feat(harness): establish bounded native Prime SDK session host

[rynfar]

Outcome

Add the next internal layer after #4: a bounded asynchronous Prime SDK session host that can create, attach, observe, and authoritatively dispose one client-owned native Prime session. This is a host-only contract slice. It does not register a Comet harness or expose a user-visible provider.

Parent umbrella: #1
Merged daemon foundation: #3 / #4
Prime SDK ingress dependency: pylon-code/prime-agent#13
Prime reviewed-upstream gate: pylon-code/prime-agent#8
Prime snapshot/worker-integrity gate: pylon-code/prime-agent#11
Pylon consumer: pylon-code/pylon#114

Dependency gate

Production session-host work is blocked on the reviewed public proof/options contract produced by Prime zeronsh#13, which must let Comet enforce a finite inbound byte limit before DaemonClient connects. The exact export and constructor contract must be cross-reviewed on zeronsh#13; do not pre-decide it here. Never infer safety from package version, branch, constructor arity, method presence, daemon schema, or server capability. Stock 0.8.1 must fail locally before session creation because its public client attaches the JSONL reader without a limit.

Prime zeronsh#8, zeronsh#11, and zeronsh#13 are all prerequisites to the production merge and real smoke. The reproducibly identified fork artifact must contain one reviewed Prime tracker head with the accepted outcomes from all three; this issue does not prescribe their internal merge order. Deterministic fake-SDK infrastructure may be developed earlier, but it cannot be presented or merged as a production session path.

This slice still keeps reconnect/recovery disabled. zeronsh#11 is required here because even the initial attach consumes snapshot transfer and this issue claims authoritative worker/descriptor settlement; reconnect and saved-session recovery remain separate later work.

Contract

• Continue loading only the already validated public root ESM export.
• Require DaemonClient, DaemonAgentConnection.attach, and the reviewed public bounded-ingress proof/options contract from Prime Interest in adding Grok Build support? zeronsh/comet#13.
• Construct the client with a reviewed finite inbound byte limit before connecting, and verify support through that explicit public contract rather than an ignored extra JavaScript argument.
• Use one long-lived asynchronous Node host with correlation IDs that separately demultiplexes command responses and unsolicited session events. Never reuse the foundation bridge's request/next-line bootstrap shape.
• Create a client_owned session with a bounded, allowlisted runtime config rooted in the local working directory and private Prime session tree.
• Validate the create result before attach. Use ownedSession: true, disable reconnect for this slice, and set supportsExtensionUi: false until Comet implements that request/response surface.
• Let the public DaemonAgentConnection advertise its documented attach-side capabilities. A daemon hello offer alone never proves the negotiated intersection.
• Keep correlated prompt lifecycle inactive and unexposed in Comet even if the fork SDK internally auto-advertises it after seeing a server offer. supportsCorrelatedPromptLifecycle() is server-offer evidence only. A later prompt issue needs an approved public negotiated-capability proof before it can use the extension.
• Obtain and validate the initial snapshot/cursor without publishing raw Prime payloads.
• Expose only a non-serializable internal PrimeSessionLease and bounded normalized host events. activeSessionId, native sessionId, sessionFile, socket paths, package paths, environment values, and raw payloads must remain inside crates/harness/src/prime/**.
• Never place a native Prime identifier in RunRequest.resume, AgentEvent::*::session_id, a Comet document, RPC, log, or error. Durable resume needs a later opaque Comet-handle-to-local-Prime mapping design.

Lifecycle and process ownership

• Bound every host command, frame, pending-request count, event queue, startup, attach, snapshot, disposal, and child-process wait.
• Isolate the SDK host with an explicit environment, finite V8 heap, owned process group, cancellation handoff, and privacy-safe typed errors.
• If creation succeeds but attach or caller cancellation fails, issue bounded complete_owned_session cleanup.
• Normal close must obtain a validated successful owning-client complete_owned_session response before DaemonAgentConnection.dispose(), then close the client and reap the SDK host. dispose() alone is not proof because it swallows completion errors. A successful supervisor response is meaningful only because it awaits worker stop, removes the worker, and deletes its descriptor.
• Dropping or cancelling a Rust future must transfer both the SDK-host process and any created native-session cleanup obligation to a bounded reaper. Killing only the Node host is not proof that a detached Prime worker stopped.
• On SDK-host crash, a different bootstrap client cannot complete the session because the supervisor enforces ownerClientId. The reaper must wait for the daemon's client-disconnect cleanup and prove the worker/descriptor is absent. If it cannot prove absence, poison and shut down this private daemon and return cleanup-uncertain; never report clean disposal.
• Do not shut down the daemon while a session lease is live except for that fail-closed poisoned-owner recovery. Reconcile worker/descriptor state before reporting clean disposal.

Tests

Use deterministic local fake public-SDK/daemon fixtures with no model, credential, network, or active Prime checkout dependency. Cover:

• response/event interleaving, reverse-order concurrent responses, and event-before-response;
• duplicate, unknown, and stale response IDs; EOF/overflow rejecting all waiters; close/cancel overtaking an in-flight operation rather than waiting behind a global promise queue;
• reviewed bounded-ingress proof/options contract required before create;
• constructor byte limit forwarded to the SDK;
• stock server offers versus attach-side client capability advertisement;
• create/attach/initial snapshot success;
• unknown events and capabilities degrading locally without raw forwarding;
• oversized/no-newline control frames and bounded event queues;
• timeout and cancellation at connect, create, attach, snapshot, and dispose;
• attach failure after create invokes owning-client complete_owned_session and validates the response;
• host crash waits for client-disconnect cleanup and proves worker/descriptor absence; unverifiable cleanup poisons/shuts down the daemon and returns cleanup-uncertain;
• graceful and forced SDK-host descendant cleanup;
• native identifiers and raw payloads absent from surfaced events/errors;
• authoritative owned-worker/descriptor settlement before success;
• a real smoke only against the exact reviewed artifact containing Use native word-editing shortcuts on every platform zeronsh/comet#8/Add workspace file mentions to the composer zeronsh/comet#11/Interest in adding Grok Build support? zeronsh/comet#13.

Initial ownership

No branch or worktree is claimed yet. After the dependency gate is satisfied, use a fresh Comet worktree from origin/main and declare the exact branch, files, tests, dependencies, and merge order here before editing.

Expected area: crates/harness/src/prime/session/**, a dedicated session-host shim, focused changes to the existing Prime foundation seams, and focused tests only.

Non-goals

• HarnessId::PrimeAgent, registry/settings/model/UI integration
• prompts or assistant streaming
• steering, follow-ups, interruption, or correlated prompt settlement
• extension UI, MCP, resources, compaction, refinement, goals, heartbeats, or schedules
• reconnect, resume, snapshot recovery, or cross-device session migration
• native subagent projection
• sandbox or approval policy (loading Prime runtime resources is not supervision)
• ACP fallback

Merge order

1. Record one reviewed Prime tracker head containing the accepted Use native word-editing shortcuts on every platform zeronsh/comet#8, Add workspace file mentions to the composer zeronsh/comet#11, and Interest in adding Grok Build support? zeronsh/comet#13 outcomes, then produce a reproducibly identified artifact. The exact internal Prime merge order is owned by that tracker.
2. Implement this host-only Comet slice and cross-review the public SDK contract with both Comet and Pylon consumers.
3. Add prompt/event normalization in a separate Comet issue; reconnect and recovery remain disabled until their own contract review.
4. Design the host-private opaque resume mapping before HarnessId::PrimeAgent registration.

Acceptance

• Deterministic tests prove asynchronous response/event demultiplexing and authoritative client-owned cleanup.
• A real smoke against the exact reviewed fork artifact containing Use native word-editing shortcuts on every platform zeronsh/comet#8/Add workspace file mentions to the composer zeronsh/comet#11/Interest in adding Grok Build support? zeronsh/comet#13 proves create/attach/snapshot/authoritative-dispose without a model prompt.
• No native identifier or raw Prime state crosses Comet's private module boundary.
• The issue contains exact files, artifact provenance, test receipts, and review outcomes before merge.

[rynfar]

Contract review complete: no remaining scope blockers.

The issue intentionally remains unclaimed and code-blocked. The implementation claim must wait for one reviewed, reproducibly identified Prime artifact containing the accepted zeronsh#8/zeronsh#11/zeronsh#13 outcomes. At that point the claim/PR must name the exact public evidence used after an owner-client crash to prove worker/descriptor absence; if Prime exposes no authoritative proof, the safe result is fail-closed shutdown of this issue's private one-session daemon or a Prime API blocker—not weaker cleanup claims.

The issue remains host-only: no HarnessId, prompts, correlated lifecycle use, reconnect, resume, sandbox/approval policy, or synchronized native identifier.

[rynfar]

Prime dependency milestone: Prime PR #14 merged at fd5cadc600f867a0a5a989064cce22934e9dad94, closing Prime zeronsh#11. It provides the reviewed capability-gated snapshot/recovery and authoritative owned-session cleanup contracts required by Comet's native daemon host.

The remaining safe-host order is unchanged:

1. regenerate and merge Prime Use native word-editing shortcuts on every platform zeronsh/comet#8 from exact post-Add workspace file mentions to the composer zeronsh/comet#11 pylon;
2. implement/review bounded public ingress in Prime Interest in adding Grok Build support? zeronsh/comet#13;
3. claim and implement Comet feat(harness): establish bounded native Prime SDK session host #5.

The fresh zeronsh#8 regeneration is now active from Prime a903d4b6768f484bd6d459b7b0aa7dee38e461e2. Comet #5 remains deliberately unclaimed; no native session IDs, paths, credentials, or process details are exposed.

[rynfar]

Prime upstream governance gate #8 is complete. PR #15 merged as e7871eb699d0f65047a21d179216ebfec7755d0c after exact-head reviews, zero conversations, and all trusted hosted jobs passed.

Bounded public ingress Prime #13 is now claimed from exact merged pylon at e7871eb699d0f65047a21d179216ebfec7755d0c in an isolated worktree. The declared client-local feature proof/raw-byte limit/error/reconnect contract is under the final joint Prime/Comet design review before source edits.

Dependency order is now: zeronsh#15/zeronsh#8 (done) → zeronsh#13 (active) → Comet #5.

[rynfar]

Prime bounded-ingress candidate is now ready as PR #16 at exact head 9013a63a76fa339b5e2898947e9cff040505d72c / tree 814cfa93bfdbab0d43acaa92c208205fd7dd5749 on base e7871eb699d0f65047a21d179216ebfec7755d0c.

Three commit-bound reviews approved with no P0/P1: transport security, API/resource/governance, and Comet consumer compatibility. Local validation includes 53 focused tests, 13 real-process passes with 8 fixture skips, both stock/current 0.8.1 adoption directions, the 36 MiB indivisible message, deterministic 100/500 MiB bounded-client reconstruction, and exact 64/128 MiB resource probes.

Trusted exact-head hosted CI is running. Comet #5 remains blocked until PR zeronsh#16 passes CI, has no unresolved conversations, receives exact head/base maintainer approval, and merges into pylon.

[rynfar]

Dependency gate satisfied: Prime PR #16 merged into pylon as 7238ac8cff25962ada9ffe4530b7d4d1cddc1b47 with parents e7871eb699d0f65047a21d179216ebfec7755d0c + 9013a63a76fa339b5e2898947e9cff040505d72c and reviewed tree 814cfa93bfdbab0d43acaa92c208205fd7dd5749. Prime zeronsh#8, zeronsh#11, and zeronsh#13 are now present in one exact tracker head.

I am claiming this slice before editing:

• branch: feat/prime-session-host-7238
• isolated worktree: /Users/rynfar/.prime/worktrees/comet-prime-session-host-7238
• base: origin/main@de66c08c3687208effe2e2fdb514d6d690f1cc0a

Declared production files:

• new crates/harness/src/prime/session/{mod.rs,contract.rs,host.rs,host.mjs};
• focused seams in crates/harness/src/prime/{mod.rs,process.rs,paths.rs,shim.mjs,contract.rs,error.rs};
• new crates/harness/tests/prime_session.rs and crates/harness/tests/support/prime_session_fixture.rs;
• focused crates/harness/tests/support/mod.rs and existing Prime fixture/test changes only if a shared foundation seam requires them.

No harness registry, protocol, engine, document, RPC, settings, model, or UI file is owned by this slice. I will post any file-set expansion before editing it.

Implementation order:

1. produce and hash a clean exact-merge Prime artifact;
2. add the bounded asynchronous fake-SDK host/fixtures and deterministic lifecycle tests;
3. implement the private Rust/Node session owner and cleanup reaper;
4. run the real no-model smoke against the exact merged artifact;
5. obtain independent security/concurrency and consumer/API reviews before opening a PR.

Contract clarifications from the pre-implementation review:

• DaemonAgentConnection.attach means the public instance attach() on a directly constructed connection. The static convenience helper is not used because on attach failure it disposes and swallows owning completion errors; Comet must validate its own explicit complete_owned_session response.
• This slice creates and immediately attaches only its own fresh session. It does not attach arbitrary saved sessions. Per-frame ingress is 64 MiB, snapshot has a deadline, the isolated host uses --max-old-space-size=512, and any OOM/host crash transfers cleanup and fails closed. A future arbitrary-session/recovery slice must first add an explicit cumulative snapshot budget if it needs graceful pre-assembly rejection.
• If create may have committed before its native ID crosses the private host boundary, Comet cannot prove exact cleanup. It poisons and shuts down the one-session private daemon and returns cleanup-uncertain rather than claiming clean settlement.

Correlated prompts, reconnect/recovery, saved-session attach, prompts/streaming, registry/UI, and all other stated non-goals remain out of scope.

[rynfar]

Exact merged Prime artifact prepared for the later real smoke:

• tracker commit: 7238ac8cff25962ada9ffe4530b7d4d1cddc1b47
• parents: e7871eb699d0f65047a21d179216ebfec7755d0c + 9013a63a76fa339b5e2898947e9cff040505d72c
• tree: 814cfa93bfdbab0d43acaa92c208205fd7dd5749
• public release package: prime-agent-0.8.1.tgz
• SHA-256: d6065af7b7eb0bf8bb945d84618c4d06fecea66cf3d07ed75737310b447913cc
• internal release dependencies:
  • prime-agent-ai-0.8.1.tgz b3f1b9218b489a93c2008ed1fad73074bb552acb15b6fe8400001417e4ea5d99
  • prime-agent-core-0.8.1.tgz d1b04c7d89d830a882791e0464e8b2c78dc92329d91c2c04b91d0cb6ac508060
  • prime-agent-tui-0.8.1.tgz bd07bccee0ca495565b1d62e9411f3fdebe49e3dfa52870564f08af5e61fde15

Receipt: a detached exact-merge worktree used native npm ci; after the catalog-generating root build, packages/ai/src/models.generated.ts was restored to the exact commit and AI plus coding-agent were rebuilt from committed source. The repository release packer produced the branded prime-agent/prime-agent bin artifact twice with identical SHA-256 values. An isolated install from the four local tarballs succeeded. The installed public root reports version 0.8.1, protocol 7, a frozen PRIME_AGENT_SDK_FEATURES containing only bounded_daemon_ingress_v1, and public DaemonClient/DaemonAgentConnection constructors. The exact artifact worktree is clean.

This is artifact provenance only, not the required Comet create/attach/snapshot/dispose smoke; that smoke remains pending the session host implementation.

[rynfar]

File-set expansion before documentation edit: add docs/prime-agent-integration.md to this branch. The focused update will record the delivered host-only session boundary, exact bounded_daemon_ingress_v1/64 MiB/512 MiB contract, authoritative cleanup proof, stock fail-closed behavior, private-data boundary, and explicit non-goals. No user-visible provider or registry claim will be added.

[rynfar]

Exact candidate opened as PR #6: #6

Commit-bound candidate:

• base de66c08c3687208effe2e2fdb514d6d690f1cc0a
• head 3ba88e519d2b062dc705a4e17629ac135d286020
• tree bb5b90da8c098ac595a4b79afbda5ee4513d3d15

The first review pass blocked the old head on poison-horizon, reaper-startup, UTF-8 serialization, and fake shutdown/coverage P1s. All were repaired. Fresh exact-head security/concurrency, API/privacy/consumer, and adversarial-test reviews now each report no P0/P1. Any head change invalidates those approvals.

Validation at this head: 36 Prime unit; 24 deterministic session (+2 env-gated ignored); 23 daemon (+1 env-gated ignored); exact reviewed-artifact and stock-negative gates pass; wider harness passes with the identical main/candidate shell_env baseline excluded; focused clippy, Rust 2024 rustfmt, Node syntax, privacy/scope, whitespace, and process/socket/descriptor leak scans pass.

Receipts:

• validation b31279d53828b9b0a91aea54bde73d2922e85bc50fca83295ea7e1d60a1ca445
• Prime artifact d6065af7b7eb0bf8bb945d84618c4d06fecea66cf3d07ed75737310b447913cc
• 1,436-file install verification 6e45ce08d50241ee9e8c1ba45e85f4b6a894c3532b6bae06f7c99c7380f3c12e

Trusted hosted release-build CI is running at https://github.com/rynfar/comet/actions/runs/33298602520, bound to exact head 3ba88e519d2b062dc705a4e17629ac135d286020. PR #6 must remain unmerged until required hosted jobs pass, conversations are clear, and exact-head approval is recorded.