instar 1.3.366 → 1.3.368

package/dist/core/PendingPullLedger.js

@@ -0,0 +1,239 @@
+/**
+ * PendingPullLedger — P2.2 of multi-machine coherence: the durable record of
+ * working-set pulls that could not complete because the producer was
+ * offline / unreachable / revoked / mid-run. The EXO case, solved: the
+ * request survives restarts and re-fires the moment the peer returns.
+ *
+ * Spec: docs/specs/WORKING-SET-HANDOFF-SPEC.md §3.4.
+ *
+ * SINGLE-WRITER DISCIPLINE (the topic-flood-#3 lesson, applied at birth):
+ * SIX mutators can overlap on one tick (onAccepted scheduler, reappearance
+ * re-arm, run-stopped re-arm, attempt/breaker update, reflex route, TTL
+ * sweep). ALL mutations route through ONE serialized `mutate(fn)` funnel —
+ * an in-process async queue, so read-modify-write never interleaves — with
+ * temp-file + atomic-rename persistence.
+ *
+ * PARSE-FAILURE POSTURE (the flood's second root): a corrupt/unparseable
+ * ledger is NEVER read as "no pending pulls" — the file is quarantined
+ * aside (`.corrupt-<ts>`), ONE notice fires through the injected
+ * `onCorrupt` seam ("pending-pull ledger unreadable — stranded-recovery
+ * records may be lost"), and a fresh ledger starts.
+ *
+ * Store path: `state/coherence-journal/pending-pulls.json` — registered in
+ * the State-Coherence Registry (machine-local; the records describe THIS
+ * machine's outstanding fetches).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+export const PENDING_PULLS_FILENAME = 'pending-pulls.json';
+export const DEFAULT_PENDING_PULL_TTL_DAYS = 7;
+/** Per-record attempt cap — the (peer,topic,epoch) breaker (§3.4). */
+export const DEFAULT_ATTEMPT_CAP = 6;
+function recordKey(r) {
+    return `${r.topic}:${r.epoch}:${r.nominee}`;
+}
+export class PendingPullLedger {
+    file;
+    ttlMs;
+    attemptCap;
+    now;
+    onCorrupt;
+    onExpired;
+    logger;
+    /** The serialized mutate() funnel — read-modify-write never interleaves. */
+    queue = Promise.resolve();
+    /** In-memory truth between mutations (loaded once, kept current). */
+    records = null;
+    corruptNotified = false;
+    constructor(config) {
+        this.file = path.join(config.stateDir, 'state', 'coherence-journal', PENDING_PULLS_FILENAME);
+        this.ttlMs = (config.ttlDays ?? DEFAULT_PENDING_PULL_TTL_DAYS) * 24 * 60 * 60 * 1000;
+        this.attemptCap = config.attemptCap ?? DEFAULT_ATTEMPT_CAP;
+        this.now = config.now ?? (() => new Date());
+        this.onCorrupt = config.onCorrupt;
+        this.onExpired = config.onExpired;
+        this.logger = config.logger ?? (() => { });
+    }
+    // ---- public API (every mutation rides the funnel) ------------------------
+    /**
+     * File (or refresh) a pending pull. Idempotent on (topic, epoch, nominee):
+     * an existing record keeps its createdAt/attempts; only `reason` refreshes.
+     */
+    async file_(rec) {
+        await this.mutate((records) => {
+            const key = recordKey(rec);
+            const existing = records.find((r) => recordKey(r) === key);
+            if (existing) {
+                existing.reason = rec.reason;
+                return records;
+            }
+            records.push({
+                ...rec,
+                createdAt: this.now().toISOString(),
+                attempts: 0,
+                lastAttemptAt: null,
+            });
+            return records;
+        });
+    }
+    /**
+     * Record a GENUINE failed attempt (offline / unreachable / refused /
+     * verify-failed). `busy` responses MUST NOT come through here — busy is
+     * retry-without-penalty (§3.2); a throttled drain must never exhaust the
+     * very records it exists to recover.
+     */
+    async recordAttempt(topic, epoch, nominee) {
+        await this.mutate((records) => {
+            const r = records.find((x) => x.topic === topic && x.epoch === epoch && x.nominee === nominee);
+            if (r) {
+                r.attempts += 1;
+                r.lastAttemptAt = this.now().toISOString();
+            }
+            return records;
+        });
+    }
+    /** A completed pull clears its record. */
+    async clear(topic, epoch, nominee) {
+        await this.mutate((records) => records.filter((r) => !(r.topic === topic && r.epoch === epoch && r.nominee === nominee)));
+    }
+    /**
+     * Supersession (§3.4): a newer epoch for the topic clears ALL records for
+     * that topic with `epoch < newEpoch`, across all nominees — a partial clear
+     * must never strand a sibling record.
+     */
+    async supersede(topic, newEpoch) {
+        await this.mutate((records) => records.filter((r) => !(r.topic === topic && r.epoch < newEpoch)));
+    }
+    /**
+     * TTL sweep: expire records older than ttlDays — each surfaced ONCE via
+     * onExpired ("never recovered"), then removed. Run on a slow cadence by the
+     * caller (it is one of the six mutators, so it rides the funnel too).
+     * Returns the expired records.
+     */
+    async sweepExpired() {
+        const expired = [];
+        await this.mutate((records) => {
+            const nowMs = this.now().getTime();
+            const kept = [];
+            for (const r of records) {
+                const age = nowMs - new Date(r.createdAt).getTime();
+                if (age > this.ttlMs)
+                    expired.push(r);
+                else
+                    kept.push(r);
+            }
+            for (const r of expired) {
+                try {
+                    this.onExpired?.(r);
+                }
+                catch { /* @silent-fallback-ok: an expiry-notice consumer failure must never block the sweep itself (WORKING-SET-HANDOFF-SPEC §3.4) */
+                }
+            }
+            return kept;
+        });
+        return expired;
+    }
+    /**
+     * The records eligible to re-fire for a returning peer — the staggered
+     * drain reads this (most-recent-epoch-first; the drain itself enforces
+     * rearmConcurrency). Records at/over the attempt cap are excluded (the
+     * breaker; a NEW epoch files a NEW record, so an old exhausted breaker
+     * never suppresses a fresh, warranted pull).
+     */
+    async pendingForPeer(nominee) {
+        const records = await this.read();
+        return records
+            .filter((r) => r.nominee === nominee && r.attempts < this.attemptCap)
+            .sort((a, b) => b.epoch - a.epoch);
+    }
+    /** All records for a topic (the run-stopped re-arm + reflex route read this). */
+    async pendingForTopic(topic) {
+        const records = await this.read();
+        return records.filter((r) => r.topic === topic && r.attempts < this.attemptCap);
+    }
+    /** Every record, including breaker-exhausted ones (observability). */
+    async all() {
+        return [...(await this.read())];
+    }
+    // ---- the funnel -----------------------------------------------------------
+    /**
+     * Serialize a read-modify-write. The fn receives the current records array
+     * (mutable) and returns the next one; persistence is temp-file + atomic
+     * rename. Errors persist nothing and propagate to THIS caller only — the
+     * queue itself never wedges.
+     */
+    mutate(fn) {
+        const run = this.queue.then(async () => {
+            const before = await this.readUnqueued();
+            const next = fn(before);
+            this.persist(next);
+            this.records = next;
+            return next;
+        });
+        // The queue continues even when one mutation throws (error isolated to caller).
+        this.queue = run.catch(() => { });
+        return run;
+    }
+    async read() {
+        // Reads ride the funnel too — a read mid-mutation would see torn state.
+        const run = this.queue.then(() => this.readUnqueued());
+        this.queue = run.catch(() => { });
+        return run;
+    }
+    /** Load from memory or disk. Corrupt disk → quarantine + notice + fresh. */
+    readUnqueued() {
+        if (this.records)
+            return this.records;
+        let raw;
+        try {
+            raw = fs.readFileSync(this.file, 'utf-8');
+        }
+        catch { /* @silent-fallback-ok: ledger absent = genuinely empty (first boot) — distinct from corrupt, which quarantines below (WORKING-SET-HANDOFF-SPEC §3.4) */
+            this.records = [];
+            return this.records;
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            if (!parsed || parsed.version !== 1 || !Array.isArray(parsed.records)) {
+                throw new Error('shape mismatch');
+            }
+            this.records = parsed.records.filter((r) => typeof r?.topic === 'number' &&
+                typeof r?.epoch === 'number' &&
+                typeof r?.nominee === 'string' &&
+                typeof r?.attempts === 'number');
+            return this.records;
+        }
+        catch {
+            // NEVER read corrupt as empty-silently: quarantine + one notice + fresh.
+            this.quarantineCorrupt();
+            this.records = [];
+            return this.records;
+        }
+    }
+    quarantineCorrupt() {
+        const quarantined = `${this.file}.corrupt-${this.now().getTime()}`;
+        try {
+            fs.renameSync(this.file, quarantined);
+        }
+        catch { /* @silent-fallback-ok: quarantine rename can lose a race with another process; the notice below still fires once (WORKING-SET-HANDOFF-SPEC §3.4) */
+        }
+        this.logger(`pending-pull ledger unreadable — quarantined to ${path.basename(quarantined)}`);
+        if (!this.corruptNotified) {
+            this.corruptNotified = true;
+            try {
+                this.onCorrupt?.(quarantined);
+            }
+            catch { /* @silent-fallback-ok: a corrupt-notice consumer failure must never block ledger recovery (WORKING-SET-HANDOFF-SPEC §3.4) */
+            }
+        }
+    }
+    persist(records) {
+        const dir = path.dirname(this.file);
+        fs.mkdirSync(dir, { recursive: true });
+        const tmp = `${this.file}.tmp-${process.pid}`;
+        const body = { version: 1, records };
+        fs.writeFileSync(tmp, JSON.stringify(body, null, 2));
+        fs.renameSync(tmp, this.file);
+    }
+}
+//# sourceMappingURL=PendingPullLedger.js.map

package/dist/core/PendingPullLedger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PendingPullLedger.js","sourceRoot":"","sources":["../../src/core/PendingPullLedger.ts"],"names":[],"mappings":"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"}

package/dist/core/PostUpdateMigrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PostUpdateMigrator.d.ts","sourceRoot":"","sources":["../../src/core/PostUpdateMigrator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"PostUpdateMigrator.d.ts","sourceRoot":"","sources":["../../src/core/PostUpdateMigrator.ts"],"names":[],"mappings":"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"}

package/dist/core/PostUpdateMigrator.js

@@ -2718,6 +2718,20 @@ Rule: I do not state that work landed inside another agent's state unless I have
             patched = true;
             result.upgraded.push('CLAUDE.md: added Cross-Agent Communication Discipline (anti-confabulation) section');
         }
+        // Working-Set Handoff fetch reflex (WORKING-SET-HANDOFF-SPEC §3.7) —
+        // existing agents need the proactive trigger ("user references files not on
+        // this machine → POST /coherence/fetch-working-set"). Content-sniffed on a
+        // distinctive marker; harmless on agents where the layer is dark (503).
+        if (!content.includes('Working-Set Handoff (fetch a topic')) {
+            const workingSetSection = `
+**Working-Set Handoff (fetch a topic's files from the machine that made them)** — When a conversation moves between my machines, its working files follow automatically (the journal nominates which machines produced artifacts; the receiving machine pulls them in verified 1MB slices; nothing is ever overwritten — a divergent local file keeps its place and the incoming copy lands alongside it). If the producer machine is offline, the request is written down durably and fires the moment it returns.
+- The fetch reflex: \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/coherence/fetch-working-set -H 'Content-Type: application/json' -d '{"topic":N}'\` → \`{ scheduled, reports: [{ nominee, report }] }\` (503 = the working-set layer is dark on this agent; 429 = rate-limited, a pull is already running or just ran).
+- **When to use** (PROACTIVE — this is the trigger): the user references files/work/analysis from this topic that are NOT on this machine ("where's the overnight analysis?", "you did this on the other machine") → fire the reflex, then answer from the landed files. Files flagged as containing credentials, still-being-written, or oversized are refused with named reasons in the report — explain honestly rather than retrying.
+`;
+            content += '\n' + workingSetSection;
+            patched = true;
+            result.upgraded.push('CLAUDE.md: added Working-Set Handoff fetch-reflex section');
+        }
         // MTP Protocol — the two EXO 3.0 tests (refusal + endorsement) on ORG-INTENT.
         // Existing agents need to know the /intent/org/test-action endpoint + the
         // three-layer protocol exist. Content-sniffed on a distinctive marker.
@@ -4546,6 +4560,12 @@ Create worktrees for collaborator repos with \`instar worktree create <branch>\`
             '**Coordination Mandate**',
             '**ReviewExchange (autonomous code review)**',
             '**Cutover Readiness**',
+            // Working-Set Handoff (WORKING-SET-HANDOFF-SPEC §3.7): the fetch reflex
+            // (POST /coherence/fetch-working-set). A Codex/Gemini agent that never
+            // learns it will tell the user the files "aren't on this machine"
+            // instead of fetching them — the EXO failure surviving on shadow
+            // frameworks only. Mirrored like every agent-facing capability.
+            "**Working-Set Handoff (fetch a topic's files from the machine that made them)**",
             // Session Boot Self-Knowledge (spec session-boot-self-knowledge): vault
             // secret NAMES + operational facts at boot. A Codex/Gemini agent that
             // never learns the facts writer + secret-get retrieval will re-ask the