0.4.17

0.4.17 — 2026-07-30

0.4.17 completes project-aware onboarding and source-grounded Project
knowledge across the shared runtime, CLI, Desktop, Dashboard, and brain.

Added

• Conversational workspace setup. Users can describe a project or start
  from a preset, review the proposed agent, capabilities, skills, tools, memory
  posture, and optional instruction change, then explicitly confirm every
  write. Bounded repository scanning provides an offline fallback.
• Two ordered onboarding flows. Provider, model, MCP, and preference setup
  remains global; project setup runs once per workspace, can be skipped without
  writing, and can be reopened from the CLI or Desktop settings.
• Typed workspace profiles. A committable, secret-free
  .brainrouter/workspace.json carries reviewed project intent while preserving
  safe forward-compatible fields and exact no-manifest behavior.
• Project knowledge. Organization- and Project-scoped knowledge bases now
  support bounded text, Markdown, HTML, PDF, and DOCX ingestion; asynchronous
  parsing and optional embeddings; status and scoped retry; hybrid retrieval;
  and source citations.
• Knowledge clients. The Dashboard Knowledge Library and Desktop Project
  knowledge panel support base creation, local upload, document status/retry,
  and citation-backed search with stale-request cancellation.
• Profile capability packs. Research, data science, study, and writing
  profiles can activate their own reviewed specialist definitions. Frontend
  remains an engineering capability and contributes design-system,
  accessibility, responsive-layout, and visual-verification skills.
• Mid-turn Queue and Steer. Desktop and CLI can visibly queue a follow-up
  behind the active turn or steer it at the next safe model boundary. Both
  delivery modes share one protocol and preserve model tool-call pairing.
• Background pull-request observation. Engineering workspaces can start a
  bounded, non-blocking watcher for checks, reviews, and comments. Material
  changes steer the originating CLI or Desktop session, allowing the active
  agent to diagnose failed CI without pausing the conversation or goal.
• Stable agent work identity. Durable plans now carry schema revisions and
  host-owned task IDs that survive rewording and reordering.
• Profile planning schemas. Engineering, research, data science, study,
  writing, and custom workspaces resolve separate validated planning artifacts,
  gates, and workflow-skill requirements. Known catalog selections are
  overridable; unknown selections fail back to the profile default.
• Reference-only Work Contracts. A revisioned session contract links plan
  tasks to requirements and future evidence/review records without copying
  their authoritative content. Existing plans migrate conservatively on read.
• Durable steering intake. When a Steer reaches the model-safe boundary,
  core records one pending Work Contract receipt with its source, prior
  revision, timestamp, and bounded summary. Delivery no longer disappears into
  prompt history before semantic reconciliation can be audited. A typed
  reconciliation step now distinguishes clarification, plan change, evidence,
  and goal conflict; extension observations remain evidence-only, and other
  tools fail closed until classification or the matching plan revision is
  stored. CLI notices and Desktop message badges expose the receipt status,
  classification, user-input requirement, and resulting plan revision through
  one shared host protocol.

Changed

• One engineering identity. engineer is the only engineering persona.
  Frontend support activates from the current task and file signals, including
  independently delegated work, without creating a second agent identity.
• Capability-aware runtime. Root and delegated agents resolve domain
  identity, capabilities, skills, tool profiles, briefing hints, and memory
  tags per task. Required profile stages now activate their declared skills in
  order, narrow the live tool surface, launch the plan-owned delegated role,
  validate its selected output sections, and unlock dependencies only after
  accepted results. Existing access mode, role, allowlist, and deny rules
  remain authoritative. CLI and Desktop now show the selected profile,
  strategy, selection source, stage owner/state, and active stage skill from
  one typed runtime event.
• Complete profile tool contracts. Research workspaces can inspect project
  folders, use Project Knowledge and Memory Context, write source-backed notes
  and artifacts, and navigate dynamic sources through a bounded interactive
  browser. Reviewed optional capabilities now activate their task-specific tool
  groups in explicit-catalog workspaces without accepting arbitrary,
  incompatible, or disabled additions.
• Profile-aware project initialization. Asking to set up a project or
  workspace now activates the selected profile's planning contract before the
  first write. Research setup language remains with the primary researcher
  instead of being misclassified as evidence collection.
• Consistent setup recommendations. Desktop source development and the
  packaged host now derive capability and tool-group choices from the same Core
  catalog. Desktop can apply all selectable recommended additions in one
  action, while CLI pickers distinguish recommended additions from selections
  already present in the workspace draft. When editing an existing workspace,
  Desktop now labels repository detection as a folder suggestion and states the
  selected profile explicitly, so an empty configured folder cannot appear to
  have silently changed profiles.
• Inspectable personality inheritance. Desktop and CLI now label the
  workspace choice as Automatic and show whether its effective communication
  style came from a global default, profile recommendation, or fallback.
• Safer contributor loop. Small PRs use focused local tests, lint, and
  typecheck; the complete hosted CI suite remains the required merge gate.
  Local full verification is reserved for cross-cutting/high-risk,
  release/publish, and CI-parity work.
• Profile-selected quality workflows. Contributor guidance now keeps
  authority invariants global while Planning, ADR, code review, and boundary
  cleanup procedures stay in focused skills. Model-neutral activation fixtures
  cover profile, task, goal, security-decision, custom-schema, and no-op paths.
• Curated browser-safe Core imports. Desktop renderer consumers now use
  focused package exports for pure catalogs, policies, graphs, diffs,
  frameworks, and prototype helpers. The compiled-path wildcard and renderer
  lint exception are removed, and extension documentation now uses the curated
  extension export.
• Smaller package boundaries. Runtime-plane configuration contracts and
  pure normalizers now live in a focused core module behind the unchanged
  configuration exports.
• Smaller worktree boundary. Worktree isolation contracts and merge-back
  presentation now live in focused Core modules behind the unchanged public
  entrypoint. Policy and recovery services now call one privileged Node host
  adapter for Git, filesystem, configuration, and state paths without changing
  isolation or merge-back behavior.
• Typed native-terminal boundary. Desktop terminal shell catalogs, session
  snapshots, and incremental reads now cross one bounded host-neutral protocol;
  Core owns deterministic geometry and reattachment policy while Electron
  retains executable discovery, environment access, native PTY allocation, and
  process lifecycle.
• Isolated background-shell host. Background command registry, polling, and
  cancellation policy now call one private host port; detached process
  creation, workspace logs, random identity, clocks, process-tree signals, and
  host-exit cleanup remain in the privileged Node adapter.
• Isolated durable-task host. Background-task transitions, filtering,
  retention, and orphan reconciliation keep their existing workspace-scoped
  API while persistence, random identity, clocks, owner PID, and process
  liveness move behind one private Node host.
• Explicit connector runtime host. Shared checkpoint policy now receives
  environment-token and current-directory context through a host-neutral
  contract while source network/filesystem clients and workspace persistence
  remain explicit adapters.
• Port-driven storage service. Workspace-scoped checkpoint and
  file-mutation persistence now sit behind an injectable port, while shared
  records and deterministic restore planning remain host-independent behind
  the existing storage entrypoints.
• Injectable execution host. Local, WSL, and SSH command validation and
  argv planning remain deterministic, while process creation and environment
  access now live behind an injected Node host adapter.
• Isolated worktree-awareness host. Passive sibling-worktree parsing and
  bounded prompt context now call an injected host; Git process creation and
  timeout remain in the private Node adapter.
• Smaller agent completion boundary. Model-answer normalization now lives
  behind a focused runtime phase while the Agent facade retains turn capture,
  hook, telemetry, usage, and transcript ordering.
• Focused agent context preparation. Pre-turn compaction, recall, prompt
  hooks, planning hints, goal and skill anchors, and child completion feedback
  now run behind one typed phase boundary before model invocation.
• Paired tool-call repair. Duplicate, truncated, scavenged, and
  storm-suppressed model tool calls now pass through a focused repair phase
  that records assistant calls and synthetic results in protocol-safe order.
• Central tool authorization. Skill, workspace, permission, access-mode,
  shell, approval, external-path, and required-workflow constraints now
  intersect in one fail-closed phase before any tool adapter runs.
• Focused tool adapters. Authorized local, orchestration, and MCP calls now
  share one typed invocation boundary for active-turn leases, lifecycle
  callbacks, managed-skill adaptation, and stable failure projection.
• Agent tool-batch phase. Parallel-safe scheduling, ordered result
  publication, interruption fill, and orphan-result repair now live behind a
  focused runtime boundary while preserving the tool-call protocol.
• Agent turn finalization. Answer capture, hooks, trace closure, usage
  accounting, telemetry, result shrinking, and termination-reason selection
  now run behind one terminal phase with the established callback order.
• Child and profile guard phase. Child auto-drain, timeout projection, and
  required profile-stage recovery now share one bounded runtime phase with
  fail-closed continuation and completion outcomes.
• Turn lifecycle coordinator. Safe-boundary steering, adaptive checkpoints,
  bounded recovery counters, verification and plan synchronization, child
  synthesis, and final-answer selection now share one host-neutral coordinator.
• Smaller onboarding contracts. Workspace transaction contracts and fixed
  storage limits now live outside the filesystem coordinator behind its
  unchanged public entrypoint.
• Explicit browser destination policy. DNS preflight, private-origin
  authority, and metadata/link-local denial now live outside Electron view
  lifecycle and remain fail-closed for agent navigation.
• Browser workspace persistence. Restorable tab locations and reviewed
  geolocation decisions now live behind an injected workspace store that keeps
  credentials, query text, fragments, and raw workspace paths off disk.
• Browser prompt manager. Permission grants, remembered geolocation
  decisions, page dialogs, timeout/cancel behavior, and prompt event ordering
  now live behind one bounded manager injected into the browser facade.
• Browser download manager. Workspace ownership, one-shot agent gesture
  leases, progress projection, item controls, safe paths, and session-listener
  cleanup now live behind an injected host port.
• Browser tab-state manager. Tab identity, ordering, active selection,
  close/reopen history, bounded snapshots, and overflow errors now live behind
  a focused live-state owner independent of Electron views.
• Browser native-view manager. Allocation, lookup, bounded console state,
  no-flash surface attachment, deterministic cleanup, and native event wiring
  now live behind an injected Electron host boundary.
• Browser agent-control manager. Workspace/chat tab authority, exact-visible
  leases, cancellation, takeover, and the shared user/agent operation queue now
  live behind one injected host boundary. Inactive agent tabs retain their own
  identity, and file uploads use the hardened cancellable staging adapter.
• Focused onboarding file integrity. Descriptor-anchored snapshots,
  bounded encodings, and exact identity/content comparisons now live outside
  transaction orchestration while preserving the existing recovery facade.
• Recoverable onboarding receipts. Bounded receipt persistence,
  validation, owner liveness, rollback, ambiguous-state preservation, and
  cleanup now live behind focused store and recovery services.
• Smaller workspace manifest contracts. The committable profile-selection
  vocabulary and fixed normalization bounds now live outside manifest policy
  and trusted filesystem orchestration behind the unchanged manifest facade.
• Pure workspace manifest policy. Profile-default resolution,
  compatibility translation, safe normalization, and bounded serialization
  now run without filesystem or onboarding-transaction dependencies.
• Focused workspace manifest storage. Fixed-path reads, guarded writes,
  compatibility diagnostics, and ordered transaction recovery now live behind
  the unchanged public manifest facade.
• Consistent assurance publication. Forge summaries and checks, the backend
  review detail, Dashboard, Desktop, and CLI now present one validated
  publication state and conclusion. Legacy review records retain their prior
  lifecycle display when no publication projection was stored.
• Deliberate deep-review hosts. Dashboard and Desktop keep diff review as
  the default and expose deep review only through an explicit manual selector.
  Both show the shared preflight, model/tool, time/cost, and context limits,
  identify coverage as bounded whole-repository, and require per-run
  acceptance before enabling Security or Code review.

Security and reliability

• Explicit deep review now requires a server-built, tamper-evident policy bound
  to the authenticated tenant, repository, program, and requester. Exact-source
  inventory and parser coverage must pass the accepted preflight before model
  work; platform/model/tool/time/cost ceilings, cancellation, one-attempt
  scheduling, and deterministic risk-ranked packet limits remain fail-closed.
  Results are labeled bounded whole-repository coverage and cannot silently
  replace ordinary diff review or authorized assessment.
• Setup proposals are read-only until confirmation, paired manifest/instruction
  writes are recoverable and stale-safe, and local paths, credentials, and
  server tenancy identifiers never enter the committable manifest.
• Knowledge authorization derives from authenticated organization membership
  and exact Project access. Local repository identity selects a Project but
  never grants access.
• Binary parsers enforce format, expansion, complexity, and byte bounds before
  persistence; normalized text is redacted before storage and parse jobs carry
  identifiers rather than source content.
• Background pull-request steering contains only normalized transition
  metadata; external titles, comments, reviews, check labels, logs, and command
  errors require explicit retrieval and remain untrusted data.
• Browser tool results are now framed as untrusted external evidence before
  model history and transcript persistence. Page-controlled console text,
  titles, URLs, filenames, and future browser observations cannot present
  themselves as policy, authorization, credentials requests, or tool
  instructions.
• Cross-host delegation pins the authenticated sender and strips untrusted
  persona, orchestration, capability, skill, tool, access, and excess-budget
  claims until a server-resolved authority profile exists. Stopping a parent
  now cascades to its owned children, records interrupted instead of
  completed, and projects one identical terminal receipt through CLI,
  headless JSONL, and Desktop.
• Work Contract writes use optimistic revisions, reject implementation-ready
  tasks without requirement/criterion/exploratory lineage, preserve unsupported
  future schemas, and accept only bounded workspace-relative affected paths.
• Authorized assessments now require a versioned, hashed policy snapshot bound
  to an active organization target, exact perimeter, immutable budget, and
  fail-closed cancellation posture; ordinary repository access cannot grant
  pentest authority.
• Authorized-assessment workspaces, including staged proxy trust material, are
  deleted after success, failure, or cancellation. Durable findings use a
  bounded secret-redacted allowlist, and a policy-driven retention sweep
  expires detailed timelines, normalized evidence, verifier payloads, and
  artifact references without changing active work or historical verdict
  counts.
• Shared Work Contract records now live in the dependency-free types package;
  core keeps persistence validation and storage behind a thin compatibility
  entrypoint instead of growing a combined contract god file.
• The Desktop renderer receives only allowlisted project/base/document/search
  views through named host queries; credentials, raw remotes, Node primitives,
  backend error bodies, and local paths remain host-owned.

Verification

• Every feature slice was squash-merged into release/0.4.17 after focused
  local evidence and its completed hosted gates were reviewed.
• Automated security reviews passed when emitted; missing automation runs were
  dispositioned only after a current-head finding/thread audit and the
  repository owner's explicit authorization.
• Live acceptance covered the isolated CLI two-stage setup, Skip/no-write,
  engineering save, edit re-entry, and deterministic model fallback; native
  Desktop onboarding/settings and responsive browser flows; the Dashboard
  knowledge workflow; and the Desktop Project knowledge panel.
• PostgreSQL/pgvector integration coverage verifies Project access isolation,
  ingest/job lifecycle, idempotent parsing, optional embeddings, scoped retry,
  hybrid retrieval, citations, provenance, and non-recursive distillation.

Breaking changes

None. Legacy frontend-builder workspace entries normalize to engineer plus
the frontend capability.

What's Changed

• fix(desktop): include agent-protocol in build:deps (desktop release workflow) by @kinqsradio in #740
• fix(desktop): pin electronVersion for the signed-build workflow by @kinqsradio in #741
• fix(desktop): dereference workspace symlinks for the signed build (3rd blocker) by @kinqsradio in #743
• fix(desktop): dereference script skips unbuilt workspace packages by @kinqsradio in #745
• chore(deps)(deps): bump the production-minor-patch group across 1 directory with 6 updates by @dependabot[bot] in #736
• chore(actions): bump actions/checkout from 4 to 7 by @dependabot[bot] in #737
• chore(actions): bump softprops/action-gh-release from 2 to 3 by @dependabot[bot] in #738
• chore(actions): bump actions/upload-artifact from 4 to 7 by @dependabot[bot] in #739
• chore(release): ship 0.4.17 by @kinqsradio in #1209

Full Changelog: v0.4.16...v0.4.17