@platless/axom-cli 0.3.13 → 0.6.36

package/dist/workstation/acp/adoption.js

@@ -1,94 +1,16 @@
 /**
- * "Adoption" — a user picking up a native agent session that already exists on this machine and
- * having its history replayed into Axom's timeline. Two ACP methods, both **optional on the
- * agent** and gated by `AcpConnection.capabilities` (Task 3): {@link listNativeSessions} calls
- * `session/list`, gated on `capabilities.list`; {@link replayNativeSession} calls `session/load`,
- * gated on `capabilities.loadSession`. Both degrade to "nothing to show" rather than an error when
- * unsupported — see the doc comment on each for why, and the deleted `bridges/types.ts`'s
- * `AgentBridge.listNativeSessions`/`BridgeSession.backfill` KDoc for the contract this carries
- * forward verbatim ("the directory hides the grouping, not an error").
- *
- * ## `session/resume` is deliberately NOT used here — read this before "fixing" it back
- *
- * The plan text that spawned this task says "`session/resume(replayFrom)`". Both do not exist in
- * `@agentclientprotocol/sdk@1.4.0`'s stable v1 entry point: `ResumeSessionRequest` has no
- * `replayFrom` field (that name only appears under `@agentclientprotocol/sdk/experimental/v2`,
- * which Global Constraint 1 forbids importing), and — more fundamentally — `resumeSession`'s own
- * doc comment in `dist/acp.d.ts` says it "Resumes an existing session **without** replaying the
- * message history (**unlike** `session/load`)". `session/load` (`loadSession`, gated by the
- * top-level `AgentCapabilities.loadSession: boolean`, not `sessionCapabilities`) is the ACP v1
- * method whose own doc comment says the agent should "Stream the entire conversation history back
- * to the client via notifications" — i.e. it is the actual replay mechanism this file needs.
- * `session/resume` exists for a client that already has a session's history cached elsewhere and
- * wants to keep working without paying for a redundant replay; Axom has never seen an adopted
- * session's history before, so that case never applies here.
- *
- * Verified both target adapters actually support the method this file calls: `claude-agent-acp`
- * 0.70.0 and `codex-acp` 1.6.2 both declare `agentCapabilities.loadSession: true` and both
- * implement `session/load` (`.superpowers/research/acp-sdk-registry.md`, "VERIFIED" section).
- *
- * ## Observing the replayed `session/update` notifications
- *
- * Unlike `session/new` (Task 4's `AcpSession`, built on the SDK's `ClientContext.buildSession(...)`
- * convenience wrapper), the SDK has no `SessionBuilder`-equivalent helper for `session/load` — the
- * only public, supported way to see raw `session/update` notifications outside of that helper is a
- * `ClientApp`-level `onNotification(methods.client.session.update, ...)` handler (the pattern the
- * SDK's own `acp.test.js` uses throughout for exactly this). That has to be registered before
- * `ClientApp.connect()` copies its handler table (`acpClient.ts`'s `ConnectAgentOptions.configure`
- * doc comment; `permission.ts`'s file doc comment says the same for `session/request_permission`).
- * {@link createReplayCapture}/{@link ReplayCapture.register} exist for that: a caller passes
- * `capture.register` into `connectAgent`'s `configure` hook — composable with `permission.ts`'s
- * `registerPermissionHandlers` in the same hook, since `configure` is one function a caller can do
- * several registrations inside of — and later, once the connection exists, passes the *same*
- * `capture` into {@link replayNativeSession}. The registered handler sees *every* `session/update`
- * notification on the connection, not just the one being replayed (verified against
- * `SessionUpdateRouter.handleMessage`, which always returns `Handled.no(message)` — it never consumes
- * the message, so dispatch keeps walking the handler chain to whatever else is registered, including
- * the SDK's own internal `session/new`-scoped router for a live `AcpSession` on the *same* connection).
- * That is exactly the axis review found this file getting wrong in fix round 1: a stray comment here
- * used to say this "never interferes with a live `AcpSession` on some other connection" — true, but
- * irrelevant, since the real conflict is a live `AcpSession` on the *same* connection (the shape a
- * caller composing this with `registerPermissionHandlers` in one `configure` hook produces routinely).
- * Without gating, the handler above would buffer *every* session's updates forever — only
- * {@link ReplayCapture.take} ever releases a buffered entry, and it is only ever called for the one
- * `sessionId` being replayed, so any other session's notifications arriving on this connection (most
- * concretely: a live `AcpSession` opened on the same connection right after adoption, which Task 8
- * needs) would accumulate unbounded for the life of the connection. {@link ReplayCapture.arm} exists
- * to close that: the handler now only buffers a `sessionId` that has been armed, {@link
- * replayNativeSession} arms its target *before* sending `session/load`, and `take()` disarms on its
- * way out — so the buffer's upper bound is whatever is currently being replayed, never every session
- * this connection has ever seen an update for.
- *
- * ## Replay goes through the same mapping and folding the live path uses — reimplemented, not shared
- *
- * {@link replayNativeSession} maps every replayed `SessionUpdate` through the exact same
- * `mapSessionUpdate` (`sessionUpdateMapper.ts`) the live path (`AcpSession`) uses, and every mapped
- * event through the same `validateWireEvent` (`validate.ts`) outbound check — so it can never
- * emit anything the server can't decode, and (per `mapSessionUpdate`'s own contract) can never emit
- * `final_result`. What it does NOT reuse is `AcpSession`'s own `agent_message` synthesis /
- * synthesis: that lives in `AcpSession` as push-based, event-sink-driven instance state (see its
- * class doc comment), a different execution shape than this file's pull-based `AsyncGenerator` over
- * an already-complete update list. Task 4's report flagged this by name: "the replay path needs its
- * own equivalent folding and message-completion logic — do not assume the live path's state machine
- * is doing it for you." {@link foldReplayEvents} is that equivalent, reimplemented as a single pass
- * over a finished array instead of instance fields mutated across live callbacks.
- *
- * **The `user_message` half of that duplication is gone.** This file used to carry its own copy of
- * `AcpSession.foldUserMessageChunk`, and the two had already drifted: replay flushed a buffered user
- * message on *any* intervening event, the live path only on a different `messageId` or turn end, so
- * the same transcript produced a different number of cards depending on which path replayed it.
- * Phase 7 moved the fold to `CoworkEngine`, which already buffered `agent_message_chunk` by exactly
- * the ACP rule that covers all three chunk kinds (`ContentChunk`, `types.gen.d.ts:3456`).
- * `user_message_chunk` now passes through here untouched, and `ExternalAgentEventApplier`'s
- * `onBackfillDone` is what closes the last buffered message.
+ * "Adoption" — the native agent sessions that already exist on this machine, as an agent lists them, and deleting them.
+ * Short-lived connections only (`connectAgent`); both ACP methods are **optional on the agent** and gated by
+ * `AcpConnection.capabilities`: {@link listNativeSessions} calls `session/list` (gated on `capabilities.list`),
+ * {@link deleteNativeSessions} calls `session/delete` (gated on `capabilities.delete`). Both degrade to "nothing to show" /
+ * `unsupported` rather than an error when the method is not advertised — carried forward verbatim from the deleted
+ * `bridges/types.ts`'s `AgentBridge.listNativeSessions` contract ("the directory hides the grouping, not an error").
+ *
+ * Replaying an adopted session's history (`session/load`) is the processor's (`processor/updates.ts`, the history window
+ * the daemon opens with `agent_session_open{mode:'load'}`); the replay helpers this file used to carry were deleted with the
+ * old live path (Task 29).
  */
-import { randomUUID } from 'node:crypto';
 import { methods } from '@agentclientprotocol/sdk';
-import { validateWireEvent } from './validate.js';
-import { SessionMapperScopes, scopeKey } from './sessionScope.js';
-import { mapSessionUpdate } from './sessionUpdateMapper.js';
-import { newSessionMetaFor } from './activityReporting.js';
-import { buildSessionMcpServers } from './delegationMcp.js';
 /** `NativeSessionInfo.title` is truncated to this many characters — mirrors the deleted `claudeCode/adoption.ts`'s display-safety guard (`TITLE_MAX_LENGTH`). */
 const TITLE_MAX_LENGTH = 80;
 /** `SessionInfo.updatedAt` is an ISO 8601 string or `null`/absent; missing or unparseable sorts as oldest (0) rather than throwing. */
@@ -144,311 +66,3 @@ export async function listNativeSessions(connection, query) {
         .sort((a, b) => b.updatedAtEpochMs - a.updatedAtEpochMs);
     return response.nextCursor != null ? { sessions, nextCursor: response.nextCursor } : { sessions };
 }
-export function createReplayCapture() {
-    const armed = new Set();
-    const buffered = new Map();
-    const listeners = new Map();
-    const takeScoped = (sessionId) => {
-        armed.delete(sessionId);
-        const list = buffered.get(sessionId) ?? [];
-        buffered.delete(sessionId);
-        return list;
-    };
-    const capture = (sessionId, notification) => {
-        if (!armed.has(sessionId))
-            return false;
-        const list = buffered.get(sessionId) ?? [];
-        list.push(notification);
-        buffered.set(sessionId, list);
-        return true;
-    };
-    return {
-        capture,
-        takeScoped,
-        register(app) {
-            app.onNotification(methods.client.session.update, (ctx) => {
-                // Armed wins over listening: while a session/load replay is in flight, its history must land
-                // in the buffer rather than in a live session's read loop — see `listen`'s doc comment.
-                if (capture(ctx.params.sessionId, ctx.params))
-                    return;
-                // Neither armed nor listened to: dropped, so this handler cannot accumulate every session
-                // the connection has ever seen an update for (see the file doc comment).
-                listeners.get(ctx.params.sessionId)?.(ctx.params.update);
-            });
-        },
-        arm(sessionId) {
-            armed.add(sessionId);
-        },
-        take(sessionId) {
-            return takeScoped(sessionId).map(({ update }) => update);
-        },
-        count(sessionId) {
-            return buffered.get(sessionId)?.length ?? 0;
-        },
-        listen(sessionId, sink) {
-            listeners.set(sessionId, sink);
-            return () => {
-                // Only clear our own entry: a later listen() for the same sessionId may already have
-                // replaced it, and unsubscribing then would silence the session that is actually running.
-                if (listeners.get(sessionId) === sink)
-                    listeners.delete(sessionId);
-            };
-        },
-    };
-}
-/** `payload[key]` narrowed to `string`, or `null` — same helper `acpSession.ts` uses for the identical reason (`payload` is `Record<string, unknown>` by construction). */
-function stringField(payload, key) {
-    const value = payload[key];
-    return typeof value === 'string' ? value : null;
-}
-/**
- * Map a completed list of replayed `SessionUpdate`s to wire events, applying the same
- * message-completion synthesis {@link AcpSession} applies to the live stream — see the file doc
- * comment for why this is a reimplementation, not a shared call, and `acpSession.ts`'s
- * `trackMessageBoundary`/`flushMessageCompleted` for the rule being mirrored:
- *
- * - `agent_message` is synthesized whenever the streaming `agent_message_chunk`/`agent_thought_chunk`
- *   `messageId` changes, and once more at the very end of the list (there is no live "turn end"
- *   signal to hang this off during replay — a whole adopted session's history has no `PromptResponse`
- *   in it at all — so "end of the replayed list" is this function's equivalent of `AcpSession.finishTurn`'s
- *   unconditional turn-end flush).
- * - A `user_message_chunk` still forces that synthesis: a user turn beginning means whatever the
- *   assistant was streaming has necessarily already ended. The chunk itself is emitted verbatim —
- *   folding it is the server's job now (see the file doc comment).
- *
- * Exported directly (not just through {@link replayNativeSession}) so its synthesis behavior can be
- * pinned by unit tests with no process spawning involved — the process-spawning tests are reserved
- * for what only a real subprocess can prove (capability gating, the actual RPC shape, ordering
- * against the real `session/load` response).
- */
-export function foldReplayEvents(updates) {
-    return foldScopedReplayEvents(updates.map((update) => ({ sessionId: 'root', update })), 'root');
-}
-/** Fold each origin independently, without reordering interleaved native notifications. */
-export function foldScopedReplayEvents(updates, rootNativeSessionId) {
-    const events = [];
-    const scopes = new SessionMapperScopes();
-    const rootRuntimeId = randomUUID();
-    const messages = new Map();
-    const emit = (event, nativeSessionId) => {
-        events.push(nativeSessionId === rootNativeSessionId ? event : { ...event, acpSessionId: nativeSessionId });
-    };
-    const flush = (key) => {
-        const message = messages.get(key);
-        if (!message)
-            return;
-        emit({ eventName: 'agent_message', payload: { messageId: message.messageId ?? 'replay' } }, message.nativeSessionId);
-        messages.delete(key);
-    };
-    for (const { sessionId: nativeSessionId, update } of updates) {
-        const origin = { rootRuntimeId, nativeSessionId };
-        const key = scopeKey(origin);
-        for (const event of mapSessionUpdate(update, scopes.get(origin))) {
-            if (event.eventName === 'user_message_chunk')
-                flush(key);
-            if (event.eventName === 'agent_message_chunk' || event.eventName === 'agent_thought_chunk') {
-                const messageId = stringField(event.payload, 'messageId');
-                const previous = messages.get(key);
-                if (previous && messageId !== null && previous.messageId !== null && messageId !== previous.messageId)
-                    flush(key);
-                messages.set(key, { nativeSessionId, messageId: messageId ?? messages.get(key)?.messageId ?? null });
-            }
-            emit(event, nativeSessionId);
-        }
-    }
-    for (const key of messages.keys())
-        flush(key);
-    scopes.clear();
-    return events;
-}
-/**
- * Wait until the `session/update` notifications an agent sent *before* answering a request have
- * actually been **dispatched**, which is **not** implied by that request having responded.
- *
- * The SDK handles the two message kinds on different schedules (`jsonrpc.js`'s
- * `receiveWireMessage`): a response is applied **synchronously** via `handleResponse` the moment the
- * reader pulls it off the stream, while a notification is handed to `processIncomingMessage`, which
- * is *not* awaited by the read loop and which awaits each registered handler in turn. So even though
- * the agent writes every `session/update` before its response — and the reader therefore reads them
- * first — the response's `await` can resume before a single one of our handlers has run. Measured
- * directly on both request paths that have this shape:
- *
- * - `session/load` ({@link replayNativeSession}): the order observed was `response`, then the
- *   updates, so `take()` on the spot returned a partial history, or none at all.
- * - `session/prompt` (`acpSession.ts`'s `AcpSession.attach`): the turn's terminal `stop` message was
- *   enqueued **ahead of** the tail of the same turn's deltas — `agent_message` and the
- *   `TurnResult` landing mid-stream, with the remaining text arriving as orphans after the item the
- *   server had already closed.
- *
- * The difference between "works" and "reorders" is nothing but how many handlers happen to be
- * registered on the connection — which is why the same code looked correct until the manager wired
- * permission handlers onto the same `ClientApp`.
- *
- * The one guarantee that survives is ordering *into* the dispatcher: by the time the response is
- * applied, every preceding notification's dispatch has been **started**. This waits for a macrotask
- * boundary, which drains a chain of synchronous handlers' microtask continuations, and keeps waiting
- * while `count()` is still growing.
- *
- * ## This is a heuristic. It is bounded **and** it truncates — three ways, all measured
- *
- * Nothing enforces the premise it rests on, so read these as live failure modes rather than as
- * theoretical corners:
- *
- * | Condition | Measured outcome |
- * |---|---|
- * | Any handler on the chain awaits a **macrotask** (even `setTimeout(…, 0)`) | 6 updates → **0** replayed |
- * | The agent answers **before** it has finished streaming | 6 updates → **4** replayed |
- * | The stream outlasts `maxRounds` | 3000 updates → **2086** replayed |
- *
- * The first is why "every handler on this chain is synchronous" is a **prerequisite**, and why it is
- * written down at the place that actually establishes it — `acpAgents.ts`'s `AcpAgents.open`
- * `configure` hook, the one site where handlers get registered — rather than only here. A function
- * cannot enforce a property of a registration it never sees.
- *
- * The second is outside this function's reach entirely: an agent that responds mid-stream has broken
- * the ordering guarantee this is built on, and no amount of waiting recovers it.
- *
- * The third is `maxRounds`, the backstop against an agent that keeps streaming forever — a wait with
- * no exit would hang the whole open. It is reachable in practice, so hitting it is **logged** rather
- * than returned quietly: that diagnostic is the whole line between "bounded degradation" and
- * "invisible data loss", and it is the only one of the three this function can see happening to
- * itself.
- *
- * `count` is supplied by the caller rather than read off a `ReplayCapture` because the two callers
- * count different things: the replay path counts buffered updates for one armed `sessionId`, the
- * live path counts updates delivered into an attached session's queue.
- */
-export async function settleUpdates(sessionId, count, maxRounds = 10) {
-    let previous = -1;
-    for (let round = 0; round < maxRounds; round += 1) {
-        const before = count();
-        // setImmediate, not setTimeout(0): it runs in the check phase, after the poll phase has drained
-        // whatever the transport already had readable, so one turn covers both the microtasks and any
-        // further messages sitting in the socket buffer.
-        await new Promise((resolve) => setImmediate(resolve));
-        const after = count();
-        if (after === before && after === previous)
-            return;
-        previous = before;
-    }
-    // Falling out of the loop is not "settled" — it is "gave up while the agent was still streaming".
-    // Whatever arrives from here on may be reordered against the turn/replay boundary this call was
-    // holding, or dropped outright. Never silent: a session that quietly loses the tail of its history
-    // is indistinguishable from an agent that had no history to give.
-    console.error(`[acp] session/update stream for '${sessionId}' was still growing after ${maxRounds} settle rounds ` +
-        `(${count()} updates so far) — continuing anyway; later updates may be reordered or lost.`);
-}
-/**
- * Replay one native session's history as wire events via `session/load` — see the file doc comment
- * for why `session/load`, not `session/resume`.
- *
- * When the agent doesn't advertise `agentCapabilities.loadSession` (`connection.capabilities.loadSession`),
- * this yields nothing **without ever calling `session/load`** — same "hidden grouping, not an error"
- * contract as {@link listNativeSessions}, applied to the capability that actually gates replay.
- *
- * Every yielded event has already gone through {@link foldReplayEvents} (same mapping the live path
- * uses, plus the same `agent_message` synthesis) and `validateWireEvent` (same outbound check the live path's
- * `permission_request` events go through) — an event that fails validation is dropped with a
- * diagnostic, never thrown, matching `validate.ts`'s own "drop + diagnostic, never an
- * exception" design. `mapSessionUpdate` never produces `final_result` (Task 4's contract, unchanged
- * here since this function adds no new event-producing path of its own) and `foldReplayEvents` adds
- * no new event names beyond what `mapSessionUpdate` and this file's own `agent_message` synthesis
- * already produce — both already appear in the server's understood vocabulary
- * (`sessionUpdateMapper.test.ts`'s `SERVER_UNDERSTOOD_EVENT_NAMES`), so nothing here needs to extend
- * it.
- *
- * ## `session/load` also activates the session, not just replays it — and Task 8 relies on that
- *
- * The `session/load` request below sends the current MCP list. That is not incidental — `session/load`
- * is not a read-only "give me the history" call: per its own spec, the agent restores this
- * `sessionId` as its **current** session, the same way `session/new` would, just with history
- * attached instead of starting empty.
- *
- * Task 8 resolved the fork this once handed forward: **Axom keeps prompting on
- * `params.nativeSessionId`, the session `session/load` just activated**, rather than opening a fresh
- * `session/new` and treating the replay as read-only history. `agentSessions.ts` receives a
- * `nativeSessionId` on reconnect as well as on adoption (the server persists it and hands it back),
- * so "open a new session and replay read-only" would silently drop the agent's own context on every
- * single reconnect — a regression against the deleted Claude Code bridge, which really did resume.
- * `AcpSession.attach` (`acpSession.ts`) is what that costs: the SDK's `ActiveSession` has a private
- * constructor reachable only through `SessionBuilder.start()`, i.e. only through `session/new`, so
- * driving an already-loaded `sessionId` means hand-building the same small `DrivenSession` surface
- * around raw `session/prompt` / `session/cancel` requests and {@link ReplayCapture.listen}.
- *
- * Both paths use `buildSessionMcpServers`, so an adopted or reconnected session receives the same
- * user servers and a freshly issued delegation lease when managed delegation is enabled.
- *
- * ## Also opts claude into activity reporting, the same as `session/new` — closing a real gap, not a cosmetic one
- *
- * `AcpSession.open`'s `session/new` request carries `_meta.claudeCode.emitRawSDKMessages`
- * (`newSessionMetaFor`, `activityReporting.ts`) so claude's collector pushes
- * `extNotification("_claude/sdkMessage", …)` back on the connection. `session/load` used to send no
- * `_meta` at all, so every session reached through this function — every adoption, and every
- * reconnect after a daemon restart, since a fresh child process's session table is always empty and
- * therefore always takes the `createSession` branch of `getOrCreateSession` — permanently lost
- * activity reporting the moment it was (re)loaded, while `agent_opened.reportsActivity` kept
- * claiming `true`. Verified directly against the installed `claude-agent-acp@0.79.0` adapter
- * (`dist/acp-agent.js`): `loadSession` → `getOrCreateSession` → (no matching in-process session, the
- * case that always applies to a freshly spawned agent) → `createSession({ …, _meta: params._meta },
- * { resume: params.sessionId })`, and `createSession` reads
- * `sessionMeta?.claudeCode?.emitRawSDKMessages` off that same `_meta` exactly as `session/new` does.
- * `newSessionMetaFor` is reused verbatim rather than re-implementing the same agent-name check here,
- * so there is exactly one place that decides which agents opt in.
- */
-export async function* replayNativeSession(connection, capture, params) {
-    if (!connection.capabilities.loadSession)
-        return;
-    // Exclusive ownership must precede every mutation of the shared capture/known-session state.
-    // A rejected concurrent load must not consume or disarm the active owner's buffer.
-    const releaseCapture = connection.captureSessionUpdates((notification) => capture.capture(params.nativeSessionId, notification));
-    // Arm before requesting — the agent may start sending session/update notifications for this
-    // sessionId as soon as it receives the request, and the capture's handler drops anything for a
-    // sessionId that isn't armed yet (see ReplayCapture.arm's doc comment).
-    capture.arm(params.nativeSessionId);
-    // The transport diverts updates for a session it does not know is handled here, because the SDK's
-    // router would otherwise drop them on the floor. During a replay this capture *is* the handler,
-    // so the claim has to be made explicitly — and withdrawn in the same `finally` that disarms.
-    const unmarkSession = connection.markSessionKnown(params.nativeSessionId);
-    // Same opt-in `session/new` sends, on the request that actually reaches the agent for every
-    // adoption/reconnect — see the doc comment above. `undefined` for every non-claude agent, in which
-    // case the spread below adds nothing, so a non-claude `session/load` is byte-for-byte the request
-    // it always sent.
-    const meta = newSessionMetaFor(connection.agentInfo?.name);
-    let updates;
-    try {
-        const mcpServers = buildSessionMcpServers(params.mcpServers, params.delegationMcp);
-        if (params.delegationMcp)
-            connection.redactStderrSecret(Object.values(params.delegationMcp.headers)[0]);
-        const response = await connection.connection.agent.request(methods.agent.session.load, {
-            sessionId: params.nativeSessionId,
-            cwd: params.cwd,
-            mcpServers,
-            ...(meta ? { _meta: meta } : {}),
-        });
-        params.onLoaded?.(response);
-        // The response resolving is NOT the end of the replay — see {@link settleUpdates} for the SDK
-        // scheduling that makes `take()` on the spot return a partial history.
-        await settleUpdates(params.nativeSessionId, () => capture.count(params.nativeSessionId));
-    }
-    finally {
-        releaseCapture();
-        unmarkSession();
-        // In a `finally` because `arm()` has no other exit. A rejected `session/load` — a stale id the
-        // agent has since deleted, the case `AcpAgents.startSession` catches and falls back from — used
-        // to throw straight past `take()`, leaving the id armed and whatever had already been buffered
-        // for it held until the connection died. That contradicts this file's own claim that "the
-        // buffer's upper bound is whatever is currently being replayed": the fallback opens a *different*
-        // session id, so nothing would ever come back to take this one. `take()` is both halves at once
-        // (release the buffer, disarm), which is why the failure path calls the same function the
-        // success path does rather than a disarm of its own.
-        updates = capture.takeScoped(params.nativeSessionId);
-    }
-    for (const event of foldScopedReplayEvents(updates, params.nativeSessionId)) {
-        const rejection = validateWireEvent(event);
-        if (rejection) {
-            console.error(`[acp] dropping a replayed event that fails validateWireEvent: ${rejection.reason} (session ${params.nativeSessionId})`);
-            continue;
-        }
-        yield event;
-    }
-}

package/dist/workstation/acp/binaryInstall.js

@@ -29,13 +29,14 @@
  * but the result says so via `checksumVerified: false`. Nothing here may report an unverified
  * download as checked; that is precisely the distinction {@link InstallOutcome} exists to preserve.
  *
- * ## Layout: several versions can coexist
+ * ## Layout: several versions can coexist, and each appears whole or not at all
  *
- * Installs land at `<root>/<registryAgent>/<version>/`, one directory per version, the same
- * side-by-side layout npm's own `_npx` cache keeps for npx-distributed adapters. Picking one
- * installed version when several are present reuses `installProbe.ts`'s
- * {@link pickInstalledVersion} rather than reimplementing that rule a second time — see
- * {@link installedBinaryVersion}.
+ * Installs land at `<root>/bin/<registryAgent>/<version>/` (spec 2026-10-11 §6.2), one directory per
+ * version. The archive is unpacked into `<root>/.staging/<uuid>/` and only a complete tree is
+ * `rename(2)`d into place, so a directory under `bin/` always holds a whole install — an unpack that
+ * is killed half-way leaves only a staging leftover, never a half-written version that something
+ * would take for installed. Which version an agent *launches* is no longer chosen here: it is the
+ * agent's `current` build (`builds/store.ts`). {@link installedBinaryVersion} only enumerates.
  *
  * ## Unpacking without a new dependency
  *
@@ -65,12 +66,14 @@
  * `<installDir>/<basename of the archive URL>` and marked executable — that filename is exactly
  * what `BinaryTarget.cmd` refers to. See {@link isArchiveFile}.
  */
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { createWriteStream, promises as fs, readdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
+import { binaryBuildDir, inside } from './builds/model.js';
+import { publishStaged } from './builds/store.js';
 import { pickInstalledVersion } from './installProbe.js';
 import { runTimedCommand } from './timedCommand.js';
 const PLATFORM_SEGMENT = {
@@ -122,12 +125,13 @@ const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 export function installedBinaryVersion(registryAgent, root, pinned) {
     let entries;
     try {
-        entries = readdirSync(path.join(root, registryAgent), { withFileTypes: true });
+        entries = readdirSync(path.join(root, 'bin', registryAgent), { withFileTypes: true });
     }
     catch {
         return undefined;
     }
-    const versions = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    // Dot-directories (`.staging`, `.trash`, editor droppings) are never versions.
+    const versions = entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith('.')).map((entry) => entry.name);
     return pickInstalledVersion(versions, pinned);
 }
 /**
@@ -203,9 +207,40 @@ const ARCHIVE_DOWNLOAD_TIMEOUT_MS = 300_000;
  * longer than the download step right above it is already allowed to take.
  */
 const ARCHIVE_EXTRACT_TIMEOUT_MS = 300_000;
+/**
+ * Attempts made on the *request* phase of one archive download. Registry archives are
+ * third-party-hosted, and the failure this retries — the initial `fetch` throwing — is the
+ * transient kind: an edge node that answers this minute and not the next, a resolver rotating
+ * between a real and a dead address. Deterministic failures (redirect policy, loops, HTTP codes)
+ * come back from {@link fetchArchive} as structured results and are never retried. Both attempts
+ * share one {@link ARCHIVE_DOWNLOAD_TIMEOUT_MS} signal, so the whole-request budget never doubles;
+ * undici's own ~10s connect bound keeps the added worst case small.
+ */
+const ARCHIVE_FETCH_ATTEMPTS = 2;
+/** Pause between the two fetch attempts — long enough for a flipped resolver answer, short next to a 300s budget. */
+const ARCHIVE_FETCH_RETRY_PAUSE_MS = 2_000;
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
+/**
+ * `fetch`'s failures arrive as a bare `fetch failed` with the real reason (a connect timeout, a
+ * reset mid-handshake, a TLS refusal — classes that lead the diagnosis, not decorate it) one or
+ * two `cause` links down, and undici names them with stable machine codes (`UND_ERR_CONNECT_TIMEOUT`,
+ * `ECONNRESET`). This walks the chain and joins it onto the message, so a daemon log and an error
+ * card say what actually happened instead of leaving a one-word verdict. Observed 2026-10-14: a
+ * machine whose route to `dl.google.com` had died logged only "fetch failed" and cost a DNS/CDN
+ * investigation that `UND_ERR_CONNECT_TIMEOUT` would have named on the spot.
+ */
+function describeFetchFailure(err) {
+    const parts = [errorMessage(err)];
+    let cause = err?.cause;
+    for (let depth = 0; depth < 5 && cause !== undefined && cause !== null; depth += 1) {
+        const named = cause;
+        parts.push(typeof named.code === 'string' ? named.code : typeof named.message === 'string' ? named.message : String(cause));
+        cause = cause.cause;
+    }
+    return [...new Set(parts)].join(' — ');
+}
 function hasEntries(dir) {
     try {
         return readdirSync(dir).length > 0;
@@ -308,7 +343,7 @@ async function extractArchive(archivePath, destDir, exec, timeoutMs) {
 }
 /**
  * Fetch, verify and unpack `agent`'s binary adapter for this machine's platform triple. Never
- * starts the agent — the counterpart to `installNpxPackage`/`installUvTool`'s "download, don't run"
+ * starts the agent — the counterpart to `ensurePristine`/`installUvBuild`'s "download, don't run"
  * contract.
  *
  * ## The three outcomes the brief for this task requires, and why each looks the way it does
@@ -340,7 +375,13 @@ export async function installBinary(agent, opts) {
         return { ok: false, error: `Agent '${agent.id}' publishes no archive for ${triple ?? `${platform}-${arch}`}.` };
     }
     const version = agent.version;
-    const installDir = path.join(opts.root, agent.id, version);
+    let installDir;
+    try {
+        installDir = inside(opts.root, binaryBuildDir(agent.id, version));
+    }
+    catch (err) {
+        return { ok: false, error: errorMessage(err) };
+    }
     if (hasEntries(installDir)) {
         return { ok: true, checksumVerified: false, alreadyInstalled: true, version, installDir };
     }
@@ -358,8 +399,24 @@ export async function installBinary(agent, opts) {
             // whereas a `BinaryTarget.archive` is an arbitrary third-party URL verified by an optional
             // SHA-256 the registry supplies. Different trust model, so the policy is stated here: one
             // whole-chain budget, a capped number of hops, and HTTPS at every one. See `fetchArchive` for
-            // why following redirects is required rather than merely permitted.
-            const fetched = await fetchArchive(target.archive, fetchImpl, AbortSignal.timeout(ARCHIVE_DOWNLOAD_TIMEOUT_MS));
+            // why following redirects is required rather than merely permitted. The one retry here covers
+            // only the transient request-phase throw ({@link ARCHIVE_FETCH_ATTEMPTS}).
+            const signal = AbortSignal.timeout(ARCHIVE_DOWNLOAD_TIMEOUT_MS);
+            let fetched;
+            for (let attempt = 1;; attempt += 1) {
+                try {
+                    fetched = await fetchArchive(target.archive, fetchImpl, signal);
+                    break;
+                }
+                catch (err) {
+                    if (attempt >= ARCHIVE_FETCH_ATTEMPTS || signal.aborted) {
+                        throw new Error(describeFetchFailure(err));
+                    }
+                    console.warn(`[acp] archive fetch attempt ${attempt} for '${agent.id}' failed ` +
+                        `(${describeFetchFailure(err)}); retrying once.`);
+                    await new Promise((resolve) => setTimeout(resolve, ARCHIVE_FETCH_RETRY_PAUSE_MS));
+                }
+            }
             if (!fetched.ok) {
                 return { ok: false, error: `Failed to download adapter archive for '${agent.id}': ${fetched.error}` };
             }
@@ -374,7 +431,14 @@ export async function installBinary(agent, opts) {
         const hash = createHash('sha256');
         const source = Readable.fromWeb(response.body);
         source.on('data', (chunk) => hash.update(chunk));
-        await pipeline(source, createWriteStream(archivePath, { mode: 0o600 }));
+        // A body that dies mid-stream (a reset connection, undici's "terminated") is a download
+        // failure like any other — reported, not thrown past the caller that owns the retry UX.
+        try {
+            await pipeline(source, createWriteStream(archivePath, { mode: 0o600 }));
+        }
+        catch (err) {
+            return { ok: false, error: `Failed to download adapter archive for '${agent.id}': ${describeFetchFailure(err)}` };
+        }
         if (target.sha256) {
             const digest = hash.digest('hex');
             if (digest.toLowerCase() !== target.sha256.toLowerCase()) {
@@ -385,23 +449,32 @@ export async function installBinary(agent, opts) {
                 };
             }
         }
-        await fs.mkdir(installDir, { recursive: true });
+        // Unpacked into a staging tree on the same filesystem, then renamed into place whole: nothing
+        // under `bin/` is ever half-written (see the module doc's layout section).
+        const staged = path.join(opts.root, '.staging', randomUUID());
         try {
-            if (await isArchiveFile(archivePath, target.archive)) {
-                await extractArchive(archivePath, installDir, opts.exec ?? runCommand, ARCHIVE_EXTRACT_TIMEOUT_MS);
+            await fs.mkdir(staged, { recursive: true });
+            try {
+                if (await isArchiveFile(archivePath, target.archive)) {
+                    await extractArchive(archivePath, staged, opts.exec ?? runCommand, ARCHIVE_EXTRACT_TIMEOUT_MS);
+                }
+                else {
+                    // Not an archive at all — the download *is* the program (e.g. `sigit`'s Linux/Windows
+                    // targets, see the module doc). Place it under the same name `BinaryTarget.cmd` refers to
+                    // and mark it executable; `chmod` is a no-op on Windows but harmless there.
+                    const destPath = path.join(staged, archiveFileName(target.archive));
+                    await fs.copyFile(archivePath, destPath);
+                    await fs.chmod(destPath, 0o755);
+                }
             }
-            else {
-                // Not an archive at all — the download *is* the program (e.g. `sigit`'s Linux/Windows
-                // targets, see the module doc). Place it under the same name `BinaryTarget.cmd` refers to
-                // and mark it executable; `chmod` is a no-op on Windows but harmless there.
-                const destPath = path.join(installDir, archiveFileName(target.archive));
-                await fs.copyFile(archivePath, destPath);
-                await fs.chmod(destPath, 0o755);
+            catch (err) {
+                return { ok: false, error: `Failed to unpack adapter archive for '${agent.id}': ${errorMessage(err)}` };
             }
+            // A concurrent install of the same version may have published first; its tree is equally whole.
+            await publishStaged(staged, installDir);
         }
-        catch (err) {
-            await fs.rm(installDir, { recursive: true, force: true }).catch(() => undefined);
-            return { ok: false, error: `Failed to unpack adapter archive for '${agent.id}': ${errorMessage(err)}` };
+        finally {
+            await fs.rm(staged, { recursive: true, force: true }).catch(() => undefined);
         }
         return { ok: true, checksumVerified: Boolean(target.sha256), alreadyInstalled: false, version, installDir };
     }