feat(session): migrate incompatible daemons safely

[benvinegar]

Stack

#932 → 2 of 3 → #934. Merge bottom-to-top.

Problem

Hunk windows and one-shot session commands need authenticated access to the shared local daemon. Upgraded interactive windows must recover from an incompatible incumbent without trusting health metadata or terminating a process that may still own live sessions.

Approach

• create owner-private Hunk daemon, producer, and caller credentials;
• authenticate producer WebSockets and session CLI controls while keeping browser-review capabilities independent;
• expose public health as exactly { "ok": true } and remove PID-based replacement;
• keep one SessionBrokerConnection across daemon generations so queued/executing command budgets and registration state remain stable;
• use health-only quiescent waiting, with launch metadata only as a generation-change hint before a signed hello establishes authority;
• let compatible upgrades reuse the incumbent, interactive windows self-heal after idle retirement, and one-shot commands fail promptly with actionable guidance;
• preserve one daemon per immutable Hunk application contract.

Forced handoff, coordinator endpoints, random ports, remote hosts, and updater-controlled daemon lifecycle remain non-goals.

Verification

• bun run typecheck
• session-focused Bun tests — 329 passed
• bun run deps:check
• bun run changeset:status
• git diff --check
• stack-wide full unit suite — 1,754 passed, 9 skipped
• stack-wide PTY suite — 137 passed, 1 platform skip

No visual evidence is included because this changes session lifecycle rather than terminal rendering.

Known limitations

Hung or idle-disabled incompatible incumbents still require manual termination. Native Windows credential-path validation and durable key rotation remain publication gates.

This PR description was generated by Pi using gpt-5.6-sol

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hunk-web	Ignored	Preview	Aug 30, 2026 11:33pm

[greptile-apps]

Greptile Summary

The PR authenticates local session producers and CLI controls, minimizes public daemon health, and replaces unsafe PID-based daemon migration with quiescent authenticated reconnection.

• Adds persistent owner-private daemon, producer, and caller credentials.
• Signs and authorizes session API requests and producer WebSocket handshakes.
• Makes incompatible windows wait for daemon succession and reconnect automatically.
• Updates daemon lifecycle, CLI behavior, documentation, and integration coverage.

Confidence Score: 4/5

The PR appears safe to merge, with only a non-blocking environment-access consistency issue in the launch-fingerprint helper.

The authenticated migration and request-routing paths are coherently tested; the remaining accepted concern is that one new helper bypasses the repository's validated environment configuration boundary.

Files Needing Attention: src/session/broker/brokerLauncher.ts

Important Files Changed

Filename	Overview
src/session/broker/credentials.ts	Adds persistent Ed25519 credential creation and strict owner-private loading with atomic per-file publication.
src/session/broker/brokerServer.ts	Adds authenticated session controls, producer handshakes, scoped authorization facts, and minimal public health.
src/session/broker/brokerClient.ts	Replaces PID-based daemon termination with authenticated compatibility detection and quiescent reconnect behavior.
src/session/agent/cliClient.ts	Routes CLI capabilities and actions through the signed caller client while retaining bounded request handling.
src/session/broker/brokerLauncher.ts	Moves Unix fallback runtime state beneath the user home and adds bounded launch-generation fingerprints, with one environment-access convention violation.
src/session/agent/commands.ts	Refuses incompatible daemon actions with migration guidance rather than terminating and replacing a daemon by PID.

Sequence Diagram

sequenceDiagram
  participant Window as Hunk window
  participant Incumbent as Incompatible daemon
  participant Successor as Successor daemon
  participant CLI as Session CLI
  Window->>Incumbent: Signed producer hello
  Incumbent-->>Window: Pre-auth compatibility refusal
  Window->>Window: Wait for daemon generation change
  Incumbent-->>Incumbent: Exit when quiescent
  Window->>Successor: Signed producer hello
  Successor-->>Window: Authenticate and register session
  CLI->>Successor: Signed capabilities request
  Successor-->>CLI: Signed capabilities
  CLI->>Successor: Authorized session action
  Successor-->>CLI: Signed result

Loading

Prompt To Fix All With AI

### Issue 1
src/session/broker/brokerLauncher.ts:418
**Direct environment access**

The new `readSessionBrokerLaunchFingerprint` parameter defaults directly to `process.env`, bypassing the repository's validated environment configuration boundary and making configuration behavior harder to validate and test consistently.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "feat(session): migrate incompatible daem..." | Re-trigger Greptile}

[greptile-apps]

Direct environment access

The new readSessionBrokerLaunchFingerprint parameter defaults directly to process.env, bypassing the repository's validated environment configuration boundary and making configuration behavior harder to validate and test consistently.

Context Used: guidelines.mdc Cursor rule (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/session/broker/brokerLauncher.ts
Line: 418

Comment:
**Direct environment access**

The new `readSessionBrokerLaunchFingerprint` parameter defaults directly to `process.env`, bypassing the repository's validated environment configuration boundary and making configuration behavior harder to validate and test consistently.

**Context Used:** guidelines.mdc Cursor rule ([source](https://github.com/modem-dev/modem/blob/main/.cursor/rules/guidelines.mdc))

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[benvinegar]

Not changing this one. Hunk has no repository-wide validated-environment API, and this helper follows the adjacent injectable-environment convention: tests may pass an environment, while production defaults to process.env. The fingerprint is only a reconnect hint; the signed hello remains the compatibility and identity authority.

_{Responded by Pi using gpt-5.6-sol.}

This comment was generated by Pi using gpt-5.6-sol

[greptile-apps]

That context makes sense. Given there is no repository-wide validated-environment API and the helper follows the established injectable-environment convention, defaulting production calls to process.env is reasonable here. Since the fingerprint is only a reconnect hint and the signed hello remains the compatibility and identity authority, I agree this does not require a change.