fix(harness): complete project onboarding [Agent Map 15/15]

[ynadge]

Primary change type

• Bug fix

Problem and motivation

The empty-Studio journey exposed first-task delivery failures, sparse map guidance, and scaffolded sibling agents that appeared outside their originating project and lost the conversation.

Summary and scope

Prepare scaffolds and attachments server-side, pass the plain first task at CLI startup, explain the project tools, and register authenticated scaffold completions immediately under their creating project with persistent sidebar and conversation continuity.

Native Codex children submit their first owned turn before transcript creation, then use a runtime marker for exact rollout attribution. Codex scaffold results accept its timing envelope and resolve relative target paths while retaining project ownership checks. Canvas resizing keeps pointer release in the parent surface so size persists. Session creation and file uploads use independent rate-limit counters.

Created-agent navigation retains an explicitly selected stopped conversation from the same durable project and restores that display selection on reload, without implicitly resuming a process.

Public first-task request and launch fields have minor release notes. Product design, interfaces, and rollout guidance remain; internal process ledgers and the status roadmap are retained in the local evidence archive and original Git history.

How this increment fits

This completes the stack and the shared fix/studio-onboarding-followups testing branch. It contains first-request delivery, authenticated created-agent membership, tool guidance, and fixes reproduced through integrated Mac journeys.

Stack and review boundary

• Part 15 of 15 in the Agent Map review stack; review this increment against its predecessor.
• Base: review/agent-map-14-delegation-tool.
• Current head: b17c1ad0651a0a13d54a3456194bc21e1a434b35; 3,985 changed lines across 72 files, counting additions and deletions including tests.
• Repackages the corresponding final behavior from #818. Original code and review history remain preserved.
• Complete coworker testing branch: fix/studio-onboarding-followups.
• The stack remains unmerged. Dependent PRs target their predecessor, so their diffs do not repeat earlier increments.

Related work

Agent Map checkpoint SAP-3147; relevant work SAP-3147. This packaging follows the maintainer-approved 15-PR split.

Validation

Fresh local checks against b17c1ad0651a0a13d54a3456194bc21e1a434b35:

pnpm build — passed (exit 0)
pnpm typecheck — passed (exit 0)
pnpm lint — passed (exit 0)
pnpm test — passed (exit 0)

Tests and documentation

Regression coverage: First request from empty Studio on Claude Code and Codex; authenticated sibling scaffolds; active and stopped conversation continuity across agent selection, reload, and restart; nested delegation; map/plan/brief contracts; upload/session quota isolation; Canvas interactions.

The complete fix/studio-onboarding-followups testing branch at d9b62cfceb22547371fb56e8e44e3a5e21a6bb86 has exactly the same source tree as this PR (19329cb375ce26361e3375a9cfa92ee9a5280061). Final Mac validation passed: root build, 555/555 browser tests with zero retries, 11/11 Canvas tests, unsigned desktop packaging, and 13 desktop smoke checks; one Windows-only smoke check is skipped on Mac.

Both real saved-session restart journeys pass on this final tree: native IDs and sibling membership survive, history and agent navigation retain the exact stopped conversation, reload restores it, and no session or input is created. Real Claude Code and Codex first requests, authenticated sibling scaffolds, all nine project tools, map/plan conflict and replay handling, focused briefs, and child/grandchild delegation passed on the preceding integrated tree. A complete tree comparison confirms this final browser/documentation correction leaves their backend source unchanged. Original-project map and native conversation preservation were also checked during the Mac update.

Example validation and its tests, terminology, PR classification fixtures, and PR CI security checks pass on this PR head. Example installation tests passed on the Mac; their source and package inputs are unchanged by the final browser correction.

Linux tests run with ordinary user filesystem permissions; the sandbox's extra ambient capabilities are dropped. Hosted CI and automated review are separate from these recorded local results.

Compatibility and release impact

• Compatibility: The cumulative release notes document the neutral-session migration and retired planner APIs. Initial requests are prepared before CLI launch; failed preparation retains the draft.
• Changeset: Included: .changeset/canvas-resize-release.md, .changeset/native-codex-delegation-startup.md, .changeset/studio-created-agent-membership.md, .changeset/studio-onboarding-followups.md, .changeset/unified-project-agents.md

Security

• No secrets, credentials, private user data, or unsanitized logs are included.
• This PR does not publicly disclose a suspected vulnerability.

AI assistance

• Codex assembled the implementation, addressed reproduced defects, supplied tests and documentation, inspected the diff, and ran the checks above. Reviews are handled by hosted PR automation.

Checklist

• Read CONTRIBUTING.md; implementation follows the requested 15-PR split.
• Description reflects this PR's actual predecessor-relative diff.
• Relevant tests accompany the changed behavior.
• Root build, typecheck, lint, and test evidence matches the final implementation; any documentation-only update is identified above.
• Release/documentation treatment is explained above.

[github-actions]

Review — PR #834 (round 1 of 2)

🔒 CONFIDENTIALITY — internal ticket/PR-process ledgers added to the public repo

docs/plans/agent-studio-plan-first-agent-map/ is new in this PR (base docs/ had
essentially no SAP references). Three of the seven files are internal project management,
not product documentation:

• sap-3152-linear-reconciliation.md — a Linear backlog to-do list ("Mark SAP-3051 and
  children … Done", a table of which tickets to Cancel/Supersede and why, instructions for
  what the SAP-3147 final comment "should" say). Nothing here is usable by a reader of this
  repo.
• sap-3152-cutover-ledger.md — a closure gate for seven internal PRs, plus a recorded
  review exception ("SAP-3151 is frozen by explicit user direction … left one known
  cleanup-recovery finding"). It also self-references "this PR (chore(harness): complete unified agent cutover [SAP-3152] #811)", which is stale.
• sap-3152-journey-evidence.md — describes, step by step, how the autonomous-review CI
  workflow was removed from a PR's file list ("copied that workflow byte-for-byte in a
  dedicated CI commit … a no-content feature-branch merge made the shim commit an ancestor
  … This removed the workflow from the PR file list"). Publishing a recipe for getting a
  diff past this repo's own review gate is not something to ship.

Fix: keep design.md and rollout-rollback.md (they describe the shipped product); move
the three ledgers to Linear or the PR body.

🔴 The terminology CI gate now fails

scripts/agent-studio-terminology-allowlist.json replaces (does not add) the entry
legacy-project-bootstrap-store-fixture, which covered
packages/harness/src/core/project-bootstrap-store.test.ts. That file is untouched by this
PR and still contains role: "map-planner" at line 463. The allowlist matches on
entry.path === source.path (check script L491-496), packages/harness/src/core is a
static scan target (L93), the unified-agent-model rule is appliesTo: () => true, and
.test.ts files are scanned. pnpm terminology:check runs in .github/workflows/test.yml:81.

Failure: CI red with a map-planner violation at
packages/harness/src/core/project-bootstrap-store.test.ts:463. Keep the old entry and add
the new legacy-bootstrap-event-ledger one alongside it.

Public API widened with no consumer, under a patch changeset

src/index.ts newly exports PROJECT_AGENT_PROMPT_APPENDIX and
projectAgentPromptAppendix from profiles/project-agent.js. Nothing in the repo consumes
them — packages/harness-desktop has zero references, and the tests import the module
directly. Exporting the literal system-prompt text makes every future wording change a
published-API change for a capability no embedder has asked for. Keep it internal, or say
in the changeset why an embedder needs it.

Changeset levels understate what ships

.changeset/studio-onboarding-followups.md and studio-created-agent-membership.md are
both patch, but this increment:

• adds public fields CreateSessionRequest.initialPrompt / .initialAttachments /
  .scaffold, LaunchOpts.initialPrompt, and the exported constant
  CREATE_SESSION_JSON_LIMIT_BYTES — backward-compatible additions, which this repo's rule
  puts at minor;
• changes DELETE /api/sessions/:id from fire-and-forget sessionManager.kill() to awaited
  sessionManager.close() (server/rest.ts). For a delegated subsession that now records a
  user-close tombstone and persists bindings; for every session the response is delayed up
  to KILL_ESCALATION_MS + KILL_ESCALATION_CONFIRM_MS. That is a behavior change on a public
  route with no changeset line at all.

The aggregate release is minor because unified-project-agents.md is in the same batch,
so the version a consumer sees is right — but the changelog entries a consumer reads will
not mention the route change.

Session creation now shares a rate-limit bucket with file uploads

server/rest.ts:332 builds one rateLimit({ windowMs: 60_000, max: 30 }) instance and
mounts the same instance on POST /sessions (L471) and POST /sessions/:id/attach-file
(L517). One instance means one counter per key, and on a loopback server every request keys
to 127.0.0.1. Attaching ~30 files in a chat turn makes the next "new session" click return
429 for the rest of the minute. Give /sessions its own limiter.

Nits

• packages/harness/README.md lists the project tools every session receives but stops at
  build_plan_rebase; build_plan_brief_refresh and project_subsession_delegate are
  missing, and docs/shared-build-plan.md (same PR) says "all nine project tools". The
  delegation tool spawns real sessions sharing the parent's cwd — it belongs in the public
  list.
• web/src/lib/project-tree.ts defines agentBelongsToProjectRoot above the import block
  it depends on (samePath, isWithinDir are imported at L23-30).

HYGIENE (advisory)

There are now two recipes for "start a new agent from an idea". handleComposerSubmit
sends scaffold + initialPrompt on POST /api/sessions and lets the CLI own delivery,
while handleScaffoldSession (web/src/App.tsx:1884, still wired to onScaffold at
L3313) keeps the old create-then-sendPromptWhenReady path with HELD_PROMPT_TIMEOUT_MS.
Both are live UI entry points, so every future change to first-turn delivery has to be made
twice. Point onScaffold at the same server-side path.

Verdict: request changes — the terminology allowlist regression breaks CI, and the three
internal ledgers under docs/plans/ should not land in a public repo.

[github-actions]

Review — PR #834 (round 2 of 2, delta only)

Round 1's blockers are fixed: the three sap-3152-* ledgers are gone, the
legacy-project-bootstrap-store-fixture allowlist entry is back beside
legacy-bootstrap-event-* (so map-planner at
project-bootstrap-store.test.ts:501 is covered again), /sessions and
/sessions/:id/attach-file now have separate rateLimit instances
(server/rest.ts:332,338), studio-onboarding-followups.md is minor and
enumerates the new public fields and the appendix export's rationale, and the
README project-tool list now reaches project_subsession_delegate.

🔒 CONFIDENTIALITY (new) — the ledger came back as JSON

docs/plans/agent-studio-plan-first-agent-map/journey-roadmap.json is new in this
round and is the same artifact round 1 asked to remove, in machine-readable form:
five internal ticket ids mapped to internal PR numbers and head SHAs, an
unreleased epic backlog (laterWork E6/E7/E8), and — line 9 — a recorded review
exception, "review": "user-directed exception recorded in cutover ledger",
pointing at a document this PR deleted. None of it is usable by a reader of the
SDK; it is Linear state committed to a public repo. Delete the file (design.md:3
carries the same SAP status line and should lose it too); the roadmap belongs in
the PR body.

Not fixed from round 1

• web/src/lib/project-tree.ts:7 — agentBelongsToProjectRoot still sits above
  the import block supplying samePath/isWithinDir.
• HYGIENE (advisory): handleScaffoldSession (web/src/App.tsx:1892, wired at
  :3323) still runs the old create-then-sendPromptWhenReady path beside the
  new server-side initialPrompt path, so first-turn delivery has two recipes.

Round 1 got this wrong

The "DELETE /api/sessions/:id switched from kill() to close()" finding does
not hold against this head: git diff <base>..HEAD -- server/rest.ts touches no
delete handler. No changeset line is owed for it.

Verdict: request changes — drop journey-roadmap.json; everything else is
cosmetic.