mixdog 1.3.4 → 1.4.0

package/src/session-runtime/workflow-agents-api/agent-editor.mjs

@@ -1,4 +1,4 @@
-import { join } from 'node:path';
+import { dirname, isAbsolute, join, relative, sep } from 'node:path';
 import { createHash } from 'node:crypto';
 import {
   accessSync,
@@ -7,18 +7,19 @@ import {
   mkdirSync,
   readFileSync,
   readdirSync,
+  realpathSync,
   renameSync,
   rmSync,
   statSync,
 } from 'node:fs';
 import {
   holdsNoData,
-  parseJsonText,
   readJsonStateSync,
   writeFileAtomicSync,
   writeJsonAtomicSync,
 } from '../../runtime/shared/atomic-file.mjs';
 import { clean } from '../../runtime/agent/orchestrator/runtime-core/session-text.mjs';
+import { agentEntryFile, agentEntryPath, parseManifestText } from '../../runtime/agent/orchestrator/runtime-core/workflow/agents.mjs';
 import { hasOwn } from '../../runtime/shared/object.mjs';
 import { serializeFrontmatterDoc } from '../../runtime/shared/markdown-frontmatter.mjs';
 import { isHiddenAgent } from '../../runtime/agent/orchestrator/internal-agents.mjs';
@@ -79,9 +80,43 @@ import {
 
 const isFixedAgent = (id) => FIXED_AGENT_SLOTS.some((agent) => agent.id === id);
 const userDir = userDefinitionDir;
-const hasUserAgentFile = (dataDir, id) => existsSync(join(userDir(dataDir, id), 'AGENT.md'));
-// An archived (deleted) agent's AGENT.md, moved aside beside the tombstone:
-// no loader reads it, and restoring moves it back.
+// The entry file of the agent folder `dir`, exactly as the loader reads it
+// (agent.json `entry`, AGENT.md by default).
+const entryIn = (dir) => agentEntryPath(dir, readManifest(dir));
+const userEntryPath = (dataDir, id) => entryIn(userDir(dataDir, id));
+// An agent exists where its folder has an AGENT.md, as discovery lists it.
+const hasEntryFile = (dir) => existsSync(join(dir, 'AGENT.md'));
+const hasUserAgentFile = (dataDir, id) => hasEntryFile(userDir(dataDir, id));
+const leavesFolder = (rel) => rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+// The file delete moves aside and restore moves back: the agent's entry when
+// it is named inside `dir` and its folder resolves inside too (a symlink as the
+// last part moves as the link alone), else HEAD's AGENT.md. An entry outside the
+// folder (`..`, or through a linked folder) is shared and never moved.
+const archivableEntry = (dir, entry) => {
+  try {
+    const rel = relative(dir, entry);
+    if (rel && !leavesFolder(rel) && !leavesFolder(relative(realpathSync(dir), realpathSync(dirname(entry))))) {
+      return entry;
+    }
+  } catch {
+    // an unresolvable folder holds no entry to move
+  }
+  return join(dir, 'AGENT.md');
+};
+// The entry file the editor may hand out to edit in place: it resolves (symlinks
+// followed) to a file inside its own agent folder, else null. The loader still
+// reads an entry outside; only the editable path is contained.
+const editablePathIn = (dir, path) => {
+  try {
+    return leavesFolder(relative(realpathSync(dir), realpathSync(path))) ? null : path;
+  } catch {
+    return null;
+  }
+};
+// An archived (deleted) agent's entry file, moved aside beside the tombstone
+// as `<entry>.archived`: no loader reads it, and restoring moves it back.
+const archivedEntryPath = (entryPath) => `${entryPath}.archived`;
+// The default entry's archive (all that HEAD wrote); a save clears it.
 const ARCHIVED_AGENT_FILE = 'AGENT.md.archived';
 
 // Frontmatter the editor does not show (e.g. `permission`), taken from the
@@ -123,15 +158,19 @@ const writeManifest = (file, manifest) => writeJsonAtomicSync(file, manifest, DE
 // no data (empty, or NUL-filled by a crash) or is not a JSON object.
 function readManifestStrict(file) {
   try {
-    const text = readFileSync(file, 'utf8');
-    if (holdsNoData(text)) return null;
-    const value = parseJsonText(text);
-    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+    return readManifestFile(file);
   } catch {
     return null;
   }
 }
 
+// The same, but a file that cannot be read throws its error.
+function readManifestFile(file) {
+  const text = readFileSync(file, 'utf8');
+  if (holdsNoData(text)) return null;
+  return parseManifestText(text);
+}
+
 // A read-only agent.json is a standing refusal, not a transient lock: the
 // atomic write's rename onto it fails with EPERM and is retried for seconds,
 // synchronously on the host's event loop. Refuse it up front (one stat, no wait),
@@ -559,10 +598,16 @@ function definitionPresence({ dataDir, rootDir, stat }, agentIds) {
 // A definition folder's revision: a hash of the three files an editor writes.
 function definitionDirRevision(dir) {
   const hash = createHash('sha256');
-  for (const name of ['agent.json', 'AGENT.md', PERSONA_FILE]) {
+  const manifest = readManifest(dir);
+  const files = [
+    ['agent.json', join(dir, 'agent.json')],
+    [agentEntryFile(manifest), agentEntryPath(dir, manifest)],
+    [PERSONA_FILE, join(dir, PERSONA_FILE)],
+  ];
+  for (const [name, file] of files) {
     hash.update(`${name}\0`);
     try {
-      hash.update(readFileSync(join(dir, name)));
+      hash.update(readFileSync(file));
     } catch {
       hash.update('\u0001absent');
     }
@@ -660,13 +705,27 @@ function createAgentArchiveApi({
       await announceBotChange(dataDir);
       return { id, deleted: true, revertedToBuiltIn: Boolean(sourceFallback) };
     }
-    // A custom agent is archived: its AGENT.md (what makes it an agent
-    // anywhere) moves aside, the tombstone keeps the packaged copy of a
-    // starter from coming back, and the rest (agent.json: name and face,
-    // persona, memory, its model and on/off) stays for its archived chat —
-    // until restoreAgentDefinition brings it back or purgeAgentDefinition.
+    // A custom agent is archived: its entry file (AGENT.md, or the one its
+    // agent.json names; what makes it an agent anywhere) moves aside, the
+    // tombstone keeps the packaged copy of a starter from coming back, and the
+    // rest (agent.json: name and face, persona, memory, its model and on/off)
+    // stays for its archived chat — until restoreAgentDefinition brings it back
+    // or purgeAgentDefinition.
+    // AGENT.md always moves aside; an AGENT.md over an existing archive is
+    // refused, since the move would overwrite it. Another selected entry
+    // moves too when its own archive is free, and otherwise stays in place
+    // under the tombstone.
+    const agentFile = join(dir, 'AGENT.md');
+    const agentArchive = archivedEntryPath(agentFile);
+    if (existsSync(agentFile) && existsSync(agentArchive)) {
+      throw new Error(`agent "${id}" cannot be deleted: ${agentArchive} already exists; move or remove it first`);
+    }
+    const entry = archivableEntry(dir, entryIn(dir));
     mkdirSync(dir, { recursive: true });
-    if (existsSync(join(dir, 'AGENT.md'))) renameSync(join(dir, 'AGENT.md'), join(dir, ARCHIVED_AGENT_FILE));
+    if (existsSync(agentFile)) renameSync(agentFile, agentArchive);
+    if (entry !== agentFile && existsSync(entry) && !existsSync(archivedEntryPath(entry))) {
+      renameSync(entry, archivedEntryPath(entry));
+    }
     writeFileAtomicSync(join(dir, AGENT_DELETED_MARKER), 'deleted\n');
     clearAgentDefinitionCache(id);
     // The Leads listing it drop it from their roster from their next turn.
@@ -683,11 +742,22 @@ function createAgentArchiveApi({
     const dataDir = dataDirOf();
     if (!isArchivedAgent(dataDir, id)) throw new Error(`agent "${id}" is not deleted`);
     const dir = userDir(dataDir, id);
-    const kept = join(dir, ARCHIVED_AGENT_FILE);
-    if (!existsSync(kept) && !existsSync(join(shippedDir(id), 'AGENT.md'))) {
+    // AGENT.md.archived back to AGENT.md, and the selected entry's archive back
+    // to that entry. Nothing is overwritten: an archive whose file exists again
+    // stays as it is, and when every kept archive collides the restore is refused.
+    const agentFile = join(dir, 'AGENT.md');
+    const entry = archivableEntry(dir, entryIn(dir));
+    const moves = [{ from: join(dir, ARCHIVED_AGENT_FILE), to: agentFile }];
+    if (entry !== agentFile) moves.push({ from: archivedEntryPath(entry), to: entry });
+    const kept = moves.filter((move) => existsSync(move.from));
+    if (kept.length === 0 && !hasEntryFile(shippedDir(id))) {
       throw new Error(`agent "${id}" was deleted before deleted agents were kept, so it cannot be restored`);
     }
-    if (existsSync(kept)) renameSync(kept, join(dir, 'AGENT.md'));
+    const free = kept.filter((move) => !existsSync(move.to));
+    if (kept.length > 0 && free.length === 0) {
+      throw new Error(`agent "${id}" cannot be restored: ${kept[0].to} already exists; move or remove it first`);
+    }
+    for (const move of free) renameSync(move.from, move.to);
     rmSync(join(dir, AGENT_DELETED_MARKER), { force: true });
     clearAgentDefinitionCache(id);
     // Back in the roster of the Leads that list it, from their next turn.
@@ -795,13 +865,20 @@ export function createAgentEditorApi(deps) {
     const dataDir = resolveDataDir(deps);
     const definition = loadAgentDefinition(dataDir, id);
     if (!definition) throw new Error(`agent "${agentId}" not found`);
+    const userOverride = hasUserAgentFile(dataDir, id);
     return {
       id,
       name: definition.name,
       description: definition.description,
       body: definition.body,
       custom: !isFixedAgent(id),
-      userOverride: hasUserAgentFile(dataDir, id),
+      userOverride,
+      // The user copy's entry file, editable in place; a shipped-only agent has
+      // none (an install-dir edit would be lost on update), nor has an entry
+      // that resolves outside its folder (the body is still returned).
+      ...(userOverride && editablePathIn(userDir(dataDir, id), userEntryPath(dataDir, id))
+        ? { path: userEntryPath(dataDir, id) }
+        : {}),
       route: routeFor(getConfig(), id),
       routeConfigured: routeConfigured(getConfig(), id),
       kind: kindOf(definition),

package/src/session-runtime/workflow-agents-api/style-and-mode.mjs

@@ -64,6 +64,10 @@ export function createStyleAndModeApi(deps) {
     listOutputStyles: () => getOutputStyleStatusCached(),
     setOutputStyle,
     getOrchestrationMode: () => configuredOrchestrationMode(displayConfig()),
+    // The default new sessions inherit. The runtime facade's own
+    // getOrchestrationMode answers for the ACTIVE session when one exists, so a
+    // New Task composer reads this one: it never depends on which session is open.
+    getConfiguredOrchestrationMode: () => configuredOrchestrationMode(displayConfig()),
     setOrchestrationMode,
   };
 }

package/src/session-runtime/workflow-agents-api/workflow-packs.mjs

@@ -77,13 +77,18 @@ export function createWorkflowPacksApi(deps) {
     const dataDir = resolveDataDir(deps);
     const pack = loadWorkflowPack(dataDir, id);
     if (!pack || pack.id !== id) throw new Error(`workflow "${workflowId}" not found`);
+    // The user copy's file, so a part of a long body can be edited in place;
+    // a shipped-only pack has none (its install copy is replaced on update).
+    const file = join(dataDir, 'workflows', id, 'WORKFLOW.md');
+    const userOverride = existsSync(file);
     return {
       id: pack.id,
       name: pack.name,
       description: pack.description,
       source: pack.source,
       body: pack.body,
-      userOverride: existsSync(join(dataDir, 'workflows', id, 'WORKFLOW.md')),
+      userOverride,
+      ...(userOverride ? { path: file } : {}),
     };
   }
 

package/src/session-runtime/workspace/transitions.mjs

@@ -426,7 +426,7 @@ export function createWorkspaceTransitions({
    * refuses while a session or worker runs in an affected folder, or a
    * background command does; `removing` refuses while any session still uses
    * one. Then holds the folders — Mixdog checkouts only; an external checkout
-   * is never lock-blocked — so new Mixdog work there waits until `run`
+   * takes no lease from this profile — so new Mixdog work there waits until `run`
    * settles. `actor`: the session acting on its own checkout, whose own turn
    * and workers its caller already checked (assertLeadIdle).
    */
@@ -985,7 +985,15 @@ export function createWorkspaceTransitions({
    * `ownTurn` (internal: the Lead's own tool call) tolerates the calling turn.
    */
   async function requestWorktree(
-    { name = null, confirmLarge = false, provision = false, carryChanges, prompt = '', txId = '', expectedRevision } = {},
+    {
+      name = null,
+      confirmLarge = false,
+      provision = false,
+      carryChanges,
+      prompt = '',
+      txId = '',
+      expectedRevision,
+    } = {},
     { ownTurn = false } = {}
   ) {
     const nameHint = validName(name);

package/src/standalone/channel-transport/client-registry/client-records.mjs

@@ -0,0 +1,65 @@
+// The live client records of the channel transport: pid-liveness reads and
+// pruning, the one removal primitive every path uses, and the UI control
+// pointer lookup. `replays` and `grace` are the registry's replay records and
+// self-shutdown grace timer.
+import { isPidAlive } from '../../../runtime/shared/pid-liveness.mjs';
+
+export function createClientRecords({ state, log, publishRemoteState, replays, grace }) {
+  const { clients } = state;
+
+  // pid death is the authoritative signal for client liveness: a client whose
+  // SSE stream closed may still reconnect, one whose lead pid is gone cannot.
+  function pruneDeadClients() {
+    for (const [token, c] of clients) {
+      if (!isPidAlive(c.leadPid)) dropClient(token, 'pid dead');
+    }
+  }
+
+  function liveClients() {
+    const out = [];
+    for (const [token, c] of clients) {
+      if (isPidAlive(c.leadPid)) out.push([token, c]);
+    }
+    return out;
+  }
+
+  // Every removal path uses this primitive, including replacement's deliberate
+  // no-failover retirement, so replay records/timers never target absent tokens.
+  function removeClientRecord(token) {
+    const c = clients.get(token);
+    if (!c) return null;
+    clients.delete(token);
+    replays.forgetFor(token);
+    try {
+      c.sse?.end?.();
+    } catch {
+      // The stream may already be closed by the peer.
+    }
+    return c;
+  }
+
+  function dropClient(token, reason) {
+    const c = removeClientRecord(token);
+    if (!c) return;
+    if (state.pointerToken === token) state.pointerToken = null;
+    log(`client ${token} (lead=${c.leadPid}) removed: ${reason}`);
+    // Client presence is not channel authority. The durable session pin stays
+    // active until that same session explicitly turns Remote OFF.
+    publishRemoteState();
+    grace.maybeArm('client removed');
+  }
+
+  // Resolve the active UI pointer for state delivery only. Session routing
+  // never depends on this client.
+  function resolveTarget() {
+    if (state.pointerToken) {
+      const c = clients.get(state.pointerToken);
+      if (c && isPidAlive(c.leadPid)) return c;
+      if (c) dropClient(state.pointerToken, 'pid dead (notify-time)');
+      else state.pointerToken = null;
+    }
+    return null;
+  }
+
+  return { pruneDeadClients, liveClients, removeClientRecord, dropClient, resolveTarget };
+}

package/src/standalone/channel-transport/client-registry/client-registration.mjs

@@ -0,0 +1,118 @@
+// Client registration for the channel transport: a fresh record per attach,
+// a passive reconnect's response-loss replay, the replaced token's retirement
+// with its token-scoped state carried over, and the replacement's
+// cancellation. `records` is the registry's client records (client-records).
+import { randomUUID } from 'node:crypto';
+import { parsePid } from '../../../runtime/shared/pid-liveness.mjs';
+import { replayMatchesCancellation, replayMatchesRegistration } from './registration-replays.mjs';
+
+export function createClientRegistration({ state, log, onClientRegistered, replays, grace, records }) {
+  const { clients } = state;
+
+  function cancelReplacementRegistration(request) {
+    const replay = replays.lookup(request.registrationId);
+    if (!replay) return 'missing';
+    if (!replayMatchesCancellation(replay, request)) return 'forbidden';
+    records.dropClient(replay.token, 'replacement deregister');
+    return 'cancelled';
+  }
+
+  /** A passive reconnect retrying under a known registration id gets the fresh
+   *  token it already created; a different identity under that id is a 409. */
+  function replayedToken(replayId, identity) {
+    const existing = replays.lookup(replayId);
+    if (!existing) return null;
+    if (replayMatchesRegistration(existing, identity) && clients.has(existing.token)) {
+      replays.arm(replayId, existing);
+      log(`client reconnect replay token=${existing.token} lead=${identity.pid}`);
+      return existing.token;
+    }
+    if (clients.has(existing.token)) {
+      const err = new Error('registration replay identity mismatch');
+      err.statusCode = 409;
+      throw err;
+    }
+    replays.remove(replayId, existing);
+    return null;
+  }
+
+  /** A reconnect names the exact token it replaces. Token-scoped state belongs
+   *  to the logical client, so the fresh record inherits the buffered frame,
+   *  remote session and pointer; the old token is retired even when it is not
+   *  the pointer — retaining it would let it later call or accumulate a
+   *  buffered frame after the fresh client has gone away. */
+  function adoptReplacedClient(fresh, replaced) {
+    const replacedWasPointer = state.pointerToken === replaced.token;
+    if (replaced.pendingRemoteStateFrame) {
+      fresh.pendingRemoteStateFrame = replaced.pendingRemoteStateFrame;
+      replaced.pendingRemoteStateFrame = null;
+    }
+    if (replaced.remoteSessionId) fresh.remoteSessionId = replaced.remoteSessionId;
+    if (replaced.restoreSessionId) fresh.restoreSessionId = replaced.restoreSessionId;
+    if (replacedWasPointer) state.pointerToken = fresh.token;
+    records.removeClientRecord(replaced.token);
+    log(`client reconnect replaced token=${replaced.token} -> ${fresh.token} lead=${fresh.leadPid}`);
+  }
+
+  function registerClient({
+    leadPid,
+    cwd,
+    passive = false,
+    replaceToken = null,
+    registrationId = null,
+    restoreSessionId = null,
+  }) {
+    const pid = parsePid(leadPid) ?? 0;
+    const restoreId = /^[A-Za-z0-9_-]+$/.test(String(restoreSessionId || '')) ? String(restoreSessionId) : null;
+    const replacementToken = replaceToken ? String(replaceToken) : null;
+    const replayId = passive && registrationId ? replays.replayIdOf(registrationId) : null;
+    const replayed = replayedToken(replayId, { pid, cwd, replacementToken, restoreId });
+    if (replayed) return replayed;
+    const token = randomUUID();
+    const fresh = {
+      token,
+      leadPid: pid,
+      cwd: cwd || null,
+      sse: null,
+      pendingRemoteStateFrame: null,
+      lastSeen: Date.now(),
+      registeredAt: Date.now(),
+      restoreSessionId: restoreId,
+    };
+    clients.set(token, fresh);
+    if (state.remoteAcquired && restoreId && restoreId === state.pinnedSessionId) fresh.remoteSessionId = restoreId;
+    state.everHadClient = true;
+    grace.cancel();
+    grace.resetBackoff();
+    grace.startSweep();
+    log(`client registered token=${token} lead=${pid} cwd=${cwd || '-'}`);
+    // The unified daemon starts the channels runtime (automation, webhooks)
+    // only once a CHANNELS client is actually present — a
+    // session runtime-only daemon must not run tunnels nobody asked for.
+    if (typeof onClientRegistered === 'function') {
+      try {
+        onClientRegistered({ token, leadPid: pid, cwd: cwd || null });
+      } catch {
+        // The registered-client hook must not fail the registration itself.
+      }
+    }
+    // Token replacement never crosses leadPid boundaries. Registration is
+    // otherwise transport-only, including same-pid fresh attaches.
+    const replaced = passive && replacementToken ? clients.get(replacementToken) : null;
+    if (replaced && replaced.leadPid === pid) adoptReplacedClient(fresh, replaced);
+    if (replayId) {
+      replays.remember(replayId, {
+        token,
+        leadPid: pid,
+        cwd: cwd || null,
+        replaceToken: replacementToken,
+        restoreSessionId: restoreId,
+        responseFinished: false,
+        timer: null,
+      });
+    }
+    return token;
+  }
+
+  return { registerClient, cancelReplacementRegistration };
+}

package/src/standalone/channel-transport/client-registry.mjs

@@ -3,6 +3,8 @@
  * transport: the live client records, registration with reconnect
  * replacement, pid-liveness pruning, and the UI control pointer lookup. The
  * supporting state machines live under ./client-registry/:
+ *   client-records       — live records, removal, pruning, pointer lookup
+ *   client-registration  — registration, replay and reconnect replacement
  *   registration-replays — response-loss replay records and their TTL
  *   client-grace         — self-shutdown grace timer + dead-pid sweep
  *   sse-attach           — binding a client's notify stream
@@ -11,14 +13,10 @@
  * pointerToken, everHadClient, closed, remoteAcquired, pinnedSessionId,
  * stickyRemoteFrame.
  */
-import { randomUUID } from 'node:crypto';
-import { isPidAlive, parsePid } from '../../runtime/shared/pid-liveness.mjs';
 import { createClientGrace } from './client-registry/client-grace.mjs';
-import {
-  createRegistrationReplays,
-  replayMatchesCancellation,
-  replayMatchesRegistration,
-} from './client-registry/registration-replays.mjs';
+import { createClientRecords } from './client-registry/client-records.mjs';
+import { createClientRegistration } from './client-registry/client-registration.mjs';
+import { createRegistrationReplays } from './client-registry/registration-replays.mjs';
 import { attachClientStream } from './client-registry/sse-attach.mjs';
 
 export function createClientRegistry({
@@ -37,162 +35,25 @@ export function createClientRegistry({
     ttlMs: registrationReplayTtlMs,
     onExpiredUnflushed: (token) => dropClient(token, 'unflushed registration replay expired'),
   });
-  const grace = createClientGrace({ state, clients, log, clientGraceMs, sweepMs, onClientsEmpty, pruneDeadClients });
-
-  // pid death is the authoritative signal for client liveness: a client whose
-  // SSE stream closed may still reconnect, one whose lead pid is gone cannot.
-  function pruneDeadClients() {
-    for (const [token, c] of clients) {
-      if (!isPidAlive(c.leadPid)) dropClient(token, 'pid dead');
-    }
-  }
-
-  function liveClients() {
-    const out = [];
-    for (const [token, c] of clients) {
-      if (isPidAlive(c.leadPid)) out.push([token, c]);
-    }
-    return out;
-  }
-
-  // Every removal path uses this primitive, including replacement's deliberate
-  // no-failover retirement, so replay records/timers never target absent tokens.
-  function removeClientRecord(token) {
-    const c = clients.get(token);
-    if (!c) return null;
-    clients.delete(token);
-    replays.forgetFor(token);
-    try {
-      c.sse?.end?.();
-    } catch {}
-    return c;
-  }
-
-  function dropClient(token, reason) {
-    const c = removeClientRecord(token);
-    if (!c) return;
-    if (state.pointerToken === token) state.pointerToken = null;
-    log(`client ${token} (lead=${c.leadPid}) removed: ${reason}`);
-    // Client presence is not channel authority. The durable session pin stays
-    // active until that same session explicitly turns Remote OFF.
-    publishRemoteState();
-    grace.maybeArm('client removed');
-  }
-
-  function cancelReplacementRegistration(request) {
-    const replay = replays.lookup(request.registrationId);
-    if (!replay) return 'missing';
-    if (!replayMatchesCancellation(replay, request)) return 'forbidden';
-    dropClient(replay.token, 'replacement deregister');
-    return 'cancelled';
-  }
-
-  // Resolve the active UI pointer for state delivery only. Session routing
-  // never depends on this client.
-  function resolveTarget() {
-    if (state.pointerToken) {
-      const c = clients.get(state.pointerToken);
-      if (c && isPidAlive(c.leadPid)) return c;
-      if (c) dropClient(state.pointerToken, 'pid dead (notify-time)');
-      else state.pointerToken = null;
-    }
-    return null;
-  }
-
-  /** A passive reconnect retrying under a known registration id gets the fresh
-   *  token it already created; a different identity under that id is a 409. */
-  function replayedToken(replayId, identity) {
-    const existing = replays.lookup(replayId);
-    if (!existing) return null;
-    if (replayMatchesRegistration(existing, identity) && clients.has(existing.token)) {
-      replays.arm(replayId, existing);
-      log(`client reconnect replay token=${existing.token} lead=${identity.pid}`);
-      return existing.token;
-    }
-    if (clients.has(existing.token)) {
-      const err = new Error('registration replay identity mismatch');
-      err.statusCode = 409;
-      throw err;
-    }
-    replays.remove(replayId, existing);
-    return null;
-  }
-
-  /** A reconnect names the exact token it replaces. Token-scoped state belongs
-   *  to the logical client, so the fresh record inherits the buffered frame,
-   *  remote session and pointer; the old token is retired even when it is not
-   *  the pointer — retaining it would let it later call or accumulate a
-   *  buffered frame after the fresh client has gone away. */
-  function adoptReplacedClient(fresh, replaced) {
-    const replacedWasPointer = state.pointerToken === replaced.token;
-    if (replaced.pendingRemoteStateFrame) {
-      fresh.pendingRemoteStateFrame = replaced.pendingRemoteStateFrame;
-      replaced.pendingRemoteStateFrame = null;
-    }
-    if (replaced.remoteSessionId) fresh.remoteSessionId = replaced.remoteSessionId;
-    if (replaced.restoreSessionId) fresh.restoreSessionId = replaced.restoreSessionId;
-    if (replacedWasPointer) state.pointerToken = fresh.token;
-    removeClientRecord(replaced.token);
-    log(`client reconnect replaced token=${replaced.token} -> ${fresh.token} lead=${fresh.leadPid}`);
-  }
-
-  function registerClient({
-    leadPid,
-    cwd,
-    passive = false,
-    replaceToken = null,
-    registrationId = null,
-    restoreSessionId = null,
-  }) {
-    const pid = parsePid(leadPid) ?? 0;
-    const restoreId = /^[A-Za-z0-9_-]+$/.test(String(restoreSessionId || '')) ? String(restoreSessionId) : null;
-    const replacementToken = replaceToken ? String(replaceToken) : null;
-    const replayId = passive && registrationId ? replays.replayIdOf(registrationId) : null;
-    const replayed = replayedToken(replayId, { pid, cwd, replacementToken, restoreId });
-    if (replayed) return replayed;
-    const token = randomUUID();
-    const fresh = {
-      token,
-      leadPid: pid,
-      cwd: cwd || null,
-      sse: null,
-      pendingRemoteStateFrame: null,
-      lastSeen: Date.now(),
-      registeredAt: Date.now(),
-      restoreSessionId: restoreId,
-    };
-    clients.set(token, fresh);
-    if (state.remoteAcquired && restoreId && restoreId === state.pinnedSessionId) fresh.remoteSessionId = restoreId;
-    state.everHadClient = true;
-    grace.cancel();
-    grace.resetBackoff();
-    grace.startSweep();
-    log(`client registered token=${token} lead=${pid} cwd=${cwd || '-'}`);
-    // The unified daemon starts the channels runtime (automation, webhooks,
-    // messaging provider) only once a CHANNELS client is actually present — a
-    // session runtime-only daemon must not run tunnels nobody asked for.
-    if (typeof onClientRegistered === 'function') {
-      try {
-        onClientRegistered({ token, leadPid: pid, cwd: cwd || null });
-      } catch {}
-    }
-    // Token replacement never crosses leadPid boundaries. Registration is
-    // otherwise transport-only, including same-pid fresh attaches.
-    const replaced = passive && replacementToken ? clients.get(replacementToken) : null;
-    if (replaced && replaced.leadPid === pid) adoptReplacedClient(fresh, replaced);
-    if (replayId) {
-      replays.remember(replayId, {
-        token,
-        leadPid: pid,
-        cwd: cwd || null,
-        replaceToken: replacementToken,
-        restoreSessionId: restoreId,
-        responseFinished: false,
-        timer: null,
-      });
-    }
-    return token;
-  }
+  const grace = createClientGrace({
+    state,
+    clients,
+    log,
+    clientGraceMs,
+    sweepMs,
+    onClientsEmpty,
+    pruneDeadClients: () => records.pruneDeadClients(),
+  });
+  const records = createClientRecords({ state, log, publishRemoteState, replays, grace });
+  const { liveClients, dropClient, resolveTarget } = records;
+  const { registerClient, cancelReplacementRegistration } = createClientRegistration({
+    state,
+    log,
+    onClientRegistered,
+    replays,
+    grace,
+    records,
+  });
 
   function attachSse(token, res) {
     const c = clients.get(token);

package/src/standalone/channel-transport.mjs

@@ -10,7 +10,7 @@
 // This module owns ONLY the transport (sockets, client registry, notify
 // routing and lifecycle). The channels runtime is injected via `handleCall`
 // so the same transport is exercised by the real daemon entry AND the smoke
-// harness (stub runtime, no Discord token).
+// harness (stub runtime).
 //
 // Composition root: the shared transport state below is read and written by
 // the sub-services in channel-transport/ (remote binding, client registry,