feat(harness): compile role-neutral focused briefs

[ynadge]

Primary change type

• Bug fix
• Documentation
• Feature
• Tests
• Dependency update
• Maintenance or refactor

Problem and motivation

Project agents need bounded task context without creating a separate builder identity or turning brief freshness into implementation authority. SAP-3150 adds deterministic focused briefs over the exact role-neutral Agent Map and project-plan versions introduced by SAP-3149.

Summary and scope

• Compile canonical workstream and ad-hoc/nested delegation briefs from independently verified exact map and plan histories.
• Preserve stable scope/brief identities, append immutable affected versions, retire safely, and reactivate against retained history.
• Evaluate categorized, targeted impact while preserving unaffected brief versions.
• Project allowlisted brief data through an escaped, deterministic, size-bounded untrusted-data overlay on the common project-agent prompt.
• Refresh briefs independently and idempotently after plan apply/rebase, with a universal explicit retry tool and content-free telemetry.
• Export the neutral contracts and add compiler, lifecycle, projection, MCP integration, prompt, and public-surface coverage.

Session creation and delegation are intentionally out of scope for SAP-3151. This change does not alter tools or authority for sessions without a brief.

Related work

Related issue or discussion: SAP-3150

Stacked on #806 / conductor/sap-3149-neutral-plan-versions-v1 at 90eb569eb6b90b917c49128b6a23c7215a0843d6.

Validation

pnpm build — passed
pnpm typecheck — passed
pnpm lint — passed (existing warnings only; zero errors)
pnpm test — reached the reproducible unrelated agent-core chmod/filesystem-capability failure in src/bundle-error.spec.ts; 17/18 agent-core suites and all preceding package suites passed
pnpm --filter @sapiom/harness test — passed: 218 files / 3,532 tests and 3 performance files / 10 tests
focused compiler/canonicalization/codec/service/MCP tests — passed throughout each implementation slice

Tests and documentation

Added deterministic compiler golden/tamper/lineage tests; canonical and nested focus tests; targeted impact tests; retirement/reactivation and refresh-replay tests; malformed graph, boundary, prompt-injection, redaction, truncation, no-brief compatibility, common-prompt overlay, MCP, and public-export tests. Updated packages/harness/docs/shared-build-plan.md.

Compatibility and release impact

• Breaking or externally visible changes: Adds public role-neutral focused-brief compilation, impact, projection, and refresh APIs plus the universal build_plan_brief_refresh MCP tool. Existing no-brief sessions preserve their prompt and tool authority.
• Changeset: Added a minor @sapiom/harness changeset.

Security

• I have not included secrets, credentials, private data, or unsanitized logs.
• This pull request does not publicly disclose a suspected vulnerability. I
  will follow the
  Security Policy for
  private reporting.

AI assistance

• I did not use AI assistance for this change.
• I used AI assistance and have described it below.

OpenAI Codex implemented the focused-brief compiler, lifecycle, projection, service/MCP integration, documentation, and tests. I verified the exact stacked ancestry, reviewed the complete diff and forbidden legacy terminology, and ran the build, typecheck, lint, focused, full Harness, and root test commands reported above.

Checklist

• I read CONTRIBUTING.md, and this contribution follows the direct-PR or issue-first policy.
• This pull request addresses one focused problem and contains no unrelated cleanup.
• I added or updated tests, or explained above why tests are not applicable.
• I ran the relevant build, typecheck, lint, and test commands, or explained
  any N/A checks above.
• I updated documentation for user-facing changes, or marked it N/A above.
• I added a Changeset for a published-package change, or explained why it is not applicable.
• I can explain and maintain every submitted change, including any AI-assisted work.

[github-actions]

Review — PR #807 (round 1)

1. Compiled brief content can violate the persistence codec's bounds, and the failure is reported as retryable

packages/harness/src/core/agent-brief-compiler.ts:518 and :417

The compiler seals briefs whose content the store's own codec then rejects. Two triggers:

• deliverables is never bounded. When a workstream has no cross-boundary outputs
  (projection.outputs.length === 0 — a single-agent map or a leaf agent, i.e. the bootstrap
  shape), deliverables becomes [mission]. mission is allowed 4096 chars by both
  build-plan-schema.ts:109 and parseBriefContent, but build-plan-codec.ts:241 enforces
  boundedStrings(deliverables, 2_000).
• bounded() counts code points; the codec counts UTF-16 units. [...value].length
  (line 418) vs value.length in isAgentMapBoundedText (agent-map-codec.ts:38). A
  relationship description with astral characters (emoji) passes the map codec at ≤2000
  units, but format()'s canonical JSON of it can be ≤2000 code points and >2000 units —
  bounded() leaves it untouched and boundedStrings(inputs, 2_000) rejects it.

Failure path: parseAgentBriefVersion throws a plain Error
(agent-map-workspace-store.ts:313), not an AgentMapWorkspaceStoreError, so
AgentBriefService.refresh (agent-brief-service.ts:195-201) maps it to
storage_unavailable → MCP recovery: "retry". Retrying is deterministic and will never
succeed: canonical brief refresh is permanently wedged for that project while the agent is
told to retry. No test compiles a brief with a >2000-char mission or astral text and
round-trips it through appendBriefVersions.

Separately, bounded() truncates entries that are canonical JSON objects, so an over-limit
inputs/outputs/dependencies entry becomes a broken JSON fragment in the projection.

2. Ad-hoc delegation scope is unbounded — a nested brief can own another workstream's nodes

packages/harness/src/core/agent-brief-compiler.ts:326-357

For family: "ad-hoc-delegation", root comes from requestedAssignment.plannedAgentId
whenever assignmentId is supplied, and ownedNodeIds comes from nodeIds — with no check
that the two agree. Supplying assignmentId for workstream A plus nodeIds belonging to
workstream B yields a sealed brief with plannedAgentId: A and ownedNodeIds: B's nodes, and
no diagnostic (the roots.length > 1 guard is skipped once requestedAssignment is truthy).
parentScopeKey is carried in the scope identity but never validated to exist or to constrain
the child's selection (grep parentScopeKey — identity and codec only).

Reachable from build_plan_brief_refresh with focus.mode: "focused", so any project session
can mint a brief that projects a sibling workstream's nodes, contracts and shared resources as
its own owned scope. Briefs are context-only, but "bounded task context" is this PR's thesis
and the projection is what the model reads.

3. The doc contradicts itself, and the changeset omits the apply/rebase behavior change

packages/harness/docs/shared-build-plan.md:57 still asserts "plan apply and rebase never
invoke a compiler or mutate brief pointers." Lines 66-68 of the same file, and
agent-map-mcp-tools.ts:267-300, do exactly that. Update the stale paragraph.

.changeset/focused-project-briefs.md also doesn't mention that build_plan_apply and
build_plan_rebase now write brief history and gained a briefRefresh field in their result.
An embedder driving those tools sees a behavior and payload change described only as
"add … lifecycle refresh". Name it in the changeset body.

4. Every plan apply now re-hashes the project's entire map and plan history

packages/harness/src/core/agent-brief-compiler.ts:159-230

verifyExactSources recomputes computeGraphContentDigest + record digest for every entry
in mapHistory and both digests for every entry in planHistory on every refresh. History
is capped at BUILD_PLAN_VERSION_HISTORY_LIMIT = 1_024 and never pruned, so that is up to ~4k
full canonical-JSON SHA-256 passes. compile() then calls indexGraph() plus two linear
mapHistory/planHistory.find() scans per previous brief (up to 128). Since
build_plan_apply/build_plan_rebase now invoke this inline, a long-lived project pays it on
every plan edit inside an interactive tool call. Verifying only the versions actually
referenced (current + each previous brief's map/plan) would be O(briefs), not O(history×briefs).

5. The focused-context overlay is public API with no producer

serializeFocusedSessionContext, FocusedSessionContextProjection, the three
FOCUSED_SESSION_CONTEXT_MAX_* constants and projectAgentPromptAppendix are exported from
src/index.ts, and focusedContext is threaded through TrustedSessionCreateOptions/
TrustedSessionResumeOptions — but nothing in the harness ever supplies it (only
served-system-prompt.test.ts:120). The changeset advertises "bounded prompt-safe context
projection" with no documented way for a consumer to attach one. Either keep the projection
internal until SAP-3151 wires it, or document the entry point in the README/JSDoc.

Related footgun: server/index.ts:634 applies the overlay only inside the
context?.agentMapIdentity branch, so focusedContext passed for a non-project session is
silently dropped rather than rejected.

Nits

• sensitivePath requires (?:^|[\s"']) before the path, so see:/home/x or (/Users/x) are
  not redacted — the doc's "sensitive/path-like values are redacted" over-claims.
• boundedString sets truncated = true on redaction, so any redacted brief reports
  outcome: "truncated" and a context-truncated diagnostic. Wrong category.
• replay() (agent-brief-service.ts:227) hardcodes disposition: "unchanged" and
  emptyImpact(), so a retried refresh reports no impact even when the original run created
  or retired briefs.

Verdict: Request changes — finding 1 makes canonical refresh permanently unrecoverable for
reachable content (long mission, or emoji in a relationship description) while telling the
agent to retry, and finding 2 lets a delegation brief claim scope it doesn't own. No
confidentiality issues: the changeset, doc and fixtures are role-neutral and name no company
other than Sapiom.

[github-actions]

Review — PR #807 (round 2, delta since 5fc174d7)

New finding — brief-append receipts never expire, and exhaustion is reported as retryable

packages/harness/src/core/agent-map-workspace-store.ts:338, agent-brief-service.ts:214

build_plan_apply/rebase now write a brief_append receipt per plan mutation, but unlike
plan receipts (build-plan-service.ts:609-620, which expire into tombstones) brief_append
receipts are only ever pushed. At PROJECT_MUTATION_RECEIPT_LIMIT (1,024) every further
append throws storage_unavailable → AgentBriefServiceError("storage_unavailable") →
MCP recovery: "retry" (agent-map-mcp-tools.ts:111). Retrying can never succeed: brief
refresh is permanently dead for that project while the agent is told to retry — the same
shape as round-1 finding 1, through the receipt table instead of the codec. This round also
makes each of those 1,024 receipts multi-KB (full briefs + impact + diagnostics are now
persisted for replay), and the aggregate is rewritten wholesale on every mutation.
AGENT_BRIEF_VERSION_HISTORY_LIMIT per brief has the same terminal behavior. Either expire
brief receipts like plan receipts, or surface quota exhaustion as a non-retryable code.

Earlier findings

1, 2, 3, 4 fixed. Bounds now count UTF-16 units and cover deliverables and the canonical
record entries (which stay parseable JSON), the store maps parse failure to malformed_state
and the service pre-validates; ad-hoc scope requires the selected nodes' root to equal the
assignment's plannedAgentId and validates parentScopeKey against an active parent;
re-hashing is limited to referenced versions and history scans are memoized; doc and changeset
updated. All three nits fixed.

5 partially fixed: focusedContext is now rejected outside a project-agent identity and
the host contract is documented (shared-build-plan.md:81-87), but nothing in the repo still
produces a projection — the exported surface stays consumer-only until SAP-3151.

Nits

• profiles/project-agent.ts:18-19 — two consecutive JSDoc blocks; the first is orphaned.
• The resume-path rejection (session-manager.ts:1344) has no test; only create does.

Verdict: Approve with one change — the round-1 blockers are genuinely closed; the
never-expiring brief receipt table reintroduces a permanent "retry" wedge.

[ynadge]

/review

[github-actions]

Review — PR #807 (round 3, delta since 28e90a94)

One commit (13e99e15). The round-2 blocker is closed: brief_append receipts now expire
into tombstones at a 256 retention limit — the same shape as
build-plan-service.ts:611-621, and 3 × 256 categories stay under the 1,024 receipt
quota — and every remaining durable-bound exhaustion (per-brief history, receipt table,
tombstone table) raises AgentBriefAppendQuotaError → AgentBriefServiceError("quota_exceeded")
→ MCP recovery: "manual_intervention" and briefRefresh.outcome: "manual_intervention",
so the "retry forever" wedge is gone. AgentBriefAppendQuotaError propagates unwrapped
through locked(); a failed append aborts before next is persisted (the new MCP test
asserts the plan still commits). Both round-2 nits are fixed, including a resume-path
rejection test that runs before the status mutation and authority claim.

No new findings.

Still open from earlier rounds

• Round-1 chore: update URLs, defaults, and LangChain v1.x docs #5 (partial, unchanged): serializeFocusedSessionContext /
  FocusedSessionContextProjection / projectAgentPromptAppendix remain exported with no
  in-repo producer until SAP-3151. Documented host contract; accepted deferral, not a bug.

Nit

• docs/shared-build-plan.md:39-43 bounds only "map and plan histories" at 1,024 and the
  brief section still says refresh "can be retried independently and idempotently" —
  AGENT_BRIEF_VERSION_HISTORY_LIMIT is also 1,024 and terminal, and brief receipts now
  expire (a reused old requestId returns request_id_expired, not a replay). One
  sentence in the brief section would match what the changeset now promises.

No confidentiality issues: the changeset addition is role-neutral and names no company
other than Sapiom.

Verdict: Approve.

[ynadge]

Superseded by the maintainer-authorized 15-part Agent Map review stack. This PR is closed without merging; its branch and review history remain preserved.

Replacement increments:

• Part 11/15: feat(harness): compile focused context [Agent Map 11/15] #830 — feat(harness): compile focused context

The complete testing branch remains fix/studio-onboarding-followups. Full stack: #819 through #834. Final hosted-review corrections and Mac journey validation are continuing on those same replacement PRs.