instar 1.3.550 → 1.3.552

package/dist/core/RemoteAckStore.d.ts

@@ -0,0 +1,71 @@
+/**
+ * RemoteAckStore — durable queue for operator-bound attention acks that target
+ * an attention item OWNED BY A DIFFERENT MACHINE (WS4.1 follow-up, CMT-1416).
+ *
+ * The problem this closes: when an operator acknowledges/resolves a pooled
+ * attention item whose owner is briefly offline, the ack PATCH is lost — the
+ * operator's intent evaporates and the item reappears OPEN on the owner's
+ * return. This store persists the ack INTENT (with the authenticated operator
+ * principal that performed it) so it survives the owner being dark; a drain
+ * tick + a boot sweep re-deliver it when the owner comes back.
+ *
+ * Design constraints (mirrors RemoteCloseAudit / PendingInboundStore):
+ *   - Append-then-compact JSONL under logs/ — no DB dependency.
+ *   - Each pending ack is idempotent on (itemId, targetMachineId): a re-ack of
+ *     the same item just refreshes the intent, never stacks duplicates.
+ *   - The operator principal is carried as data the OWNER revalidates at apply
+ *     time — this store never authorizes anything, it only remembers intent.
+ *   - Best-effort writes; a failed append/compact logs loudly (an unrecorded
+ *     ack-intent deserves a trace) but never throws into the ack path.
+ *
+ * This file ships behind the dark gate multiMachine.seamlessness.ws41DurableAck:
+ * when off, the route that feeds it 503s and the store is never constructed, so
+ * a single-machine or flag-off agent is a strict no-op.
+ */
+export interface PendingRemoteAck {
+    /** Attention item id on the OWNING machine. */
+    itemId: string;
+    /** Registry lookup key for the owning machine (never a URL). */
+    targetMachineId: string;
+    /** Normalized attention status the operator chose (e.g. DONE, ACKNOWLEDGED). */
+    status: string;
+    /** Authenticated operator principal that performed the ack (data the owner
+     *  revalidates — never trusted as authorization by this store). */
+    operatorUid: string;
+    /** Operator display name (for the owner's audit; not load-bearing). */
+    operatorDisplayName?: string;
+    /** When the operator's intent was first captured (ISO). */
+    enqueuedAt: string;
+    /** Delivery attempts so far (drain backoff / give-up bound). */
+    attempts: number;
+    /** Last delivery attempt outcome class, for observability. */
+    lastOutcome?: 'pending' | 'unreachable' | 'rejected' | 'stale-superseded';
+}
+export declare class RemoteAckStore {
+    private readonly log;
+    private readonly filePath;
+    /** Keyed on `${itemId}::${targetMachineId}` — idempotent intent. */
+    private readonly pending;
+    private loaded;
+    constructor(stateDir: string, log?: (msg: string) => void);
+    private key;
+    private ensureLoaded;
+    private append;
+    /**
+     * Record (or refresh) the operator's ack intent for an item owned elsewhere.
+     * Idempotent on (itemId, targetMachineId): a repeat ack updates status/principal
+     * and resets attempts rather than stacking a second pending row.
+     */
+    enqueue(intent: Omit<PendingRemoteAck, 'enqueuedAt' | 'attempts' | 'lastOutcome'>): PendingRemoteAck;
+    /** Mark a delivery attempt's outcome (drain observability + backoff input). */
+    recordAttempt(itemId: string, targetMachineId: string, outcome: PendingRemoteAck['lastOutcome']): void;
+    /** Remove a delivered (or owner-rejected-as-stale) intent — terminal. */
+    resolve(itemId: string, targetMachineId: string): void;
+    /** All still-pending intents (for the drain tick / boot sweep / observability). */
+    list(): PendingRemoteAck[];
+    /** Pending intents targeting one machine (drain when that peer comes online). */
+    listForMachine(targetMachineId: string): PendingRemoteAck[];
+    /** Count of still-pending intents (cheap status read). */
+    get size(): number;
+}
+//# sourceMappingURL=RemoteAckStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RemoteAckStore.d.ts","sourceRoot":"","sources":["../../src/core/RemoteAckStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,eAAe,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf;uEACmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,SAAS,GAAG,aAAa,GAAG,UAAU,GAAG,kBAAkB,CAAC;CAC3E;AAED,qBAAa,cAAc;IAQvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,MAAM,CAAS;gBAGrB,QAAQ,EAAE,MAAM,EACC,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAkB;IAK3D,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,YAAY;IA0BpB,OAAO,CAAC,MAAM;IAgBd;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,YAAY,GAAG,UAAU,GAAG,aAAa,CAAC,GAAG,gBAAgB;IAepG,+EAA+E;IAC/E,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,CAAC,aAAa,CAAC,GAAG,IAAI;IAUtG,yEAAyE;IACzE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI;IAgBtD,mFAAmF;IACnF,IAAI,IAAI,gBAAgB,EAAE;IAK1B,iFAAiF;IACjF,cAAc,CAAC,eAAe,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAI3D,0DAA0D;IAC1D,IAAI,IAAI,IAAI,MAAM,CAGjB;CACF"}

package/dist/core/RemoteAckStore.js

@@ -0,0 +1,144 @@
+/**
+ * RemoteAckStore — durable queue for operator-bound attention acks that target
+ * an attention item OWNED BY A DIFFERENT MACHINE (WS4.1 follow-up, CMT-1416).
+ *
+ * The problem this closes: when an operator acknowledges/resolves a pooled
+ * attention item whose owner is briefly offline, the ack PATCH is lost — the
+ * operator's intent evaporates and the item reappears OPEN on the owner's
+ * return. This store persists the ack INTENT (with the authenticated operator
+ * principal that performed it) so it survives the owner being dark; a drain
+ * tick + a boot sweep re-deliver it when the owner comes back.
+ *
+ * Design constraints (mirrors RemoteCloseAudit / PendingInboundStore):
+ *   - Append-then-compact JSONL under logs/ — no DB dependency.
+ *   - Each pending ack is idempotent on (itemId, targetMachineId): a re-ack of
+ *     the same item just refreshes the intent, never stacks duplicates.
+ *   - The operator principal is carried as data the OWNER revalidates at apply
+ *     time — this store never authorizes anything, it only remembers intent.
+ *   - Best-effort writes; a failed append/compact logs loudly (an unrecorded
+ *     ack-intent deserves a trace) but never throws into the ack path.
+ *
+ * This file ships behind the dark gate multiMachine.seamlessness.ws41DurableAck:
+ * when off, the route that feeds it 503s and the store is never constructed, so
+ * a single-machine or flag-off agent is a strict no-op.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+export class RemoteAckStore {
+    log;
+    filePath;
+    /** Keyed on `${itemId}::${targetMachineId}` — idempotent intent. */
+    pending = new Map();
+    loaded = false;
+    constructor(stateDir, log = console.log) {
+        this.log = log;
+        this.filePath = path.join(stateDir, '..', 'logs', 'remote-ack-queue.jsonl');
+    }
+    key(itemId, targetMachineId) {
+        return `${itemId}::${targetMachineId}`;
+    }
+    ensureLoaded() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        try {
+            const raw = fs.readFileSync(this.filePath, 'utf-8');
+            for (const line of raw.split('\n')) {
+                const t = line.trim();
+                if (!t)
+                    continue;
+                try {
+                    const entry = JSON.parse(t);
+                    const k = this.key(entry.itemId, entry.targetMachineId);
+                    if (entry._deleted) {
+                        this.pending.delete(k);
+                    }
+                    else {
+                        this.pending.set(k, entry);
+                    }
+                }
+                catch {
+                    // @silent-fallback-ok — a torn last line (crash mid-append) is skipped;
+                    // the rest of the durable log still loads.
+                }
+            }
+        }
+        catch {
+            // @silent-fallback-ok — absent file reads as empty queue (first run).
+        }
+    }
+    append(entry) {
+        try {
+            fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+            /* state-registry: remote-ack-queue */
+            fs.appendFileSync(this.filePath, JSON.stringify(entry) + '\n');
+        }
+        catch (err) {
+            // Loud, not silent: a lost ack-intent reappears as a re-OPENed item to the
+            // operator later — worth a trace even when the log file is the failure.
+            this.log(`[remote-ack] QUEUE APPEND FAILED (intent held in memory only): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Record (or refresh) the operator's ack intent for an item owned elsewhere.
+     * Idempotent on (itemId, targetMachineId): a repeat ack updates status/principal
+     * and resets attempts rather than stacking a second pending row.
+     */
+    enqueue(intent) {
+        this.ensureLoaded();
+        const k = this.key(intent.itemId, intent.targetMachineId);
+        const existing = this.pending.get(k);
+        const entry = {
+            ...intent,
+            enqueuedAt: existing?.enqueuedAt ?? new Date().toISOString(),
+            attempts: 0,
+            lastOutcome: 'pending',
+        };
+        this.pending.set(k, entry);
+        this.append(entry);
+        return entry;
+    }
+    /** Mark a delivery attempt's outcome (drain observability + backoff input). */
+    recordAttempt(itemId, targetMachineId, outcome) {
+        this.ensureLoaded();
+        const k = this.key(itemId, targetMachineId);
+        const entry = this.pending.get(k);
+        if (!entry)
+            return;
+        entry.attempts += 1;
+        entry.lastOutcome = outcome;
+        this.append(entry);
+    }
+    /** Remove a delivered (or owner-rejected-as-stale) intent — terminal. */
+    resolve(itemId, targetMachineId) {
+        this.ensureLoaded();
+        const k = this.key(itemId, targetMachineId);
+        if (!this.pending.has(k))
+            return;
+        this.pending.delete(k);
+        this.append({
+            itemId,
+            targetMachineId,
+            status: '',
+            operatorUid: '',
+            enqueuedAt: new Date().toISOString(),
+            attempts: 0,
+            _deleted: true,
+        });
+    }
+    /** All still-pending intents (for the drain tick / boot sweep / observability). */
+    list() {
+        this.ensureLoaded();
+        return Array.from(this.pending.values());
+    }
+    /** Pending intents targeting one machine (drain when that peer comes online). */
+    listForMachine(targetMachineId) {
+        return this.list().filter((e) => e.targetMachineId === targetMachineId);
+    }
+    /** Count of still-pending intents (cheap status read). */
+    get size() {
+        this.ensureLoaded();
+        return this.pending.size;
+    }
+}
+//# sourceMappingURL=RemoteAckStore.js.map

package/dist/core/RemoteAckStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RemoteAckStore.js","sourceRoot":"","sources":["../../src/core/RemoteAckStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAsB7B,MAAM,OAAO,cAAc;IAQN;IAPF,QAAQ,CAAS;IAClC,oEAAoE;IACnD,OAAO,GAAG,IAAI,GAAG,EAA4B,CAAC;IACvD,MAAM,GAAG,KAAK,CAAC;IAEvB,YACE,QAAgB,EACC,MAA6B,OAAO,CAAC,GAAG;QAAxC,QAAG,GAAH,GAAG,CAAqC;QAEzD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,wBAAwB,CAAC,CAAC;IAC9E,CAAC;IAEO,GAAG,CAAC,MAAc,EAAE,eAAuB;QACjD,OAAO,GAAG,MAAM,KAAK,eAAe,EAAE,CAAC;IACzC,CAAC;IAEO,YAAY;QAClB,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACpD,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;gBACtB,IAAI,CAAC,CAAC;oBAAE,SAAS;gBACjB,IAAI,CAAC;oBACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAA8C,CAAC;oBACzE,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;oBACxD,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;wBACnB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;oBACzB,CAAC;yBAAM,CAAC;wBACN,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;oBAC7B,CAAC;gBACH,CAAC;gBAAC,MAAM,CAAC;oBACP,wEAAwE;oBACxE,2CAA2C;gBAC7C,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,sEAAsE;QACxE,CAAC;IACH,CAAC;IAEO,MAAM,CAAC,KAAgD;QAC7D,IAAI,CAAC;YACH,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/D,sCAAsC;YACtC,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;QACjE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,2EAA2E;YAC3E,wEAAwE;YACxE,IAAI,CAAC,GAAG,CACN,kEACE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,EAAE,CACH,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,MAAyE;QAC/E,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,eAAe,CAAC,CAAC;QAC1D,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACrC,MAAM,KAAK,GAAqB;YAC9B,GAAG,MAAM;YACT,UAAU,EAAE,QAAQ,EAAE,UAAU,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAC5D,QAAQ,EAAE,CAAC;YACX,WAAW,EAAE,SAAS;SACvB,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAC3B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACnB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,+EAA+E;IAC/E,aAAa,CAAC,MAAc,EAAE,eAAuB,EAAE,OAAwC;QAC7F,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;QAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC;QACpB,KAAK,CAAC,WAAW,GAAG,OAAO,CAAC;QAC5B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;IAED,yEAAyE;IACzE,OAAO,CAAC,MAAc,EAAE,eAAuB;QAC7C,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,OAAO;QACjC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,CAAC,MAAM,CAAC;YACV,MAAM;YACN,eAAe;YACf,MAAM,EAAE,EAAE;YACV,WAAW,EAAE,EAAE;YACf,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACpC,QAAQ,EAAE,CAAC;YACX,QAAQ,EAAE,IAAI;SACf,CAAC,CAAC;IACL,CAAC;IAED,mFAAmF;IACnF,IAAI;QACF,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,iFAAiF;IACjF,cAAc,CAAC,eAAuB;QACpC,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe,KAAK,eAAe,CAAC,CAAC;IAC1E,CAAC;IAED,0DAA0D;IAC1D,IAAI,IAAI;QACN,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF"}

package/dist/core/types.d.ts

@@ -357,6 +357,18 @@ export interface JobDefinition {
      *  re-run must be a deliberate per-job choice. Older agents' job parsers
      *  ignore unknown fields (additive-safe). */
     resumeOnReap?: boolean;
+    /** MULTI-MACHINE-SEAMLESSNESS-SPEC §WS4.3 role-guard-at-spawn — opt this job
+     *  IN as a STATE-WRITING job. A state-writing job mutates shared/replicated
+     *  state that only the writable owner (the lease-holder) may touch; it must
+     *  NOT spawn on a read-only standby. When `multiMachine.seamlessness.ws43RoleGuard`
+     *  is on and this machine does not hold the lease, the scheduler refuses the
+     *  spawn at the spawn boundary (the TOCTOU re-check — a machine awake at boot
+     *  can demote mid-run while its cron tasks keep firing). The writable owner's
+     *  own scheduler runs the job (the cron fires on every machine; only the
+     *  owner's pass clears the guard), so the refusal re-routes by construction.
+     *  Default-absent = NOT state-writing → never guarded (additive-safe; older
+     *  agents' parsers ignore the unknown field). */
+    writesState?: boolean;
     /** Tags for filtering/grouping */
     tags?: string[];
     /** Telegram topic ID this job reports to (auto-created if not set) */
@@ -985,7 +997,7 @@ export interface RelationshipManagerConfig {
      */
     intelligence?: IntelligenceProvider;
 }
-export type SkipReason = 'disabled' | 'paused' | 'quota' | 'memory-pressure' | 'capacity' | 'claimed' | 'machine-scope' | 'already-running' | 'gate';
+export type SkipReason = 'disabled' | 'paused' | 'quota' | 'memory-pressure' | 'capacity' | 'claimed' | 'machine-scope' | 'already-running' | 'role-guard' | 'gate';
 /**
  * Result of a canRunJob gate check. The callback may return a plain boolean
  * (legacy) or this richer form so the scheduler can log/track the actual
@@ -2010,6 +2022,17 @@ export interface MultiMachineConfig {
          * config defaults (the gate decides) — a literal `false` would force-dark dev.
          */
         ws44PoolLinks?: boolean;
+        /**
+         * WS4.3 role-guard-at-spawn (§WS4.3 / F8, F21; CMT-1416). When on, the
+         * scheduler refuses to spawn a STATE-WRITING job (JobDefinition.writesState)
+         * on a machine that does NOT hold the lease — the spawn-boundary TOCTOU
+         * re-check that closes the window where a machine awake at boot demotes to a
+         * read-only standby mid-run while its cron tasks keep firing. DEFAULT
+         * (undefined/false) = strict no-op (byte-for-byte today's behavior). The
+         * writable owner's own scheduler runs the job; a refusal raises ONE deduped
+         * attention item. Single-machine agents always hold the lease → never fires.
+         */
+        ws43RoleGuard?: boolean;
         /**
          * WS4.4 (f) load-shed: when the fronting machine is over this 1-min
          * load-per-core threshold, holder-resolution serves the last-cached