@staix/agent-hub 0.12.44 → 0.12.45

package/src/hub/daemon.ts

@@ -1,3 +1,4 @@
+import { loadExternalAdapterDefinitions, readAdapterModuleDeclarations, type AdapterModuleDeclaration } from "../adapters/external-modules.ts";
 import { WsPeer, isWsPeer } from "../adapters/channel-peer.ts";
 import { ownerToolEffect, canonicalWriteUnknown } from "./no-writes.ts";
 import { NativeHookLaunches } from "./native-hook-launch.ts";
@@ -26,7 +27,7 @@ import { JcodeOptionMismatch, isJcodePeer, type JcodePeer } from "../adapters/jc
 import { jcodeMcpReady } from "../cli/jcode-mcp.ts";
 import { loadSdlc, readSpecEdit, sdlcGh } from "./sdlc.ts";
 import { claudePeer as defaultChannelPeer, claudeStateFile, ownTerminalRow, pathEvidence, transcriptPersisted } from "./claude-state.ts";
-import { peerRosterConfig, rosterAllows, type PeerRoster } from "./roster.ts";
+import { peerRosterConfig, rosterAllows, staleInstanceKey, type PeerRoster } from "./roster.ts";
 import { KNOWN_PEERS, OPTIONAL_PEERS, PLANNER_PEERS, SUPPORTED_PEERS, START_MODE_PEERS, isSupportedPeer, STARTABLE_PEERS, isStartablePeer } from "../adapters/registry.ts";
 import { RecoveryDeferredHubError } from "./deferred-hub.ts";
 import { databaseBusySite, isDatabaseBusy, RecoveryDatabaseBusy } from "./recovery-error.ts";
@@ -93,7 +94,7 @@ import { AssignmentUndeliveredError, ESCALATE_AFTER, Tasks } from "./tasks.ts";
 import { DEFAULT_INFERENCE, DIGEST, Inference, screenPii, type InferenceConfig } from "./inference.ts";
 import { ask, ASK_NOTE_TITLE, RUN_START } from "./ask.ts";
 import { currentRouting, loadRouting, detectSignals, OVERLAY_FILE, overlayToml, parseRouting, routingText, type Routing } from "./routing.ts";
-import { projectSettings, checkSettingValue, ignoredLine, pendingUndo, pendingUndoIdentity, readOverlay, restoredValue, routingCandidate, storedLocally, settingDef as instanceSettingDef, settingRefusal, settingRows, settingText, undoSetting, valueAt, writeConfigSetting, writeRoutingSetting, type SettingAuthority, type SettingDef, type SettingRow, type SettingValue, type UndoIdentity } from "./settings.ts";
+import { projectSettings, checkSettingValue, ignoredLine, pendingUndo, pendingUndoIdentity, readOverlay, restoredValue, routingCandidate, storedLocally, sharedValue, settingDef as instanceSettingDef, settingRefusal, settingRows, settingText, undoSetting, valueAt, writeConfigSetting, writeRoutingSetting, type SettingAuthority, type SettingDef, type SettingRow, type SettingValue, type UndoIdentity } from "./settings.ts";
 import { Bus } from "./bus.ts";
 import { attribute, deliveryTask, type TaskAttribution } from "./attribution.ts";
 import { DeliveryJournal } from "./delivery-journal.ts";
@@ -112,7 +113,7 @@ import { Facts, FACTS_PREFIX, type FactScope } from "./facts.ts";
 import { crashPlan, lossNotice, readSessions, removeSessions, writeSessions, type SessionsFile } from "./crash.ts";
 import type { JournalDelivery } from "./delivery-journal.ts";
 import { DEFAULT_LIMITS, Limiter, PROJECT_LIMITS, type LimitsConfig } from "./limits.ts";
-import { soleWorktree, branchHeads, changedPaths, knownChangedPaths, hasTree, headState, headMoveCursor, incomingHeadPaths, repoOf, snapshot, SnapshotBudgetExceeded, Turns, type SnapshotBudget, type HeadMoveCursor, type Repo, type TurnRecord } from "./snapshots.ts";
+import { soleWorktree, branchHeads, changedPaths, knownChangedPaths, hasTree, headState, headMoveCursor, incomingHeadPaths, repoOf, snapshot, SnapshotBudgetExceeded, budgetNow, Turns, type SnapshotBudget, type HeadMoveCursor, type Repo, type TurnRecord } from "./snapshots.ts";
 import { archiveRestartSnapshot, readRecoveryWaivers, readRestartSnapshot, removeRestartSnapshot, restartPath, writeRestartSnapshot, type RecoveryPhase, type RestartPeerSnapshot, type RestartSnapshot } from "./restart.ts";
 import { consumeRecoveryContinuity, readRecoveryContinuity, retireRecoveryContinuity } from "./recovery-continuity.ts";
 import { shellQuote, publishTerminalLaunch, terminalLaunchCandidate } from "../cli/terminal-recovery.ts";
@@ -134,6 +135,7 @@ import { nativeRecall } from "../memory/recall.ts";
 import { promotionScreen, withoutPii, mentionsPrivatePath } from "./memory-policy.ts";
 
 export interface HubConfig {
+  adapter_modules?: readonly AdapterModuleDeclaration[];
   adapters?: Readonly<Record<string, import("../adapters/configured-acp.ts").ConfiguredAcpAdapterConfig>>;
   /** Person-owned declarations, read only from an untracked machine-local file. Bound for this daemon lifetime. */
   instances?: InstancesConfig;
@@ -322,12 +324,13 @@ function retiredRoutingSettings(cwd: string): readonly string[] {
   catch { return []; } // Routing admission and reload report parse errors using their own last-good state.
 }
 
-export function loadConfig(cwd: string, layers?: readonly ConfigLayer[], routingRetired: readonly string[] = retiredRoutingSettings(cwd)): HubConfig {
+export function loadConfig(cwd: string, layers?: readonly ConfigLayer[], routingRetired: readonly string[] = retiredRoutingSettings(cwd), externalDefinitions?: readonly import("../adapters/registry-types.ts").AdapterDefinition[]): HubConfig {
   const captured = layers ?? readInstanceConfigLayers(cwd);
-  const instanceConfig = readInstanceConfig(cwd, captured);
+  const instanceConfig = readInstanceConfig(cwd, captured, externalDefinitions);
   const instances = instanceConfig.instances;
   const adapterCatalog = instanceConfig.catalog;
   const ignored: string[] = [...instanceConfig.ignored];
+  const inertModuleRoster = !!instanceConfig.adapter_modules?.length;
   const appliedPermissionSources: NonNullable<HubConfig["permission_default_sources"]> = {};
   const files = CONFIG_FILES.flatMap((name) => {
     let file: Record<string, any>; // parsed JSON, checked field by field below
@@ -338,9 +341,10 @@ export function loadConfig(cwd: string, layers?: readonly ConfigLayer[], routing
       if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
       throw error;
     }
+    delete file.adapter_modules; // Code provenance is captured separately and never evaluated by configuration reads.
     delete file.adapters; // Adapter provenance is compiled by the same project-local loader.
     delete file.instances; // Declaration authority was checked against its exact captured origin above.
-    peerRosterConfig(file.roster, instances, adapterCatalog);
+    peerRosterConfig(file.roster, instances, adapterCatalog, inertModuleRoster);
     catalogAssignments(file.catalog_roles);
     profileName(file.profile);
     resolveProfile(file.profile, file.profile_overrides);
@@ -412,6 +416,7 @@ export function loadConfig(cwd: string, layers?: readonly ConfigLayer[], routing
     ...DEFAULT_CONFIG,
     ...file,
     ...(instanceConfig.adapters ? { adapters: instanceConfig.adapters } : {}),
+    ...(instanceConfig.adapter_modules ? { adapter_modules: instanceConfig.adapter_modules } : {}),
     ...(instances ? { instances } : {}),
     ...(file.text_projection !== undefined ? { text_projection: projectionConfig(file.text_projection) } : {}),
     ...(file.pii !== undefined ? { pii: { paths: policyPaths(file.pii.paths, "pii.paths") } } : {}),
@@ -421,7 +426,7 @@ export function loadConfig(cwd: string, layers?: readonly ConfigLayer[], routing
     permission_default_sources: appliedPermissionSources,
     memory: { ...DEFAULT_CONFIG.memory, native: true, ...file.memory, ...(file.memory?.short_ttl_days !== undefined ? { short_ttl_days: ttlDays(file.memory.short_ttl_days) } : {}),
       ...(file.memory?.sync_interval_min !== undefined ? { sync_interval_min: syncMinutes(file.memory.sync_interval_min) } : {}) }, // the native store is on with any project config (#258)
-    roster: peerRosterConfig(file.roster, instances, adapterCatalog),
+    roster: peerRosterConfig(file.roster, instances, adapterCatalog, inertModuleRoster),
     roles: { ...configuredRoles, ...conductorPolicy.roles, ...extraRoles },
     planner: conductorPolicy.planner,
     conductor: conductorPolicy.conductor,
@@ -476,6 +481,8 @@ export interface DaemonOptions {
   /** Host-only snapshot/probe seams; never read from project config or tool arguments. */
   snapshot?: typeof snapshot;
   snapshotBurstMs?: number;
+  /** Host-only (#661): the clock the shared snapshot Git budget reads (default performance.now). A test holds it fixed so a slow runner cannot spend the 250 ms; production never sets it and no config key or tool reaches it. */
+  snapshotClock?: () => number;
   checkoutBranch?: typeof mainCheckoutBranch;
   /** Host-only admission transport; never selected by project config or tools. */
   releaseHostAdmission?: (cwd: string) => Promise<ReleaseHostAdmission>;
@@ -531,12 +538,21 @@ export async function startDaemon(opts: DaemonOptions) {
   const startupCleanup: (() => void)[] = [];
   let ready = false;
   try {
-  const loadedConfig = opts.config ?? loadConfig(opts.cwd);
+  let startupLayers: ReturnType<typeof readInstanceConfigLayers>;
+  try { startupLayers = readInstanceConfigLayers(opts.cwd); }
+  catch (error) { if (!opts.config) throw error; startupLayers = []; } // Explicit embeddings may ignore unreadable file config; no code is loaded from it.
+  const externalAdapterRefusals: import("../adapters/external-modules.ts").ExternalAdapterRefusalRecord[] = [];
+  const externalDefinitions = await loadExternalAdapterDefinitions(opts.cwd, startupLayers, refusal => externalAdapterRefusals.push(refusal));
+  const externalAdapters = externalDefinitions.map(({ kind, displayName }) => ({ kind, displayName }));
+  const externalIds = new Set(externalAdapters.map(item => item.kind));
+  const moduleDeclarations = readAdapterModuleDeclarations(opts.cwd, startupLayers).modules;
+  const loadedConfig = opts.config ? { ...opts.config, adapter_modules: moduleDeclarations.length ? moduleDeclarations : undefined }
+    : loadConfig(opts.cwd, startupLayers, undefined, externalDefinitions);
   reviewerPoolConfig(loadedConfig.review, DEFAULT_REVIEW_POOL, REVIEW_POOL_KINDS);
   const lifecycleConfig = loadSdlc(opts.cwd, VERSION);
   // Preserve embedding-owned policy references, but never publish reloads into shared defaults.
   const ownedConfig = Object.fromEntries(Object.entries(loadedConfig).map(([key, value]) => [key, !opts.config || value === (DEFAULT_CONFIG as unknown as Record<string, unknown>)[key] ? structuredClone(value) : value])) as unknown as HubConfig;
-  const adapterCatalog = createProjectAdapterCatalog(loadedConfig.adapters);
+  const adapterCatalog = createProjectAdapterCatalog(loadedConfig.adapters, externalDefinitions);
   const configuredIds = adapterCatalog.definitions.filter(d => !builtinDefinitionOf(d.kind)).map(d => d.kind);
   const declarations = validateInstances(loadedConfig.instances, adapterCatalog);
   const extraIds = Object.keys(declarations);
@@ -562,7 +578,7 @@ export async function startDaemon(opts: DaemonOptions) {
     }
   }
   const config: HubConfig = { ...ownedConfig, ...(extraIds.length ? { instances: declarations } : {}),
-    roster: peerRosterConfig(loadedConfig.roster, declarations, adapterCatalog),
+    roster: peerRosterConfig(loadedConfig.roster, declarations, adapterCatalog, moduleDeclarations.length > 0),
     permission_modes: { ...permissionModesFromInstances, ...permissionDefaults(loadedConfig.permission_modes, declarations, adapterCatalog) },
     peers: { ...startModesFromInstances, ...peerStartConfig(loadedConfig.peers, declarations, adapterCatalog) },
     ...(extraIds.length ? { permission_default_sources: { ...instancePermissionSources, ...loadedConfig.permission_default_sources } } : {}),
@@ -585,7 +601,16 @@ export async function startDaemon(opts: DaemonOptions) {
   const reviewOnlyItem = (peer: string, env: Envelope): boolean => env.from === USER || env.from === HUB && (env.kind === "review" || (env.kind === "task" && env.to?.includes(peer) === true));
   const readOnlyPeer = (peer: string): boolean => declarations[peer]?.readOnly === true;
   const SETTINGS = projectSettings(declarations, adapterCatalog);
-  const settingDef = (key: unknown) => instanceSettingDef(key, declarations, adapterCatalog);
+  // #225: a roster key whose instance was undeclared has no row of its own. The only thing a person can do with it is delete it,
+  // so it gets a boolean roster row that checkSettingValue below only accepts as a removal.
+  const staleRosterKey = (key: unknown): string | undefined => {
+    const peer = typeof key === "string" && key.startsWith("roster.") ? key.slice("roster.".length) : undefined;
+    return peer !== undefined && !declarations[peer] && Object.hasOwn(config.roster, peer) && staleInstanceKey(peer, adapterCatalog) ? peer : undefined;
+  };
+  const settingDef = (key: unknown): SettingDef | string => {
+    const found = instanceSettingDef(key, declarations, adapterCatalog), stale = staleRosterKey(key);
+    return typeof found === "string" && stale ? { key: `roster.${stale}`, group: "Roster", label: `${stale}: stale roster key (instance no longer declared)`, type: "boolean", store: "config", applies: "live", risk: "raises", floor: false, path: ["roster", stale] } : found;
+  };
   const accountOf = (peer: string) => definitionOf(peer)?.budget?.account ?? peer;
   const accountMembers = (account: string) => SUPPORTED_PEERS.filter(peer => accountOf(peer) === account);
   let rosterChanging: string | undefined;
@@ -593,7 +618,8 @@ export async function startDaemon(opts: DaemonOptions) {
   let kimiAdmissionId: string | undefined;
   let kimiAdmissionExpiry: ReturnType<typeof setTimeout> | undefined;
   const clearKimiAdmission = () => { clearTimeout(kimiAdmissionExpiry); kimiAdmissionExpiry = undefined; kimiSessionMode = undefined; kimiAdmissionId = undefined; };
-  const onRoster = (peer: string) => rosterAllows(config.roster, peer, config.pi.enabled, declarations, adapterCatalog);
+  const projectRosterAllows = (roster: PeerRoster, peer: string, piEnabled: boolean) => rosterAllows(roster, peer, piEnabled, declarations, adapterCatalog, moduleDeclarations.length > 0);
+  const onRoster = (peer: string) => projectRosterAllows(config.roster, peer, config.pi.enabled);
   // pi.enabled historically gates starts, not retained queues or tools sockets. Only an explicit roster.pi changes those.
   const membershipAllowed = (peer: string) => definitionOf(peer)?.enabledSwitchStartOnly && config.roster[peer] === undefined ? true : onRoster(peer);
   conductorPeer(config.roles); // reject ambiguous leadership before opening a control listener
@@ -604,7 +630,7 @@ export async function startDaemon(opts: DaemonOptions) {
   // The state dir can vanish under a running hub (issue #56): a log line must never take a handler down with it.
   const log = (line: string) => { try { appendFileSync(logFile, `${new Date().toISOString()} ${line}\n`); } catch { /* the state dir is gone; the watchdog is stopping the hub */ } };
   let runningRouting = currentRouting(opts.cwd, log);
-  let acceptedSources = parseConfigSources(configSourceTexts(opts.cwd), runningRouting, opts.cwd);
+  let acceptedSources = parseConfigSources(configSourceTexts(opts.cwd), runningRouting, opts.cwd, externalAdapters);
   const startupSources = structuredClone(acceptedSources.trustLayers);
   const embeddedConfig = structuredClone(config);
   let desiredConfig = structuredClone(config);
@@ -1193,8 +1219,9 @@ export async function startDaemon(opts: DaemonOptions) {
     if (!peer || peer.state === "offline") return undefined;
     let token = checkConnections.get(peer);
     if (!token) { token = randomUUID(); checkConnections.set(peer, token); }
-    const native = isWsPeer(peer) || isCodexPeer(peer) || isPiPeer(peer) ? peer.sessionGeneration : peer.recoveryMetadata?.().sessionId;
-    if (isPiPeer(peer) && native === undefined) return undefined;
+    const hasGeneration = "sessionGeneration" in peer;
+    const native = hasGeneration ? peer.sessionGeneration : peer.recoveryMetadata?.().sessionId;
+    if (hasGeneration && native === undefined) return undefined;
     return `${instanceId}:${token}:${String(native ?? "")}`;
   };
   const currentCheck = (receipt: { task: number; owner: string; updated: number | string; generation: number | string; revision?: number }) => {
@@ -1672,8 +1699,9 @@ export async function startDaemon(opts: DaemonOptions) {
     const owner = bus.peers.get(peer);
     const state = bus.stateOf(peer);
     const session = contextSession(peer);
-    const generation = isWsPeer(owner) || isCodexPeer(owner) ? owner.sessionGeneration : undefined;
-    if (!owner || (isWsPeer(owner) && owner.claiming) || (state !== "idle" && state !== "busy") || (reason === "context" && (!session || turns.get(peer)?.private || contextPii(peer)))) return Promise.resolve(undefined);
+    const generationFenced = !!owner && owner.checkpointUsesSessionGeneration !== false && "sessionGeneration" in owner;
+    const generation = generationFenced ? owner.sessionGeneration : undefined;
+    if (!owner || (generationFenced && generation === undefined) || (isWsPeer(owner) && owner.claiming) || (state !== "idle" && state !== "busy") || (reason === "context" && (!session || turns.get(peer)?.private || contextPii(peer)))) return Promise.resolve(undefined);
     const openWork = board.list().some((t) => (["proposed", "in_progress", "changes_requested", "in_review"].includes(t.state) && t.owner === peer) || (t.state === "in_review" && t.reviewer === peer));
     if (!openWork && !bus.queued(peer) && !bus.hasInFlight(peer) && state !== "busy") {
       if (reason === "quota") log(`budget ${peer}: no open work, no checkpoint`);
@@ -1685,7 +1713,7 @@ export async function startDaemon(opts: DaemonOptions) {
       : `Checkpoint request: your native context window is near the configured threshold. Finish the step you are on and call hub_checkpoint {summary, request_id: "${requestId}"} with what you were doing, what is half done and what a fresh session would need. This only saves a checkpoint; keep your tasks and session. The operator decides whether to continue or restart. Do not include private task text.`;
     const ask = newEnvelope(HUB, body, { to: [peer], kind: "budget", priority: "important" });
     return new Promise((resolve) => {
-      const valid = () => !stopping && !recoveryActive() && bus.peers.get(peer) === owner && (!(isWsPeer(owner) || isCodexPeer(owner)) || owner.sessionGeneration === generation) && ["idle", "busy"].includes(bus.stateOf(peer)) && contextSession(peer) === session;
+      const valid = () => !stopping && !recoveryActive() && bus.peers.get(peer) === owner && (!generationFenced || owner.sessionGeneration === generation) && ["idle", "busy"].includes(bus.stateOf(peer)) && contextSession(peer) === session;
       const done = (summary: string | undefined) => {
         clearTimeout(timer);
         checkpointWaits.delete(peer);
@@ -1815,7 +1843,8 @@ export async function startDaemon(opts: DaemonOptions) {
     if (!snapshotBudget) {
       const requested = opts.snapshotBurstMs ?? 250;
       const ms = Number.isFinite(requested) ? Math.max(1, Math.min(250, requested)) : 250;
-      snapshotBudget = { deadline: performance.now() + ms };
+      const now = opts.snapshotClock;
+      snapshotBudget = { deadline: (now ? now() : performance.now()) + ms, ...(now ? { now } : {}) };
       setImmediate(() => { snapshotBudget = undefined; snapshotBudgetNoticed = false; });
     }
     return snapshotBudget;
@@ -2309,7 +2338,7 @@ export async function startDaemon(opts: DaemonOptions) {
         await tasks.specStageGate(by, a.id, a.receipt); // #481 S1: a live spec edit-time check before a build stage
         return line(tasks.recordLifecycle(by, a.id, a.receipt));
       case "hub_review":
-        return line(await tasks.review(by, a.id, a.verdict, a.note, a.unmet, a.head, a.coverage));
+        return line(await tasks.review(by, a.id, a.verdict, a.note, a.unmet, a.head, a.coverage, a.findings));
       case "hub_remember":
         return tasks.remember(by, a);
       case "hub_checkpoint": {
@@ -2684,13 +2713,14 @@ export async function startDaemon(opts: DaemonOptions) {
   };
   const permissionDisplay = (id: string, peer: PeerAdapter | undefined): string => {
     if (readOnlyPeer(id)) return "read-only";
-    if (isAcpPeer(peer) && ["unknown", "unmanaged"].includes(peer.permissionModeState)) return peer.permissionModeState;
-    if (starting.has(id) && (isAcpPeer(peer) || isCodexPeer(peer))) return peer.getPermissionMode();
     if (definitionOf(id)?.transport === "claude-channel" && isWsPeer(peer) && peer.state !== "offline") {
       const launch = claudePermissionLaunch(id);
       if (!launch || claudePermissionGenerations.get(id) !== peer.sessionGeneration) return "unverified";
     }
-    return permissionMode(id);
+    const native = peer?.permissionModeState;
+    // An offline ask clears the hub choice, not a stopped ACP runtime's retained native field.
+    if (peer?.state === "offline" && !starting.has(id) && isPermissionMode(native)) return permissionMode(id);
+    return native ?? permissionMode(id);
   };
   const permissionStatus = (id: string, peer: PeerAdapter | undefined): Record<string, unknown> => {
     const note = definitionOf(id)?.permission.unmanagedStatusNote;
@@ -2745,6 +2775,8 @@ export async function startDaemon(opts: DaemonOptions) {
     protocol: PROTOCOL,
     features: DAEMON_FEATURES,
     configuredAdapters: configuredIds,
+    ...(externalAdapters.length ? { externalAdapters } : {}),
+    ...(externalAdapterRefusals.length ? { externalAdapterRefusals } : {}),
     startablePeers: SUPPORTED_PEERS.filter(isStartablePeer),
     readOnlyPeers: extraIds.filter(readOnlyPeer),
     // #450 I3: the instance ids this daemon bound at startup; a launcher selects only one of these.
@@ -3156,7 +3188,7 @@ export async function startDaemon(opts: DaemonOptions) {
                   if (!end.head) throw new Error("end HEAD evidence is unavailable");
                   const dirtyPaths = knownChangedPaths(turnRepo, end.head, end.tree, end.budget);
                   if (!dirtyPaths) throw new Error("end worktree diff evidence is unavailable");
-                  const checkBudget = () => { if (end.budget && performance.now() >= end.budget.deadline) throw new SnapshotBudgetExceeded(); };
+                  const checkBudget = () => { if (end.budget && budgetNow(end.budget) >= end.budget.deadline) throw new SnapshotBudgetExceeded(); };
                   const dirty = new Set(dirtyPaths), dirtyScope = new Set(dirtyPaths), incoming = new Set(paths);
                   for (const path of dirtyPaths) {
                     checkBudget();
@@ -3740,9 +3772,10 @@ export async function startDaemon(opts: DaemonOptions) {
         onActivity: item => activityRings[peer]?.append(item),
         isPrivateTurn: () => !!turns.get(peer)?.private || contextPii(peer),
         kind: adapter.kind, cmd: [launch.cmd, ...launch.args], permissionMode: permission === "read-only" ? "ask" : permission,
+        ...(externalIds.has(adapter.kind) ? { requireOwnedGroup: true, requireLoadSessionEcho: true, nativePolicy: adapter.permission.genericAcp ?? {} } : {}),
         ...(args.model ? { launchModel: args.model } : {}), ...(args.sessionId ? { resumeSessionId: args.sessionId } : {}),
         cwd: executionCwd, watchdogMs: config.watchdog_ms, onPermission,
-        autoApprove: title => !stopping && HUB_TOOL_TITLES.has(title),
+        autoApprove: title => !externalIds.has(adapter.kind) && !stopping && HUB_TOOL_TITLES.has(title),
         log: () => log(`${peer}: ACP runtime diagnostic: details withheld`),
         onUsageDiagnostic: (observation, sessionId) => {
           if (observation.source !== "usage_update" || observation.shape !== "context-used") return;
@@ -3755,7 +3788,7 @@ export async function startDaemon(opts: DaemonOptions) {
         mcpServers,
         preamble: sessionRoleContract(peer),
       } } });
-      if (!isAcpPeer(owner)) throw new Error("ACP factory did not return its native transport");
+      if (!isAcpPeer(owner) || owner.id !== peer) throw new Error("ACP factory did not return its bound native transport");
       recoveryTaskPreface(peer); await ensurePreface(peer);
       try { await owner.start(); await reconcileNativeStart(peer, owner); }
       catch (error) {
@@ -4398,12 +4431,12 @@ export async function startDaemon(opts: DaemonOptions) {
   function roleHolders(candidate: HubConfig): { planners: string[]; conductors: string[] } {
     // A valid transfer may briefly have two conductors while its leaves are planned. Validate the final map later.
     const policy = Object.fromEntries(Object.entries(candidate.roles).map(([peer, roles]) => [peer, roles.filter(role => role !== "conductor")]));
-    const settled = resolveSettledRoles(policy, candidate.planner, peer => rosterAllows(candidate.roster, peer, candidate.pi.enabled, declarations, adapterCatalog));
+    const settled = resolveSettledRoles(policy, candidate.planner, peer => projectRosterAllows(candidate.roster, peer, candidate.pi.enabled));
     return { planners: settled.planners, conductors: Object.keys(candidate.roles).filter(peer => candidate.roles[peer]!.includes("conductor")).sort() };
   }
   function prepareConfiguration(sources: ConfigSources, authority: SettingAuthority, scope?: string, confirmed: readonly string[] = []) {
-    const fileConfig = loadConfig(opts.cwd, sources.layers, sources.routing.retired ?? []);
-    validateEffectiveConfig(fileConfig);
+    const fileConfig = loadConfig(opts.cwd, sources.layers, sources.routing.retired ?? [], externalDefinitions);
+    validateEffectiveConfig(fileConfig, adapterCatalog);
     const candidate = structuredClone(desiredConfig), routing = structuredClone(desiredRouting);
     const accepted: string[] = [], rejected: { key: string; reason: string }[] = [], guarded: string[] = [];
     const previews: { key: string; before: string; after: string; effect?: string }[] = [];
@@ -4500,7 +4533,7 @@ export async function startDaemon(opts: DaemonOptions) {
     const running = structuredClone({ ...config, roles: policyRoles });
     for (const change of changes) if (change.applies !== "restart") putConfig(running, change.key, change.after);
     running.retired = fileConfig.retired;
-    validateEffectiveConfig(running);
+    validateEffectiveConfig(running, adapterCatalog);
     conductorPeer(running.roles);
     for (const peer of Object.keys(running.catalog_roles ?? {})) selectedRoles(peer, running.roles, { ...resolvedProfile.catalog_roles, ...catalogAssignments(running.catalog_roles) }, catalog);
     const problem = running.mlx.enabled === false ? mlxPinProblem(routing, sources.texts["routing.toml"] !== null) : undefined;
@@ -4530,7 +4563,7 @@ export async function startDaemon(opts: DaemonOptions) {
     const texts = configSourceTexts(opts.cwd), next = configSourceTexts(scratch);
     texts["config.json"] = next["config.json"];
     texts["config.local.json"] = next["config.local.json"];
-    const prepared = prepareConfiguration(parseConfigSources(texts, undefined, opts.cwd), authority, scope);
+    const prepared = prepareConfiguration(parseConfigSources(texts, undefined, opts.cwd, externalAdapters), authority, scope);
     const refusal = prepared.rejected.find(item => item.key === scope);
     if (refusal) throw new Error(`${refusal.key}: ${refusal.reason}`);
     return prepared.fileConfig;
@@ -4538,7 +4571,7 @@ export async function startDaemon(opts: DaemonOptions) {
   function routingWriteCheck(authority: SettingAuthority, overlay: import("./routing.ts").RoutingOverlay | undefined, scope?: string): void {
     const texts = configSourceTexts(opts.cwd);
     texts["routing.local.toml"] = overlay === undefined ? null : overlayToml(overlay);
-    const prepared = prepareConfiguration(parseConfigSources(texts, undefined, opts.cwd), authority, scope);
+    const prepared = prepareConfiguration(parseConfigSources(texts, undefined, opts.cwd, externalAdapters), authority, scope);
     const refusal = prepared.rejected.find(item => item.key === scope);
     if (refusal) throw new Error(`${refusal.key}: ${refusal.reason}`);
   }
@@ -4555,7 +4588,7 @@ export async function startDaemon(opts: DaemonOptions) {
       const texts = configSourceTexts(opts.cwd);
       fingerprint = configFingerprint(texts);
       if (confirm !== undefined && (typeof confirm !== "string" || authority !== "terminal" || scope || !reloadConfirmation || reloadConfirmation.token !== confirm || reloadConfirmation.fingerprint !== fingerprint || reloadConfirmation.revision !== configRevision)) return { ok: false, error: "configuration confirmation is stale or changed; run ahub settings reload again" };
-      const sources = parseConfigSources(texts, undefined, opts.cwd);
+      const sources = parseConfigSources(texts, undefined, opts.cwd, externalAdapters);
       const prepared = prepareConfiguration(sources, authority, scope, confirm === undefined ? [] : reloadConfirmation!.keys);
       if (confirm !== undefined && prepared.rejected.some(item => reloadConfirmation!.keys.includes(item.key))) return { ok: false, error: "configuration trust changed; run ahub settings reload again" };
       if (scope && prepared.rejected.some(item => item.key === scope)) return { ok: false, error: prepared.rejected.find(item => item.key === scope)!.reason };
@@ -4622,7 +4655,7 @@ export async function startDaemon(opts: DaemonOptions) {
     const stamp = CONFIG_FILES.map((name) => { try { const s = statSync(join(opts.cwd, ".agenthub", name)); return `${s.mtimeMs}:${s.size}`; } catch { return "-"; } }).join("|");
     if (storedConfigCache?.stamp !== stamp) {
       let loaded: HubConfig | undefined;
-      try { loaded = loadConfig(opts.cwd); } catch { /* the rows say that the files do not load */ }
+      try { loaded = loadConfig(opts.cwd, undefined, undefined, externalDefinitions); } catch { /* the rows say that the files do not load */ }
       storedConfigCache = { stamp, config: loaded };
     }
     return storedConfigCache.config;
@@ -4645,7 +4678,7 @@ export async function startDaemon(opts: DaemonOptions) {
     const rows = settingRows({
       instances: declarations, adapterCatalog, cwd: opts.cwd, routing: activeRouting(), ...(routingProblem ? { routingProblem } : {}), ...(stored?.ignored ? { ignored: stored.ignored } : {}),
       running: (path) => path[0] === "roster" ? onRoster(path[1]!) : path[0] === "tasks" && path[1] === "wip_limits" ? tasks.wipLimit(path[2]!) : valueAt(config, path),
-      next: stored ? (path) => path[0] === "roster" ? rosterAllows(stored.roster, path[1]!, stored.pi.enabled, declarations, adapterCatalog) : path[0] === "tasks" && path[1] === "wip_limits" ? (Object.hasOwn(stored.tasks.wip_limits ?? {}, path[2]!) ? stored.tasks.wip_limits![path[2]!] : 1) : valueAt(stored, path) : undefined,
+      next: stored ? (path) => path[0] === "roster" ? projectRosterAllows(stored.roster, path[1]!, stored.pi.enabled) : path[0] === "tasks" && path[1] === "wip_limits" ? (Object.hasOwn(stored.tasks.wip_limits ?? {}, path[2]!) ? stored.tasks.wip_limits![path[2]!] : 1) : valueAt(stored, path) : undefined,
       roles: roleState,
       mode: (peer) => {
         const owner = bus.peers.get(peer), attached = !!owner && owner.state !== "offline";
@@ -4698,10 +4731,12 @@ export async function startDaemon(opts: DaemonOptions) {
     if (rosterChanging) return { ok: false, error: `roster change for ${rosterChanging} is in progress` };
     const peer = def.path[1]!;
     let saved = false;
+    // #225: a stale key has no peer behind it. What changes is that the key is deleted, not whether the peer is on the roster.
+    const stale = staleRosterKey(def.key) !== undefined, previousKey = config.roster[peer], sharedCopy = stale && sharedValue(opts.cwd, def) !== undefined;
     const terminalNotice = retainedTerminalNotice(peer);
     let handoff: Awaited<ReturnType<Tasks["reassignForRoster"]>> = [];
     try {
-      const next = rosterCandidate(def, value, undo), before = onRoster(peer), after = rosterAllows(next, peer, config.pi.enabled, declarations, adapterCatalog);
+      const next = rosterCandidate(def, value, undo), before = onRoster(peer), after = projectRosterAllows(next, peer, config.pi.enabled);
       if (!after) {
         const refusal = rosterRemovalRefusal(peer, now);
         if (refusal) return { ok: false, error: refusal };
@@ -4715,7 +4750,7 @@ export async function startDaemon(opts: DaemonOptions) {
       config.roster = next;
       settlePlanner(); // #455: an automatic planner follows the roster
       saved = true;
-      recordSetting(def.key, before, after, source, undo, reason);
+      recordSetting(def.key, stale ? previousKey ?? null : before, stale ? null : after, source, undo, reason);
       bus.rosterChanged(peer); // fence the queue before stopping or detaching the adapter
       if (!after) {
         for (const pending of permissions.values()) if (pending.peer === peer) pending.done(undefined);
@@ -4740,6 +4775,7 @@ export async function startDaemon(opts: DaemonOptions) {
       const reloaded = await reloadConfig(authority, `roster.${peer}`);
       if (reloaded.ok !== true) return { ...reloaded, saved: true };
       writeStatus();
+      if (stale) return { ok: true, text: [`${peer}: stale roster key removed from .agenthub/config.local.json`, ...(sharedCopy ? [`still set in .agenthub/config.json: that copy decides nothing, and stays until you edit it there`] : [])].join("\n") };
       const stayed = !after ? board.list().filter(task => !isClosedTaskState(task.state) && (task.owner === peer || task.reviewer === peer)) : [];
       return { ok: true, text: [`${peer}: ${after ? "on" : "off"} roster (in force now)`, ...(!after && terminalNotice ? [terminalNotice] : []), ...(after && definitionOf(peer)?.cli.rosterReturnNotice ? [definitionOf(peer)!.cli.rosterReturnNotice!(codexResumeCommand(peer))] : []), ...(!after ? handoff.map(move => sanitize(`task ${move.title}: ${move.role} assignment moved to ${move.to}`)) : []), ...stayed.map(task => sanitize(`task ${tasks.publicTitle(task)} stays with ${peer} as ${[task.owner === peer ? "owner" : "", task.reviewer === peer ? "reviewer" : ""].filter(Boolean).join(" and ")} (${task.state})`)), ...(!after && !handoff.length && !stayed.length ? ["No open tasks to hand over."] : [])].join("\n"), ...(!after ? { handoff } : {}) };
     } catch (error) {
@@ -4752,6 +4788,12 @@ export async function startDaemon(opts: DaemonOptions) {
     const def = settingDef(key);
     if (typeof def === "string") return { error: def };
     const routing = activeRouting();
+    if (staleRosterKey(def.key) && raw !== null) return { error: `${def.key} names an instance that is no longer declared: it can only be removed (ahub roster remove ${def.path[1]})` };
+    // A removal only edits the machine-local file. A key that lives only in the shared one would be "removed" and come back on reload.
+    if (staleRosterKey(def.key) && !storedLocally(opts.cwd, def)) return { error: `${def.key} is not in .agenthub/config.local.json, so removing it here changes nothing: edit .agenthub/config.json` };
+    // Removing the local copy would let a different shared value show through, which the reload refuses as setting a stale key, after the write.
+    const shared = staleRosterKey(def.key) ? sharedValue(opts.cwd, def) : undefined;
+    if (shared !== undefined && shared !== config.roster[def.path[1]!]) return { error: `${def.key} is also set to ${String(shared)} in .agenthub/config.json: edit .agenthub/config.json first; nothing was changed` };
     try { return { def, value: checkSettingValue(def, raw, def.type === "roles" ? compatibleRoles(def.path[1]!) : Object.keys(routing.hub_routes ?? {})) }; }
     catch (error) { return { error: (error as Error).message }; }
   }
@@ -4848,9 +4890,12 @@ export async function startDaemon(opts: DaemonOptions) {
     const input = settingInput(key, raw);
     if ("error" in input) return { ok: false, error: input.error };
     const { def, value } = input;
+    if (def.group === "Roster" && staleRosterKey(def.key)) {
+      return { ok: true, lines: [`${def.path[1]}: no longer declared; its roster key decides nothing today.`, `Removing it deletes roster.${def.path[1]} from .agenthub/config.local.json and nothing else.`, ...(sharedValue(opts.cwd, def) !== undefined ? [`.agenthub/config.json also holds roster.${def.path[1]}: that copy stays until you edit it there.`] : [])] };
+    }
     if (def.group === "Roster") {
       try {
-        const peer = def.path[1]!, next = rosterCandidate(def, value), on = rosterAllows(next, peer, config.pi.enabled, declarations, adapterCatalog);
+        const peer = def.path[1]!, next = rosterCandidate(def, value), on = projectRosterAllows(next, peer, config.pi.enabled);
         return { ok: true, lines: [`${peer}: ${onRoster(peer) ? "on" : "off"} -> ${on ? "on" : "off"} roster`, ...(on ? ["Admission, starts and new work become available; any existing pause or held delivery remains."] : [`${bus.queued(peer)} queued messages are retained until the peer returns.`, "Owned runtimes stop; native terminal sessions detach. Open tasks are offered to another eligible peer.", `For a busy peer, use ahub roster remove ${peer} --now explicitly; this stops its owned runtime or detaches its native session during the active turn.`, ...(retainedTerminalNotice(peer) ? [retainedTerminalNotice(peer)!] : []), ...tasks.rosterPreview(peer).map(move => sanitize(`task ${move.title}: ${move.to ? `${move.role} offered to ${move.to} if removed now` : `${move.role} stays with ${peer}; no eligible replacement`}`)), ...(rosterRemovalRefusal(peer, false) ? [rosterRemovalRefusal(peer, false)!] : [])])], ...(on ? {} : { confirm: peer }) };
       } catch (error) { return { ok: false, error: sanitize((error as Error).message) }; }
     }
@@ -5009,6 +5054,7 @@ export async function startDaemon(opts: DaemonOptions) {
     const incompatibleRecoveryTarget = () => {
       const cancelled = incompatibleCancellationTarget();
       if (cancelled) return cancelled;
+      if (externalIds.size && (!Array.isArray(msg.targetFeatures) || !msg.targetFeatures.includes("external_adapter_modules"))) return "target lacks external_adapter_modules; verified external definitions cannot be preserved by that daemon";
       if (configuredIds.length && (!Array.isArray(msg.targetFeatures) || !msg.targetFeatures.includes("configured_acp"))) return "target lacks configured_acp; project adapter definitions cannot be preserved by that daemon";
       if (extraIds.length && (!Array.isArray(msg.targetFeatures) || !msg.targetFeatures.includes("peer_instances"))) return "target lacks peer_instances; declared instance identities cannot be restored by that daemon";
       if (board.releases().some(release => release.train && ["active", "frozen"].includes(release.state)) && (!Array.isArray(msg.targetFeatures) || !msg.targetFeatures.includes("release_trains"))) return "target lacks release_trains; active or frozen train safeguards cannot be preserved";
@@ -5171,8 +5217,11 @@ export async function startDaemon(opts: DaemonOptions) {
       if (nativeUnattended(peer)) return { ok: false, error: "Codex started --unattended already skips prompts; run ahub permission codex ask after it stops to clear the hub choice, then restart without --unattended" };
     }
     const from = permissionMode(peer);
+    const runtime: PeerAdapter = owner;
+    const nativeMode = runtime.permissionModeState;
+    if (nativeMode === "unknown" || nativeMode === "unmanaged") return { ok: false, error: `${peer} permission mode ${nativeMode}; inspect its native policy before changing modes` };
     try {
-      if (isAcpPeer(owner) || isCodexPeer(owner)) await owner.setPermissionMode(mode);
+      if (runtime.setPermissionMode) await runtime.setPermissionMode(mode);
     } catch (error) { return { ok: false, error: (error as Error).message }; }
     if (bus.peers.get(peer) !== owner || bus.stateOf(peer) === "offline") return { ok: false, error: `${peer} session changed; inspect status and retry` };
     permissionModes.set(peer, mode);
@@ -5710,6 +5759,13 @@ export async function startDaemon(opts: DaemonOptions) {
         if (msg.op === "export") {
           try { return void reply({ ok: true, export: tasks.workflowExport(msg.id) }); } catch { return void reply({ ok: false, error: "workflow export unavailable" }); }
         }
+        if (msg.op === "accept-departure") {
+          void tasks.acceptPlanDeparture(USER, msg.id, msg.head, msg.reason).then(
+            () => reply({ ok: true }),
+            () => reply({ ok: false, error: "plan departure not accepted: task changed, current complete file evidence unavailable, or arguments invalid" }),
+          );
+          return;
+        }
         if (msg.op === "accept") {
           // #481 S1: the person's spec acceptance, bound to the issue's body edit time; no body is read.
           if (!Number.isSafeInteger(msg.id) || msg.id <= 0 || !Number.isSafeInteger(msg.issue) || msg.issue <= 0 || (msg.repo !== undefined && typeof msg.repo !== "string")) return void reply({ ok: false, error: "usage: ahub sdlc accept <task> --issue <n> [--repo owner/repository]" });

package/src/hub/facts.ts

@@ -1,7 +1,7 @@
 import { repoGitArgs, repoGitEnv, type Repo } from "./snapshots.ts";
 import { isHubWritePath } from "./permission-mode.ts";
 import { createHash, randomUUID } from "node:crypto";
-import { closeSync, constants, fstatSync, mkdirSync, openSync, readSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { closeSync, constants, fstatSync, mkdirSync, openSync, readSync, rmSync, statSync, writeFileSync, type Stats } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { sanitize, type PeerId } from "./envelope.ts";
 import { isDenied } from "../local/deny.ts";
@@ -24,6 +24,22 @@ import { realPath } from "./project.ts";
 const MAX_BYTES = 256 * 1024;
 /** Larger files that are not read are hashed for the HEAD comparison while all of them in one comparison total this much or less; beyond it, none is compared. */
 const HASHED_BYTES = 64 * 1024 * 1024;
+/**
+ * A large file whose last change (ctime) is this recent may still be rewritten with the same stat: Linux before 6.13
+ * stamps files from a coarse clock, so a same-size rewrite within one tick keeps size, mtime, ctime and inode (#428).
+ * Such a file is named by its bytes, as git treats a racily clean entry: at most RACY_HASH_MAX_BYTES each, hashed once
+ * per version in a public entry point, RACY_BURST_BYTES in all per store (Facts instance) per event-loop turn (the hooks
+ * run on the daemon's loop). The HEAD comparison keeps its own bound (HASHED_BYTES) and is not limited by these.
+ * ponytail: ceilings, each falling back to the stat-only stamp (no claim either way): a racy file over the per-file cap,
+ * or past the turn's budget, misses a same-size rewrite within one timestamp tick; a racy file first seen past the
+ * budget (kept stat-only) reads as changed once when a later turn hashes it with the same bytes; a file written continuously never settles and is hashed at every look, within that budget; FAT's 2 s mtime
+ * is the widest covered; a settled file made racy with the same bytes (chmod, `cp -p`, touch) reads as changed once; a
+ * version first seen racy costs an open and a stat at every later look (largeBlob's cache answers). A per-file history
+ * of racy versions if any of these matters.
+ */
+const RACY_MS = 2000;
+const RACY_HASH_MAX_BYTES = 4 * 1024 * 1024;
+const RACY_BURST_BYTES = 16 * 1024 * 1024;
 /** Changed lines shown in one fact, all files together; the rest is counted and the files named. */
 export const MAX_LINES = 60;
 /** What Claude Code's Read returns by default: the first 2000 lines, each cut at 2000 characters. */
@@ -145,6 +161,10 @@ export class Facts {
   private readonly seenDropped = new Map<PeerId, Set<string>>();
   /** Git blob ids of large files, by path, with the stat they were taken at. */
   private readonly largeBlobs = new Map<string, { stamp: string; blob: string }>();
+  /** Blob ids of racy large files hashed in the current boundary, by path and stat (#428). */
+  private racyMemo = new Map<string, string>();
+  /** Bytes of racy large files left to hash in this event-loop turn. */
+  private racyLeft?: { bytes: number };
   /** Directories each peer acknowledged being told were cut: once per session, not at every boundary. */
   private readonly cutTold = new Map<PeerId, Set<string>>();
   /**
@@ -217,7 +237,7 @@ export class Facts {
    * ponytail: a directory swapped between the containment check and the open is followed once; an fd-relative walk
    * (openat per component) closes that if it matters.
    */
-  private load(file: string): Omit<Version, "seq"> {
+  private load(file: string, statOnly = false): Omit<Version, "seq"> {
     if (this.rel(join(this.root, file)) !== file) return { hash: "missing" };
     const projected = this.o.projection?.(join(this.root, file));
     if (projected) return { hash: projected.rawHash, blob: projected.rawBlob, text: projected.text, projected: true };
@@ -226,7 +246,10 @@ export class Facts {
       fd = openSync(join(this.root, file), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
       const st = fstatSync(fd);
       if (!st.isFile()) return { hash: "missing" }; // a directory, a device or a fifo: never read
-      if (st.size > MAX_BYTES) return { hash: `large:${st.size}:${st.mtimeMs}` };
+      if (st.size > MAX_BYTES) {
+        const blob = statOnly ? undefined : this.racyBlob(file, fd, st);
+        return blob ? { hash: `large:${st.size}:${st.mtimeMs}:${blob}`, blob } : { hash: `large:${st.size}:${st.mtimeMs}` };
+      }
       const buf = Buffer.alloc(st.size);
       let got = 0;
       while (got < buf.length) {
@@ -317,13 +340,17 @@ export class Facts {
     const seen = files.filter((f) => head.has(f)).map((f) => [f, version(f)] as const);
     const large = seen.reduce((n, [, v]) => n + (v?.hash.startsWith("large:") ? Number(v.hash.split(":")[1]) : 0), 0);
     return new Set(seen.filter(([f, v]) => {
-      const blob = v?.blob ?? (v?.hash.startsWith("large:") && large <= HASHED_BYTES ? this.largeBlob(f, v.hash) : undefined);
+      const blob = !v?.hash.startsWith("large:") ? v?.blob : large <= HASHED_BYTES ? v.blob ?? this.largeBlob(f, v.hash, true) : undefined;
       return blob !== undefined && blob === head.get(f);
     }).map(([f]) => f));
   }
 
   /** Git's blob id of a file too large to load, streamed; undefined for anything that is not a small enough regular file. */
-  private largeBlob(file: string, observed: string): string | undefined {
+  /**
+   * `head`: for the HEAD comparison, which bounds its own hashing (HASHED_BYTES): a racy file is streamed whatever the
+   * racy cap and the turn's budget, uncached. Otherwise a racy file goes through racyBlob's limits.
+   */
+  private largeBlob(file: string, observed: string, head = false): string | undefined {
     if (this.rel(join(this.root, file)) !== file) return undefined;
     let fd: number | undefined;
     try {
@@ -333,13 +360,10 @@ export class Facts {
       // A file that stays stat-dirty but equal to HEAD is looked at again at every boundary: hashed once per version.
       const stamp = `${st.ino}:${st.size}:${st.mtimeMs}:${st.ctimeMs}`, known = this.largeBlobs.get(file);
       if (known?.stamp === stamp) return known.blob;
-      const h = createHash("sha1").update(`blob ${st.size}\0`);
-      const buf = Buffer.alloc(1024 * 1024);
-      let got = 0;
-      for (let n = 0; got < st.size && (n = readSync(fd, buf, 0, buf.length, got)) > 0; got += n) h.update(buf.subarray(0, n));
-      if (got !== st.size) return undefined; // changed while read: no claim
-      const blob = h.digest("hex");
-      this.largeBlobs.set(file, { stamp, blob });
+      // A racy stamp may name other bytes later: never cached.
+      if (Date.now() - st.ctimeMs < RACY_MS) return head ? this.racyMemo.get(racyKey(file, st)) ?? streamBlob(fd, st.size) : this.racyBlob(file, fd, st);
+      const blob = streamBlob(fd, st.size);
+      if (blob) this.largeBlobs.set(file, { stamp, blob });
       return blob;
     } catch {
       return undefined;
@@ -348,6 +372,22 @@ export class Facts {
     }
   }
 
+  /** A racy large file's blob id (#428), or undefined when it is settled, over the per-file cap or past the turn's budget. */
+  private racyBlob(file: string, fd: number, st: Stats): string | undefined {
+    if (Date.now() - st.ctimeMs >= RACY_MS || st.size > RACY_HASH_MAX_BYTES) return undefined;
+    const key = racyKey(file, st), known = this.racyMemo.get(key);
+    if (known) return known;
+    if (!this.racyLeft) {
+      const turn = this.racyLeft = { bytes: RACY_BURST_BYTES };
+      setImmediate(() => { if (this.racyLeft === turn) this.racyLeft = undefined; });
+    }
+    if (st.size > this.racyLeft.bytes) return undefined;
+    this.racyLeft.bytes -= st.size;
+    const blob = streamBlob(fd, st.size);
+    if (blob) this.racyMemo.set(key, blob);
+    return blob;
+  }
+
   /** `file` is covered again: an offer still unread that named it as dropped must not spend the notice of a later drop. */
   private coveredAgain(peer: PeerId, notice: "untracked" | "unfollowed", file: string): void {
     for (const o of this.offers.get(peer) ?? []) if (o[notice]?.includes(file)) o[notice] = o[notice]!.filter((f) => f !== file);
@@ -357,6 +397,7 @@ export class Facts {
   private boundary(): void {
     this.expanded = new Map();
     this.expandedCut = new Set();
+    this.racyMemo = new Map(); // not per turn: a rewrite between two entry points of one turn is another version
   }
 
   /** `peer` worked on `file`; `seen` is the file as it was when it did, the baseline if it has no view of it yet. */
@@ -463,6 +504,12 @@ export class Facts {
     const now = this.load(file);
     const was = this.latest.get(file);
     if (was && was.hash === now.hash) return was;
+    // Seen while racy (named by its bytes), now with the same stat but no blob (settled, or past the turn's budget): the
+    // same version if the bytes are, or when they cannot be hashed now (no claim).
+    if (was?.blob && was.hash === `${now.hash}:${was.blob}`) {
+      const blob = this.largeBlob(file, now.hash);
+      if (blob === undefined || blob === was.blob) return was;
+    }
     const version = { ...now, seq: ++this.seq };
     this.latest.set(file, version);
     if (was) {
@@ -720,7 +767,9 @@ export class Facts {
     // does, nor what they wrote before or after (a member settling keeps its files in the set).
     const written = windows.flatMap((w) => [...(this.writes.get(w.peer) ?? [])].filter(([, times]) => times.some((t) => t >= w.since && (w.until === undefined || t <= w.until))).map(([file]) => file));
     const files = [...new Set([...this.expand(paths.flatMap((p) => { const r = this.rel(p); return r ? [r] : []; }), true), ...written])].sort();
-    for (const file of files) h.update(file).update("\0").update(this.load(file).hash).update("\0");
+    // ponytail: a large file counts by its stat, racy or not, so the target does not move when it settles; a same-size
+    // rewrite within one timestamp tick does not move it either (observe() sees that one).
+    for (const file of files) h.update(file).update("\0").update(this.load(file, true).hash).update("\0");
     return h.digest("hex");
   }
 
@@ -871,3 +920,17 @@ export function codexEffect(before: string | undefined, now: { hash: string; tex
   const observed = changedLines(diff(before, now.text));
   return reported.length > 0 && reported.length === observed.length && reported.every((l, i) => l === observed[i]);
 }
+
+/** Git's blob id of the `size` bytes `fd` reads, streamed; undefined when fewer were read (changed while read). */
+function streamBlob(fd: number, size: number): string | undefined {
+  const h = createHash("sha1").update(`blob ${size}\0`);
+  const buf = Buffer.alloc(1024 * 1024);
+  let got = 0;
+  for (let n = 0; got < size && (n = readSync(fd, buf, 0, buf.length, got)) > 0; got += n) h.update(buf.subarray(0, n));
+  return got === size ? h.digest("hex") : undefined;
+}
+
+/** A racy large file's version within one boundary: its path and every stat field. */
+function racyKey(file: string, st: Stats): string {
+  return `${file}\0${st.ino}:${st.size}:${st.mtimeMs}:${st.ctimeMs}`;
+}