mixdog 1.3.5 → 1.4.0

package/src/session-runtime/setup-tool/tool-defs.mjs

@@ -6,10 +6,17 @@ import {
 } from './settings-contract.mjs';
 import { MEDIA_KINDS } from '../../runtime/media/tool-defs.mjs';
 import { INSTRUCTION_FILES_MODES } from '../../runtime/shared/instruction-files-mode.mjs';
+import {
+  DEFAULT_HEARTBEAT_INTERVAL_MINUTES,
+  HEARTBEAT_INTERVAL_CHOICES,
+} from '../../runtime/shared/heartbeat-interval.mjs';
 import { AUTO_EFFORT_BASES } from '../../runtime/agent/orchestrator/providers/auto-effort.mjs';
 import { WORKTREE_NEW_TASK_DEFAULTS } from '../../runtime/shared/worktrees/settings.mjs';
 import { CONNECTOR_IDS } from '../../runtime/shared/connector-catalog.mjs';
 import { COMPACTION_SUMMARY_MODES } from '../../runtime/agent/orchestrator/session/compact/summary-mode.mjs';
+import { ACTION_KINDS } from '../../runtime/agent/orchestrator/session/human-gate/outbound-policy.mjs';
+import { PERMISSION_MODES } from '../../runtime/agent/orchestrator/session/human-gate/store.mjs';
+import { CONNECTOR_PERMISSIONS } from '../../runtime/agent/orchestrator/mcp/agent-connectors.mjs';
 
 /** Built-in `setup` tool: the model's handle on a Mixdog user's persisted
  *  configuration. The description is a contract only; how to use each action
@@ -104,6 +111,7 @@ export const SETUP_ACTION_FIELDS = Object.freeze({
   set_quota_auto_resume: 'enabled',
   set_model_preferences: 'provider model hidden? favorite?',
   set_heartbeat_enabled: 'enabled',
+  set_heartbeat_interval: 'minutes',
   set_reactions_enabled: 'enabled',
   forget_provider_auth: 'name accountId?',
   set_provider_account: 'name providerAccount',
@@ -121,6 +129,19 @@ export const SETUP_ACTION_FIELDS = Object.freeze({
   enable_plugin_mcp: 'name',
   connect_connector: 'connector',
   set_worktree_settings: 'worktree',
+  reset_route_fallback: 'sessionId? agent?',
+  continue_in_model: 'sessionId route',
+  schedule_quota_resume: 'sessionId',
+  cancel_quota_resume: 'sessionId',
+  set_cache_warming_enabled: 'enabled',
+  read_agent_settings: 'agent',
+  read_project_connectors: 'projectPath',
+  set_agent_permission: 'agent actionKind permissionMode',
+  set_agent_connector: 'agent name enabled',
+  set_agent_connector_tool: 'agent name tool permission',
+  set_project_connector: 'projectPath name enabled',
+  restore_definition: 'definitionKind name',
+  set_bot_order: 'botOrder',
   ...SETUP_EXTENDED_ACTION_FIELDS,
 });
 
@@ -170,7 +191,7 @@ const ROUTE_SCHEMA = {
 ROUTE_SCHEMA.properties.fallbacks = {
   type: 'array',
   description:
-    'Lead (set_route), agent (bots included) and Web Search routes only: ordered fallback models tried when the model hits its usage limit or is unavailable; [] clears the list.',
+    'Lead (set_route), agent (bots included) and Web Search routes only: ordered fallback models tried when the model hits its usage limit or is unavailable, each on another provider; [] clears the list. Running sessions on that route read it at their next hop.',
   items: {
     type: 'object',
     additionalProperties: false,
@@ -219,7 +240,11 @@ export const SETUP_TOOL_DEFS = Object.freeze([
           description:
             'Partial route update; omitted fields are preserved. Agent or Web Search provider "" restores Main inheritance. contextPercent and contextTokens apply to Main and agent routes only.',
         },
-        agent: { type: 'string', description: 'set_agent_route: agent id.' },
+        agent: {
+          type: 'string',
+          description:
+            'Agent or bot id (lead = Mixy): set_agent_route, read_agent_settings, set_agent_permission, set_agent_connector(_tool); reset_route_fallback: every chat of that bot.',
+        },
         workflow: { type: 'string', description: 'set_workflow: pack id.' },
         style: { type: 'string', description: 'set_output_style: style id.' },
         profile: {
@@ -272,7 +297,7 @@ export const SETUP_TOOL_DEFS = Object.freeze([
         enabled: {
           type: 'boolean',
           description:
-            'Boolean setters (set_*_enabled, set_compaction, set_auto_update, set_ai_session_titles, set_quota_auto_resume, set_heartbeat_enabled, set_mcp_enabled, set_plugin_enabled).',
+            'Boolean setters (set_*_enabled, set_compaction, set_auto_update, set_ai_session_titles, set_quota_auto_resume, set_heartbeat_enabled, set_mcp_enabled, set_plugin_enabled, set_agent_connector, set_project_connector).',
         },
         provider: { type: 'string', description: 'set_model_preferences: provider id.' },
         hidden: {
@@ -297,12 +322,12 @@ export const SETUP_TOOL_DEFS = Object.freeze([
         },
         name: {
           type: 'string',
-          description: `set_builtin_enabled: ${SETUP_BUILTIN_TOGGLE_FEATURES.join('|')}; install_builtin also accepts memory. Memory toggles use set_memory_enabled. revoke_linked_device: client id from status connection, not its display name; set_developer_option: option id from status developer; read_definition/delete_definition: the definition id; reconnect_mcp: optional MCP server name (omit for all); else MCP/plugin/provider id.`,
+          description: `set_builtin_enabled: ${SETUP_BUILTIN_TOGGLE_FEATURES.join('|')}; install_builtin also accepts memory. Memory toggles use set_memory_enabled. revoke_linked_device: client id from status connection, not its display name; set_developer_option: option id from status developer; read_definition/delete_definition: the definition id; reconnect_mcp: optional MCP server name (omit for all); set_agent_connector(_tool)/set_project_connector: connector (MCP server) id from read_agent_settings; restore_definition: archived agent id; else MCP/plugin/provider id.`,
         },
         accountId: {
           type: 'string',
           description:
-            'forget_provider_auth: OAuth account id from status providers with detail:true; required when the provider has several accounts. set_media_default: optional account of the OAuth lane to pin; omitted = the lane provider\'s selected account.',
+            "forget_provider_auth: OAuth account id from status providers with detail:true; required when the provider has several accounts. set_media_default: optional account of the OAuth lane to pin; omitted = the lane provider's selected account.",
         },
         providerAccount: {
           type: 'object',
@@ -350,6 +375,11 @@ export const SETUP_TOOL_DEFS = Object.freeze([
           maximum: 86400,
           description: 'set_local_idle_ttl: unload after this many idle seconds, 0 disables; default 3600.',
         },
+        minutes: {
+          type: 'integer',
+          enum: [...HEARTBEAT_INTERVAL_CHOICES],
+          description: `set_heartbeat_interval: minutes between Mixy's heartbeat checks; default ${DEFAULT_HEARTBEAT_INTERVAL_MINUTES}.`,
+        },
         query: { type: 'string', description: 'search_local_models: Hugging Face GGUF search query.' },
         repository: { type: 'string', description: 'inspect_hf_model: public Hugging Face owner/model repository.' },
         filename: {
@@ -427,6 +457,35 @@ export const SETUP_TOOL_DEFS = Object.freeze([
           },
           description: 'set_worktree_settings: only the given fields change.',
         },
+        sessionId: {
+          type: 'string',
+          description:
+            'reset_route_fallback (default: this session), continue_in_model, schedule_quota_resume, cancel_quota_resume: session id from status model/agents or the session tool. The last three take another session.',
+        },
+        actionKind: {
+          type: 'string',
+          enum: [...ACTION_KINDS],
+          description: "set_agent_permission: the action kind row of the agent's permission table.",
+        },
+        permissionMode: {
+          type: 'string',
+          enum: [...PERMISSION_MODES],
+          description:
+            'set_agent_permission: block or ask; allow (and any change that lets an agent do more without asking) is made by the person in the desktop app.',
+        },
+        tool: { type: 'string', description: 'set_agent_connector_tool: tool name within the connector `name`.' },
+        permission: {
+          type: 'string',
+          enum: [...CONNECTOR_PERMISSIONS],
+          description: 'set_agent_connector_tool: needs_approval or disabled; auto is made in the desktop app.',
+        },
+        botOrder: {
+          type: 'array',
+          items: { type: 'string', minLength: 1, pattern: '\\S' },
+          maxItems: 500,
+          description:
+            'set_bot_order: bot ids in display order (Mixy is always first and not listed); [] = default order.',
+        },
         ...SETUP_EXTENDED_PROPERTIES,
       },
     },

package/src/session-runtime/tool-policy/agent-profile-fold.mjs

@@ -19,6 +19,8 @@ import {
 } from '../../runtime/agent/orchestrator/mcp/agent-connectors.mjs';
 import { agentListEntries } from '../../runtime/agent/orchestrator/session/manager/prompt-utils.mjs';
 import { markToolSurfaceMigrated } from '../../runtime/agent/orchestrator/session/loop/tool-exposure-migration.mjs';
+import { resetBp2StableContext } from '../../runtime/agent/orchestrator/context/collect.mjs';
+import { requestPrefixIdentity } from '../../runtime/agent/orchestrator/session/thinking-binding.mjs';
 import {
   agentProfileRevision,
   leadRosterRevision,
@@ -40,15 +42,6 @@ const PROMPT_FOLD_INTENT = 'prompt_fold';
 // Cache-break intents that already rebuild the conversation's cached prefix.
 const COLD_INTENTS = new Set(['post_turn_compaction', 'manual_compaction']);
 
-// What the next request sends ahead of the conversation: the system blocks and tools.
-const promptPrefix = (session) =>
-  JSON.stringify([
-    (Array.isArray(session.messages) ? session.messages : [])
-      .filter((message) => message?.role === 'system')
-      .map((message) => message.content),
-    session.tools,
-  ]);
-
 // A bot thread built from other shipped rules than these (a release changed one).
 const rulesStale = (session) =>
   sessionModeOf(session) === AGENT_MODE && session.rulesRevision !== promptRulesRevision();
@@ -208,7 +201,10 @@ export function createAgentProfileFold({
     const config = configForSession(getConfig(), session.workflow?.id, currentMode(session));
     const staged = await stagePolicy(session, identity, config, { conversation: true });
     if (getSession?.() !== session) return false;
-    const before = promptPrefix(session);
+    const before = requestPrefixIdentity(session);
+    // BP2 (profile meta, skill manifest) from current sources too; applyPolicy
+    // re-appends its deferred manifest.
+    if (typeof staged.stableContext === 'string') resetBp2StableContext(session, staged.stableContext);
     applyPolicy(session, staged);
     rewriteConversationBp3Core(session, staged.core);
     if (session.agentProfileRevision !== undefined) {
@@ -218,17 +214,25 @@ export function createAgentProfileFold({
     }
     if (agentMode) session.rulesRevision = promptRulesRevision();
     session.updatedAt = Date.now();
-    if (promptPrefix(session) === before) return false;
+    if (requestPrefixIdentity(session) === before) return false;
     markToolSurfaceMigrated(session, session.pendingCacheBreakIntent || intent);
     return true;
   }
 
   /** Fold pending prompt changes (a switched workflow, a bot's moved tool
-   *  gates, changed shipped rules) when the cache is cold anyway. */
+   *  gates, changed shipped rules) when the cache is cold anyway. A
+   *  compaction rebuilds the prompt from current sources whether or not
+   *  anything is known pending (an update can change shipped rules, skills
+   *  and manifests no stamp tracks); an unchanged prompt stays byte-identical
+   *  and adds no break. */
   async function foldPromptIfCold() {
     const session = getSession?.();
+    // Scope exception: delegated worker sessions (`owner: 'agent'`) keep the
+    // prompt they were created with; they are task-scoped, and their skill
+    // bodies are still restored from current sources at Compact.
     if (!session?.id || !session.promptIdentity || isAgentOwner(session)) return false;
-    if (!foldPending(session) || !cacheCold(session)) return false;
+    const compacted = COLD_INTENTS.has(session.pendingCacheBreakIntent);
+    if (!compacted && !(foldPending(session) && cacheCold(session))) return false;
     return foldPrompt(session, PROMPT_FOLD_INTENT);
   }
 

package/src/session-runtime/tool-policy/policy-stage.mjs

@@ -11,9 +11,14 @@ import {
 import { deferredSurfaceModeForLead } from '../../runtime/agent/orchestrator/runtime-core/effort.mjs';
 import {
   applyInitialDeferredToolManifestToBp2,
+  buildSkillManifest,
+  collectPromptSkillsCached,
   composeSystemPrompt,
 } from '../../runtime/agent/orchestrator/context/collect.mjs';
-import { _buildBaseRules } from '../../runtime/agent/orchestrator/session/manager/rules-cache.mjs';
+import {
+  _buildBaseRules,
+  _buildLeadMetaContext,
+} from '../../runtime/agent/orchestrator/session/manager/rules-cache.mjs';
 import { sessionRolePromptFields } from '../../runtime/agent/orchestrator/session/manager/session-prompt-composition.mjs';
 import {
   delegationDisabled,
@@ -134,7 +139,12 @@ export function createPolicyStage({
             model: getRoute()?.model,
           });
     const coreMemoryContext = conversation ? '' : await leadCoreMemoryContext();
-    const { sessionMarkerCore } = composeSystemPrompt({
+    // BP2's stable part as session creation composes it
+    // (session-prompt-composition.mjs): the Lead meta context and the skill
+    // manifest of the skills in scope now.
+    const skipRules = identity.skipAgentRules || toolFreeRole;
+    const skills = schemaAllowedTools?.length === 0 ? [] : collectPromptSkillsCached(session.cwd);
+    const { sessionMarkerCore, stableSystemContext } = composeSystemPrompt({
       ...sessionRolePromptFields(identity, {
         ownerIsAgent,
         toolFreeRole,
@@ -149,6 +159,8 @@ export function createPolicyStage({
       // setting; agent mode carries none.
       instructionFilesContext:
         conversation || toolFreeRole || agentMode ? null : loadInstructionFilesContext?.(session) || null,
+      metaContext: skipRules || ownerIsAgent ? undefined : _buildLeadMetaContext({ includeOutputStyle: !agentMode }),
+      skillManifest: buildSkillManifest(skills),
     });
     return {
       workflow,
@@ -159,6 +171,8 @@ export function createPolicyStage({
       ownerIsAgent,
       baseRules,
       core: conversation ? withPresentedWorkspaceSlices(session, sessionMarkerCore) : sessionMarkerCore,
+      // Without BP1 the BP2 block cannot be located: null leaves it as it is.
+      stableContext: skipRules ? null : stableSystemContext,
     };
   }
 

package/src/session-runtime/turn/turn-run/ask-callbacks.mjs

@@ -80,6 +80,7 @@ export function createAskCallbacks({ transcript, notifyFnForSession, scheduleSea
       beforeToolExecution: () => turn.snapshot.promise || Promise.resolve(),
       transcriptMeta: stampCheckpoint(options),
       promptSource: options.promptSource,
+      ...(options.promptOrigin ? { promptOrigin: options.promptOrigin } : {}),
       // A routine turn's trusted selection text (its instructions only).
       ...(typeof options.skillSelection === 'string' ? { skillSelection: options.skillSelection } : {}),
       retryFailedTurn: options.retryFailedTurn === true,

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/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);