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

.changeset/canvas-resize-release.md

@@ -0,0 +1,5 @@
+---
+"@sapiom/harness": patch
+---
+
+Keep canvas overview resizing responsive when the pointer is released over the embedded canvas. The drag now finishes and its height persists instead of leaving the panel stuck in resize mode.

.changeset/native-codex-delegation-startup.md

@@ -0,0 +1,5 @@
+---
+"@sapiom/harness": patch
+---
+
+Fix fresh Codex delegation waiting for a transcript that Codex creates only after the first turn. Exact owned children now receive one marked kickoff before transcript discovery, and concurrent rollouts are correlated to that runtime without crossing session identities. Retried requests preserve the same child and do not repeat its kickoff.

.changeset/studio-created-agent-membership.md

@@ -0,0 +1,12 @@
+---
+"@sapiom/harness": patch
+---
+
+Register successfully scaffolded agents immediately under their creating Studio
+project, including folders beside its root. Preserve the project's existing
+conversation when selecting those agents, and restore membership from recorded
+scaffold completions on restart without moving files or creating extra sessions.
+
+Accept native Codex timed MCP results and relative scaffold targets while preserving exact creator-path and project ownership checks. Previously recorded successful Codex completions recover membership on restart.
+
+Keep an explicitly selected archived conversation when selecting its project's created agents after restart. Remember that conversation across browser reloads only while its exact session ID remains in the server's state, without resuming a runtime, creating a session, or replaying input. Existing browser preferences remain compatible; absent or stale conversation selections use the existing live-session fallback.

.changeset/studio-onboarding-followups.md

@@ -0,0 +1,21 @@
+---
+"@sapiom/harness": minor
+---
+
+Deliver a new-agent request directly to Claude Code or Codex at startup after
+scaffolding and attachment preparation, without requiring a second Enter or
+placing internal authoring instructions in the user's prompt. Preserve project
+scope during launch and retain the composer draft when preparation fails.
+Session creation and attachment uploads each retain an independent limit of
+30 requests per minute, so uploading files does not block a new conversation.
+
+Add optional `CreateSessionRequest.initialPrompt`, `initialAttachments`, and
+`scaffold` fields, `LaunchOpts.initialPrompt` for fresh interactive launches,
+and `CREATE_SESSION_JSON_LIMIT_BYTES` for embedders configuring HTTP parsers.
+Export `PROJECT_AGENT_PROMPT_APPENDIX` and `projectAgentPromptAppendix` so
+embedders can compose Studio's shared project guidance and optional focused
+context offline without starting a server.
+
+Strengthen shared Agent Map, build-plan, and writable subsession guidance while
+keeping authoring and runtime capabilities primary. Document project-tool
+contracts and replace the known stale Studio orientation at prompt delivery.

.changeset/unified-project-agents.md

@@ -1,18 +1,28 @@
 ---
 "@sapiom/harness": minor
+"@sapiom/harness-desktop": patch
 ---
 
-Unify Studio project sessions around one ordinary coding-agent identity and
-make the project name open the shared Agent Map without starting a session.
-Conversation tabs restore their exact session and Canvas independently of the
-map and workflow Steps selection.
+Unify Agent Studio project sessions around one ordinary coding-agent identity, make the project name open the shared Agent Map, and seed new projects through a durable, retry-safe bootstrap in the first `Plan Agents` session.
 
 **Breaking for embedders** (minor while `@sapiom/harness` is pre-1.0):
 `HarnessSession.agentMapIdentity` is now the role-neutral
-`ProjectAgentSession { projectId, userId, sessionId }`. Stop branching on the
-former `role` or `assignment` fields. Valid persisted legacy metadata is
-normalized while session/provider IDs, cwd, title, transcript, and Canvas are
-preserved. Malformed or conflicting authority fails closed. Optional
-`projectBootstrap` describes lifecycle state only. Generic session routes
-revalidate project ownership on resume; migrated startup queues retain their
-durable FIFO input boundary during the coordinator transition.
+`ProjectAgentSession { projectId, userId, sessionId }`; `role` and `assignment`
+are no longer present. `AgentMapToolEvent.role` is also removed; telemetry
+consumers use neutral project/session/tool/outcome fields. Valid persisted pre-upgrade session metadata is migrated
+into the optional `projectBootstrap` lifecycle field and then removed. Retired
+project-session HTTP aliases and public API names are removed; live clients use
+the generic session routes.
+
+**Migration:** stop branching on `agentMapIdentity.role` or `.assignment`, read
+optional `projectBootstrap` only for bootstrap status, and use the generic
+session routes. An
+embedder that already owns a new session's first prompt should send
+`initialUserInputPending: true` in the same `CreateSessionRequest`, so automatic
+bootstrap yields before launch. New telemetry consumers should recognize the
+neutral `project_agent.*` and `project_bootstrap.*` events. Valid legacy state
+keeps its session/provider IDs, cwd, title, transcript, and Canvas; malformed or
+conflicting authority is retained and fails closed. Released infrastructure
+bootstrap event markers remain read-compatible so their private control prompt
+never becomes a human transcript turn after upgrade. Downgrading does not
+restore the superseded session authority model.

docs/plans/agent-studio-plan-first-agent-map/design.md

@@ -0,0 +1,69 @@
+# Agent Studio unified Agent Map
+
+## Product authority
+
+Every Studio project session is one ordinary writable project agent. Its
+trusted principal is `{ projectId, userId, sessionId }`, derived by the server.
+Assignment, map-node, and focused-brief references are context, never
+authorization. Every project session receives the same project-agent prompt,
+Agent Map tools, build-plan tools, coding surface, and delegation tool subject
+to normal project isolation and capability lifecycle.
+
+The project owns one durable Agent Map and one current project build plan.
+Sessions read and update that shared state through validated tools. A clear
+implementation request proceeds directly. Agents update the map or plan only
+when work changes architectural boundaries, ownership, contracts, resources,
+connectors, artifacts, sequencing, or cross-agent flow. Internal code choices
+remain local.
+
+## Navigation
+
+The project name selects the production Agent Map. That selection is a
+deterministic read of durable state and never creates, resumes, focuses, or
+prompts a session. Every session tab selects exactly one ordinary conversation
+and its Canvas/Steps surface. A new project starts with one ordinary session
+initially named `Plan Agents`; the name and first position grant no special
+authority.
+
+## Bootstrap and continuous maintenance
+
+Project creation durably schedules one evidence-first bootstrap turn for the
+first ordinary session when the map is meaningfully empty. Attempts, readiness,
+preemption, retry, restart recovery, and delivery correlation are durable and
+idempotent. User input remains usable and wins races without being discarded.
+Opening the map does not trigger model work. After bootstrap, the common prompt
+makes map maintenance a responsibility of every session.
+
+## Versions, briefs, and delegation
+
+Map, plan, and brief content use canonical digests and project-bound immutable
+version references. Accepted changes append a version and atomically advance a
+current pointer. Concurrent writes use exact expected versions; stale overlap
+conflicts require reread/rebase. Restoration appends a new record carrying
+`restoredFromVersionId`; history is never rewritten or rewound.
+
+Focused briefs are deterministic, bounded, exact-source context overlays. They
+focus a mission, scope, dependencies, contracts, deliverables, constraints, and
+acceptance evidence without changing prompt or tools. Sessions without briefs
+retain full capabilities and global context.
+
+Any project agent may delegate writable work. The coordinator uses stable
+project/parent/key bindings, durable spawn claims, exact session reuse,
+readiness-gated kickoff delivery, acknowledgement, bounded retention, nested
+delegation, and explicit stale-context recovery. Cleanup owns only sessions it
+created; unrelated manual sessions are never adopted or mutated.
+
+## Evidence boundary
+
+Source and runtime evidence may verify or challenge project intent but never
+silently becomes intent. The per-agent execution graph remains the authority for
+internal steps and ordinary tool calls. The project map stays at architectural
+altitude.
+
+## Security and observability
+
+Trusted scope never comes from model arguments. Capabilities are private,
+project/session-scoped, rotated on resume, revoked on exit, and rejected across
+projects. Telemetry records bounded lifecycle outcomes and identifiers only; it
+must not contain prompts, plan prose, source text, paths, credentials, connector
+payloads, or raw provider errors.

docs/plans/agent-studio-plan-first-agent-map/modules/journey/interfaces.md

@@ -0,0 +1,60 @@
+# Unified Agent Map journey interfaces
+
+## Shared identity
+
+```ts
+type ProjectAgentSession = Readonly<{
+  projectId: StudioProjectId;
+  userId: UserId;
+  sessionId: SessionId;
+}>;
+```
+
+The server derives this identity for creation, resume, bootstrap, manual
+sessions, and delegated sessions. Focus references are carried separately.
+
+## Navigation seam
+
+- Project-name selection renders `AgentMapPane` and does not change the active
+  session ID.
+- A session-tab selection activates that exact session and renders the ordinary
+  conversation plus Canvas/Steps.
+- The tab key is the durable session ID; there is one visible tab per live ID.
+
+## Map and plan seam
+
+- `GraphContentDigest` identifies canonical semantic graph content.
+- `AgentMapVersionRef` binds `projectId`, `versionId`, and `contentDigest`.
+- `ProjectAgentActorRef` records trusted user/session attribution.
+- `ProjectBuildPlanVersion` is immutable and exact-map-bound.
+- `AgentBriefVersion` is immutable and exact map/plan-bound.
+- Current reads and historical exact-version reads are distinct operations.
+- Apply/rebase/restore append before atomically advancing a pointer.
+
+All sessions discover `agent_map_read`, `agent_map_validate`,
+`agent_map_propose`, `build_plan_read`, `build_plan_validate`,
+`build_plan_apply`, `build_plan_rebase`, `build_plan_brief_refresh`, and
+`project_subsession_delegate`.
+
+## Focused-context seam
+
+A focused projection is allowlisted, deterministic, source-verified, and size
+bounded. Authored prose is delimited as untrusted data. The projection excludes
+secrets, raw evidence, local paths, connector values, unrelated history, and
+arbitrary instructions. It supplements the common project-agent prompt.
+
+## Delegation seam
+
+Delegation authority comes from the caller's private project capability. Inputs
+contain a stable request key, stable delegation key, assignment, and optional
+exact focused-context reference; they contain no trusted project/user/session
+selector. Durable claims fence creation, spawning, kickoff, acknowledgement,
+release, and restart recovery. Nested delegation uses the same interface and
+capabilities. Manual sessions remain outside coordinator ownership.
+
+## Future journey contracts
+
+Later shared-context, reconciliation, and existing-project adoption work must
+consume these neutral identity, version, brief, and session contracts. Evidence
+remains diagnostic; no later issue may add an approval or mode boundary before
+ordinary coding or delegation.

docs/plans/agent-studio-plan-first-agent-map/rollout-rollback.md

@@ -0,0 +1,39 @@
+# Unified Agent Map rollout and recovery
+
+## Release gate
+
+Ship desktop beta first. Before a tag, record the exact main SHA, changeset
+files, generated release PR, desktop package version, last known good tag, and
+the intended `vX.Y.Z-beta.N` tag. Build and smoke the packaged AppImage, inspect
+the packaged resources when runtime files changed, and walk the project-map,
+ordinary-session, direct-build, and delegation journeys.
+
+The npm path is changeset → merged version PR → publish. The desktop path is a
+tag exactly matching `packages/harness-desktop/package.json`. Stable release is
+allowed only after beta evidence and the update manifests are present.
+
+## Rollback reality
+
+There is no in-place downgrade for users who already installed a bad npm or
+desktop version. Recovery is roll-forward:
+
+1. identify and revert the faulty commit on a new branch;
+2. add a new changeset and publish a strictly higher package version;
+3. build and publish a strictly higher desktop tag;
+4. verify installers, `latest*.yml`, and blockmaps remain available for the
+   last known good and new recovery releases;
+5. use deprecation only as an installer warning, never as an unpublish plan.
+
+Deleting a tag or release cannot downgrade installed desktop applications and
+may strand the updater. `SAPIOM_UPDATE_CHANNEL` is a single-machine diagnostic,
+not fleet rollback. Record an out-of-hours approver and drill the full
+revert→changeset→version-PR→tag sequence before stable rollout.
+
+## Product-state restoration
+
+Product restoration is separate from binary rollback. A map or plan restore is
+an ordinary expected-version write. It appends a new immutable version whose
+content matches the selected historical version and whose
+`restoredFromVersionId` names that source. The previous history remains
+byte-for-byte unchanged, the current pointer advances atomically, and a stale
+restore conflicts like any other concurrent write.