instar 0.28.102 → 0.28.103

package/dist/remediation/runbooks/supervisor-preflight.js

@@ -0,0 +1,299 @@
+/**
+ * supervisor-preflight — the W-2 `ApprovedRunbook` wrapping
+ * `ServerSupervisor.preflightSelfHeal` per spec A34 (composed-multi-step
+ * surface alignment).
+ *
+ * SELF-HEALING-REMEDIATOR-V2-SPEC §A6 (errorCode provenance — structured
+ * sources only), §A9 (verify asserts durability not just liveness), §A21
+ * (verify probe error → verify-inconclusive, distinct from verify-failed),
+ * §A34 (W-2 is ONE runbook composing six heal steps; verify produces a
+ * SINGLE durable-state check after all steps), §A36 (essential requires
+ * blastRadius='machine'), §A57 Tier-2 (W-2 ships after F-5, F-6, F-7,
+ * F-8-rest are on main).
+ *
+ * Surface: `ServerSupervisor.invokeFromRemediator(ctx)` (added by W-2).
+ * The legacy in-line `preflightSelfHeal()` call inside `spawnServer()`
+ * stays unchanged as the boot-path safety net; this runbook is the
+ * parallel, Remediator-orchestrated path.
+ *
+ * Match contract:
+ *   eventPrefilter.errorCode    = ['BIND_FAILURE', 'CRASH_LOOP',
+ *                                  'SUPERVISOR_DEGRADED']
+ *   eventPrefilter.provenance   = ['native-binding', 'subsystem-explicit']
+ *
+ * `'free-text'` is intentionally NOT in the prefilter — §A6 mandates that
+ * runbooks only fire on structured-provenance events. The match() callback
+ * narrows further to lifeline/server subsystems so a same-errorCode event
+ * about an unrelated subsystem (e.g., memory) routes to no-matching-runbook.
+ *
+ * Verify (§A9):
+ *   The verify step asserts the durable lifeline state.json marker exists
+ *   and was written recently (post-restart). Clean marker → verified-healthy.
+ *   Missing or corrupt marker → verify-failed. Probe path error (filesystem
+ *   I/O throws) → verify-inconclusive per §A21 — distinct from verify-failed.
+ *
+ * essential:
+ *   This runbook is `essential: true`. A wedged supervisor (bind-failure
+ *   crash loop, shadow-install missing, better-sqlite3 ABI mismatch,
+ *   merged-conflict settings.json) DoSes every server-mediated capability:
+ *   Telegram relay, dashboard, jobs scheduler, threadline. Without the
+ *   heal, the agent is offline. blastRadius is 'machine' (preflight
+ *   touches shadow-install/node_modules, the node symlink, the git tree,
+ *   and the lifeline state directory), which satisfies §A36's validator.
+ *
+ * A15 partial-upgrade rule (Tier-2 build-acceleration carve-out):
+ *   F-6 (the supervisor handshake the W-2 runbook depends on) merged on
+ *   2026-05-13. The 7-day lag rule applies to PRODUCTION CUTOVER — turning
+ *   the runbook live for end-users — not to the BUILD of the runbook code
+ *   itself. The wrapper is constructible and unit-testable today; live
+ *   activation gates on the separate `wrappers-active-after` config flag
+ *   (defaults to false) and is the Tier-3 wiring PR's concern.
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import { markerPath } from '../../lifeline/startupMarker.js';
+// ── Verify probe ─────────────────────────────────────────────────────────
+/**
+ * §A9 durable-state assertion for the supervisor-preflight runbook. The
+ * preflight heals six prerequisites:
+ *
+ *   1. shadow-install
+ *   2. node symlink
+ *   3. stuck git rebase
+ *   4. better-sqlite3 ABI mismatch
+ *   5. stale lifeline lock
+ *   6. settings.json merge-conflict
+ *
+ * Verifying every step in isolation would multiply the verify surface six-
+ * fold and re-implement detection logic the preflight body already owns.
+ * Per §A34, the verify produces a SINGLE durable-state check: did the
+ * lifeline re-spawn cleanly after the heal? The signal we read is the
+ * `lifeline-started-at.json` startup marker — written unconditionally
+ * by every lifeline startup, including the post-preflight one.
+ *
+ * Returns:
+ *   - kind: 'ok'           — marker present, well-formed, fresh-enough
+ *   - kind: 'failed'       — marker missing or corrupt (post-preflight
+ *                            spawn did NOT happen → heal did not durably
+ *                            recover the supervisor)
+ *   - kind: 'inconclusive' — filesystem probe threw (cannot determine
+ *                            durability one way or the other → §A21)
+ */
+export function verifyLifelineDurable(stateDir, options = {}) {
+    const maxAgeMs = options.maxAgeMs ?? 10 * 60_000; // 10 min default
+    const now = options.nowMs ?? Date.now();
+    try {
+        const p = markerPath(stateDir);
+        let raw;
+        try {
+            raw = fs.readFileSync(p, 'utf-8');
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === 'ENOENT') {
+                return {
+                    kind: 'failed',
+                    reason: `lifeline startup marker missing at ${p}`,
+                };
+            }
+            // EACCES, EIO, etc — probe error, not durability failure.
+            return {
+                kind: 'inconclusive',
+                reason: `marker readFileSync threw (${code ?? 'unknown'}): ${err.message}`,
+            };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            return {
+                kind: 'failed',
+                reason: `marker JSON parse failed: ${err.message.slice(0, 200)}`,
+            };
+        }
+        if (!parsed ||
+            typeof parsed !== 'object' ||
+            typeof parsed.startedAt !== 'string' ||
+            typeof parsed.pid !== 'number' ||
+            typeof parsed.version !== 'string') {
+            return {
+                kind: 'failed',
+                reason: 'marker shape invalid (missing startedAt/pid/version)',
+            };
+        }
+        const startedAtMs = Date.parse(parsed.startedAt);
+        if (!Number.isFinite(startedAtMs)) {
+            return {
+                kind: 'failed',
+                reason: `marker startedAt is unparseable: ${parsed.startedAt}`,
+            };
+        }
+        const ageMs = now - startedAtMs;
+        if (ageMs > maxAgeMs) {
+            return {
+                kind: 'failed',
+                reason: `marker is stale (ageMs=${ageMs} > maxAgeMs=${maxAgeMs}) — lifeline did not respawn post-heal`,
+            };
+        }
+        // Negative age = clock skew or marker from the future. Treat as probe
+        // error (§A21) rather than failure — we cannot confidently say durability
+        // is broken when the clocks disagree.
+        if (ageMs < -60_000) {
+            return {
+                kind: 'inconclusive',
+                reason: `marker startedAt is in the future (ageMs=${ageMs}) — clock-skew probe error`,
+            };
+        }
+        return { kind: 'ok', markerStartedAt: parsed.startedAt };
+    }
+    catch (err) {
+        return {
+            kind: 'inconclusive',
+            reason: `verify wrapper threw: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+let _verifyImpl = null;
+export function _setVerifyImplForTesting(fn) {
+    _verifyImpl = fn;
+}
+/**
+ * Allow tests to inject a stub supervisor so the runbook can run end-to-end
+ * without spawning a real tmux session or touching the on-disk shadow-install.
+ */
+let _supervisorForTesting = null;
+export function _setSupervisorForTesting(s) {
+    _supervisorForTesting = s;
+}
+/**
+ * The state directory the verify step reads the lifeline marker from. Tests
+ * inject a tmpdir; production callers configure this at runbook-registration
+ * via a closure (the runbook factory) — for now, allow override.
+ */
+let _stateDirForVerify = null;
+export function _setStateDirForVerify(dir) {
+    _stateDirForVerify = dir;
+}
+// ── Match helpers ────────────────────────────────────────────────────────
+const SUPERVISOR_SUBSYSTEMS = new Set([
+    'lifeline',
+    'server',
+    'supervisor',
+    // Legacy emit-sites tag the server subsystem as 'http' in some places.
+    // Match() narrows to those by inspecting reason text.
+]);
+const SUPERVISOR_ERROR_CODES = ['BIND_FAILURE', 'CRASH_LOOP', 'SUPERVISOR_DEGRADED'];
+// ── ApprovedRunbook ──────────────────────────────────────────────────────
+export const supervisorPreflightRunbook = {
+    id: 'supervisor-preflight',
+    // Lower than W-1 (node-abi-mismatch=100). When a BIND_FAILURE event also
+    // carries a NATIVE_MODULE_ABI_MISMATCH errorCode (rare but possible during
+    // crash-loop diagnosis), W-1's runbook is the right surface to dispatch
+    // because it's the precise heal. supervisor-preflight is the broad heal
+    // for the bind-failure root-cause class.
+    priority: 90,
+    surface: 'supervisor',
+    eventPrefilter: {
+        errorCode: SUPERVISOR_ERROR_CODES,
+        // §A6: NOT free-text. Only structured-provenance events fire this runbook.
+        provenance: ['native-binding', 'subsystem-explicit'],
+    },
+    match: (event) => {
+        // Narrow to lifeline/server subsystems. Defence-in-depth: a BIND_FAILURE
+        // event for an unrelated subsystem (e.g., a future memory-bind-failure)
+        // should NOT trigger a supervisor preflight.
+        if (SUPERVISOR_SUBSYSTEMS.has(event.subsystem))
+            return true;
+        // Legacy free-text subsystems may use 'http' or 'tunnel' — inspect the
+        // reason for an explicit supervisor/server/lifeline mention.
+        const reasonText = event.reason.full ?? event.reason.redacted ?? '';
+        return /\b(server|lifeline|supervisor)\b/i.test(reasonText);
+    },
+    preconditions: async (_event) => {
+        // Cheap guard: stateDir must be set + accessible (the supervisor cannot
+        // heal without somewhere to read/write shadow-install).
+        if (!_stateDirForVerify)
+            return true; // Production callers wire the dir
+        try {
+            fs.accessSync(_stateDirForVerify, fs.constants.R_OK | fs.constants.W_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    surfaceCallable: async (ctx) => {
+        const supervisor = _supervisorForTesting;
+        if (!supervisor) {
+            // Production callers must wire a supervisor instance via the runbook
+            // factory pattern. Until that lands (Tier-3 dispatcher wiring), the
+            // surfaceCallable returns a failure that surfaces in the audit
+            // projection as `surfaceCallable returned outcome=failure`.
+            return {
+                outcome: 'failure',
+                details: {
+                    reason: 'no-supervisor-wired',
+                    attemptId: ctx.attemptId,
+                },
+            };
+        }
+        const result = await supervisor.invokeFromRemediator(ctx);
+        // The Remediator's `ExecutionResult` type matches the supervisor's
+        // `SupervisorRemediatorExecutionResult` shape; pass through verbatim.
+        return result;
+    },
+    verify: async (ctx) => {
+        const impl = _verifyImpl;
+        let probe;
+        if (impl) {
+            probe = impl(ctx);
+        }
+        else if (_stateDirForVerify) {
+            probe = verifyLifelineDurable(_stateDirForVerify);
+        }
+        else {
+            probe = {
+                kind: 'inconclusive',
+                reason: 'no stateDir wired for verify — cannot read lifeline marker',
+            };
+        }
+        switch (probe.kind) {
+            case 'ok':
+                return {
+                    outcome: 'verified-healthy',
+                    reason: `lifeline marker present (startedAt=${probe.markerStartedAt}); preflight durable`,
+                };
+            case 'failed':
+                return { outcome: 'verify-failed', reason: probe.reason };
+            case 'inconclusive':
+                return { outcome: 'verify-inconclusive', reason: probe.reason };
+        }
+    },
+    blastRadius: 'machine',
+    reversibility: 'reversible',
+    // 3 minutes. Cold-cache shadow-install reinstall + better-sqlite3 rebuild
+    // can both run in one preflight cycle; each takes ~30-60s on slow hardware.
+    // The deadline race in F-8 will abort with `aborted-deadline` if exceeded.
+    expectedRuntimeMs: 180_000,
+    // §A36: essential requires blastRadius='machine' (satisfied above). A
+    // wedged supervisor DoSes every server-mediated capability, so this is the
+    // canonical essential runbook for the supervisor surface.
+    essential: true,
+};
+// Re-export the path helper so consumers can compute the marker location
+// without re-importing from `src/lifeline/startupMarker.ts`.
+export { markerPath as supervisorMarkerPath };
+// For tests/observability — list the durable state assertions.
+export const VERIFIED_HEAL_TARGETS = [
+    'shadow-install',
+    'node-symlink',
+    'git-rebase',
+    'better-sqlite3-abi',
+    'stale-lifeline-lock',
+    'settings-json',
+];
+/** No-op compile-time use to keep `path` import alive for future helpers. */
+const _ = path;
+void _;
+//# sourceMappingURL=supervisor-preflight.js.map

package/dist/remediation/runbooks/supervisor-preflight.js.map

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

package/dist/scheduler/AgentMdAtomicSave.d.ts

@@ -0,0 +1,85 @@
+/**
+ * AgentMdAtomicSave — race-safe two-rename commit for agentmd job edits.
+ *
+ * Per INSTAR-JOBS-AS-AGENTMD spec §Design Principles "Override = fork;
+ * race-safe two-rename commit":
+ *
+ *   The save sequence is md-first, manifest-last:
+ *     1. Write `<file>.md.new` (staged body).
+ *     2. Write `<schedule>.json.new` (staged manifest).
+ *     3. rename(<file>.md.new → <file>.md)          ← rename A
+ *     4. rename(<schedule>.json.new → <schedule>.json)  ← rename B
+ *
+ * SIGKILL between rename A and rename B leaves a consistent state: the
+ * new body is on disk paired with the OLD manifest. The loader handles
+ * this gracefully — it loads the new body and the old manifest's
+ * schedule, which is a strictly-progressed state.
+ *
+ * SIGKILL before rename A is also consistent: the old body + old
+ * manifest are intact; the `.new` staged files are orphaned and the next
+ * boot's reconcile() can either reapply or discard them.
+ *
+ * Re-applying a half-committed save is idempotent because each rename is
+ * atomic at the filesystem level and overwrites any pre-existing target.
+ *
+ * This module is the canonical save helper for both Dashboard edits and
+ * future CLI edit commands. It is NOT yet wired into a UI consumer — the
+ * Phase 4 Dashboard UI rewrite is the consumer. Shipping the helper
+ * separately so the spec's atomicity guarantee has a tested
+ * implementation regardless of when the UI lands.
+ */
+export interface AtomicSaveInput {
+    /** Final on-disk path of the .md body (e.g., `.instar/jobs/user/<slug>.md`). */
+    mdPath: string;
+    /** Final on-disk path of the per-slug manifest (e.g.,
+     *  `.instar/jobs/schedule/<slug>.json`). */
+    manifestPath: string;
+    /** Bytes to write to mdPath. Caller is responsible for any normalization. */
+    mdBody: string;
+    /** Object to JSON-serialize into manifestPath. */
+    manifest: Record<string, unknown>;
+}
+export interface AtomicSaveResult {
+    ok: true;
+    mdWritten: string;
+    manifestWritten: string;
+}
+export interface AtomicSaveFailure {
+    ok: false;
+    stage: 'stage-md' | 'stage-manifest' | 'commit-md' | 'commit-manifest';
+    reason: string;
+    partial: {
+        mdNewExists: boolean;
+        manifestNewExists: boolean;
+        mdCommitted: boolean;
+        manifestCommitted: boolean;
+    };
+}
+/**
+ * Two-rename atomic save. Writes the body first, then the manifest. Each
+ * write goes to a `.new` sibling, then renames atomically over the final
+ * path. On failure at any stage, returns a structured `AtomicSaveFailure`
+ * the caller can use to drive recovery / Issues-card surface.
+ *
+ * Implementation notes:
+ *   - We DO NOT delete the staged `.new` files on failure — leaving them
+ *     in place gives reconcile() something to reason about. The next
+ *     successful save will overwrite them.
+ *   - `fs.renameSync` is atomic on POSIX filesystems for paths on the
+ *     same filesystem (always the case here — both live under .instar/).
+ *   - `fs.writeFileSync` with `flag: 'w'` truncates; we use it
+ *     deliberately so a half-written `.new` on retry is replaced.
+ */
+export declare function atomicSaveAgentMdJob(input: AtomicSaveInput): AtomicSaveResult | AtomicSaveFailure;
+/**
+ * Discover any `.new` staged files left over from a crashed save. Used by
+ * reconcile() to surface "interrupted save" Issues-card rows.
+ */
+export declare function listStagedNewFiles(jobsRootDir: string): string[];
+/**
+ * Clean up an orphaned `.new` file. Used by reconcile() when the operator
+ * chooses "Discard staged changes" in the Issues-card UI. Routes through
+ * SafeFsExecutor per the destructive-tool funnel.
+ */
+export declare function discardStagedFile(stagedPath: string): void;
+//# sourceMappingURL=AgentMdAtomicSave.d.ts.map

package/dist/scheduler/AgentMdAtomicSave.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentMdAtomicSave.d.ts","sourceRoot":"","sources":["../../src/scheduler/AgentMdAtomicSave.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf;gDAC4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,IAAI,CAAC;IACT,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,UAAU,GAAG,gBAAgB,GAAG,WAAW,GAAG,iBAAiB,CAAC;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE;QACP,WAAW,EAAE,OAAO,CAAC;QACrB,iBAAiB,EAAE,OAAO,CAAC;QAC3B,WAAW,EAAE,OAAO,CAAC;QACrB,iBAAiB,EAAE,OAAO,CAAC;KAC5B,CAAC;CACH;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,GAAG,iBAAiB,CAiFjG;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAQhE;AAiBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAE1D"}

package/dist/scheduler/AgentMdAtomicSave.js

@@ -0,0 +1,169 @@
+/**
+ * AgentMdAtomicSave — race-safe two-rename commit for agentmd job edits.
+ *
+ * Per INSTAR-JOBS-AS-AGENTMD spec §Design Principles "Override = fork;
+ * race-safe two-rename commit":
+ *
+ *   The save sequence is md-first, manifest-last:
+ *     1. Write `<file>.md.new` (staged body).
+ *     2. Write `<schedule>.json.new` (staged manifest).
+ *     3. rename(<file>.md.new → <file>.md)          ← rename A
+ *     4. rename(<schedule>.json.new → <schedule>.json)  ← rename B
+ *
+ * SIGKILL between rename A and rename B leaves a consistent state: the
+ * new body is on disk paired with the OLD manifest. The loader handles
+ * this gracefully — it loads the new body and the old manifest's
+ * schedule, which is a strictly-progressed state.
+ *
+ * SIGKILL before rename A is also consistent: the old body + old
+ * manifest are intact; the `.new` staged files are orphaned and the next
+ * boot's reconcile() can either reapply or discard them.
+ *
+ * Re-applying a half-committed save is idempotent because each rename is
+ * atomic at the filesystem level and overwrites any pre-existing target.
+ *
+ * This module is the canonical save helper for both Dashboard edits and
+ * future CLI edit commands. It is NOT yet wired into a UI consumer — the
+ * Phase 4 Dashboard UI rewrite is the consumer. Shipping the helper
+ * separately so the spec's atomicity guarantee has a tested
+ * implementation regardless of when the UI lands.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { SafeFsExecutor } from '../core/SafeFsExecutor.js';
+/**
+ * Two-rename atomic save. Writes the body first, then the manifest. Each
+ * write goes to a `.new` sibling, then renames atomically over the final
+ * path. On failure at any stage, returns a structured `AtomicSaveFailure`
+ * the caller can use to drive recovery / Issues-card surface.
+ *
+ * Implementation notes:
+ *   - We DO NOT delete the staged `.new` files on failure — leaving them
+ *     in place gives reconcile() something to reason about. The next
+ *     successful save will overwrite them.
+ *   - `fs.renameSync` is atomic on POSIX filesystems for paths on the
+ *     same filesystem (always the case here — both live under .instar/).
+ *   - `fs.writeFileSync` with `flag: 'w'` truncates; we use it
+ *     deliberately so a half-written `.new` on retry is replaced.
+ */
+export function atomicSaveAgentMdJob(input) {
+    const { mdPath, manifestPath, mdBody, manifest } = input;
+    const mdNew = mdPath + '.new';
+    const manifestNew = manifestPath + '.new';
+    const partial = {
+        mdNewExists: false,
+        manifestNewExists: false,
+        mdCommitted: false,
+        manifestCommitted: false,
+    };
+    // Stage 1: ensure both parent directories exist.
+    try {
+        fs.mkdirSync(path.dirname(mdPath), { recursive: true });
+        fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            stage: 'stage-md',
+            reason: `Failed to create parent directories: ${err instanceof Error ? err.message : String(err)}`,
+            partial,
+        };
+    }
+    // Stage 2: write the body to its .new sibling.
+    try {
+        fs.writeFileSync(mdNew, mdBody, { encoding: 'utf-8', flag: 'w' });
+        partial.mdNewExists = true;
+    }
+    catch (err) {
+        return {
+            ok: false,
+            stage: 'stage-md',
+            reason: `Failed to stage md body: ${err instanceof Error ? err.message : String(err)}`,
+            partial,
+        };
+    }
+    // Stage 3: write the manifest to its .new sibling.
+    try {
+        fs.writeFileSync(manifestNew, JSON.stringify(manifest, null, 2) + '\n', { encoding: 'utf-8', flag: 'w' });
+        partial.manifestNewExists = true;
+    }
+    catch (err) {
+        return {
+            ok: false,
+            stage: 'stage-manifest',
+            reason: `Failed to stage manifest: ${err instanceof Error ? err.message : String(err)}`,
+            partial,
+        };
+    }
+    // Stage 4 (rename A): commit md-first. After this, the body is durable.
+    try {
+        fs.renameSync(mdNew, mdPath);
+        partial.mdCommitted = true;
+        partial.mdNewExists = false;
+    }
+    catch (err) {
+        return {
+            ok: false,
+            stage: 'commit-md',
+            reason: `Failed to commit md body: ${err instanceof Error ? err.message : String(err)}`,
+            partial,
+        };
+    }
+    // Stage 5 (rename B): commit manifest-last. SIGKILL between renames A
+    // and B leaves the new body + old manifest, which is a consistent
+    // strictly-progressed state.
+    try {
+        fs.renameSync(manifestNew, manifestPath);
+        partial.manifestCommitted = true;
+        partial.manifestNewExists = false;
+    }
+    catch (err) {
+        return {
+            ok: false,
+            stage: 'commit-manifest',
+            reason: `Failed to commit manifest: ${err instanceof Error ? err.message : String(err)}`,
+            partial,
+        };
+    }
+    return { ok: true, mdWritten: mdPath, manifestWritten: manifestPath };
+}
+/**
+ * Discover any `.new` staged files left over from a crashed save. Used by
+ * reconcile() to surface "interrupted save" Issues-card rows.
+ */
+export function listStagedNewFiles(jobsRootDir) {
+    const staged = [];
+    walk(jobsRootDir, (file) => {
+        if (file.endsWith('.md.new') || file.endsWith('.json.new')) {
+            staged.push(file);
+        }
+    });
+    return staged;
+}
+function walk(dir, visit) {
+    if (!fs.existsSync(dir))
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        const p = path.join(dir, e.name);
+        if (e.isDirectory())
+            walk(p, visit);
+        else if (e.isFile())
+            visit(p);
+    }
+}
+/**
+ * Clean up an orphaned `.new` file. Used by reconcile() when the operator
+ * chooses "Discard staged changes" in the Issues-card UI. Routes through
+ * SafeFsExecutor per the destructive-tool funnel.
+ */
+export function discardStagedFile(stagedPath) {
+    SafeFsExecutor.safeUnlinkSync(stagedPath, { operation: 'AgentMdAtomicSave discard staged .new file' });
+}
+//# sourceMappingURL=AgentMdAtomicSave.js.map

package/dist/scheduler/AgentMdAtomicSave.js.map

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

package/dist/scheduler/AgentMdReconcile.d.ts

@@ -0,0 +1,62 @@
+/**
+ * AgentMdReconcile — boot-time consistency check for the agentmd job tree.
+ *
+ * Per INSTAR-JOBS-AS-AGENTMD spec §Runtime "Load lifecycle (boot)":
+ *
+ *   reconcile() runs at boot, surfaces orphan/shadow/missing on boot.
+ *   Output goes to Dashboard Issues card.
+ *
+ * Categories surfaced:
+ *
+ *   - ORPHAN-MANIFEST: A `<slug>.json` per-slug manifest exists but the
+ *     `.md` it references does NOT. Scheduler cannot resolve the body;
+ *     entry is excluded from jobs[] and surfaced as Issues-card row.
+ *
+ *   - SHADOW-MD: A `<slug>.md` exists in either `instar/` or `user/` but
+ *     has no per-slug manifest. The body is on disk but the scheduler
+ *     has no schedule for it — Issues-card "Add to schedule (disabled)"
+ *     or "Delete file" actions apply.
+ *
+ *   - MISSING-FROM-JOBS-JSON: A legacy `jobs.json` entry has no
+ *     corresponding per-slug manifest AND no `.md` under user/ or
+ *     instar/. Mid-migration state; not yet copied over.
+ *
+ *   - STAGED-NEW: A `.md.new` or `.json.new` left over from a crashed
+ *     atomic save (see AgentMdAtomicSave). Issues-card "Apply" /
+ *     "Discard" actions apply.
+ *
+ *   - CASE-COLLISION: Two slug files differ only by case (NFC normalized)
+ *     in the same directory. Both are excluded from jobs[] by the
+ *     loader; this row surfaces them together.
+ *
+ * Pure function — reads the file system, returns a structured report.
+ * The caller (boot lifecycle in JobLoader; Phase 4 Dashboard read
+ * endpoint) decides how to present the rows.
+ */
+export type ReconcileFindingKind = 'orphan-manifest' | 'shadow-md' | 'missing-from-jobs-json' | 'staged-new' | 'case-collision';
+export interface ReconcileFinding {
+    kind: ReconcileFindingKind;
+    /** Affected slug (when computable). */
+    slug?: string;
+    /** Affected file path (absolute). */
+    filePath?: string;
+    /** Two-pane comparison: for case-collision, both paths. */
+    conflictingPaths?: string[];
+    /** One-line operator-facing summary. */
+    summary: string;
+    /** Stable severity ordering for the Issues card. */
+    severity: 'info' | 'warning' | 'error';
+}
+export interface ReconcileReport {
+    findings: ReconcileFinding[];
+    summary: {
+        total: number;
+        byKind: Record<ReconcileFindingKind, number>;
+    };
+}
+export interface ReconcileOptions {
+    /** State directory root (e.g., `<projectDir>/.instar/`). */
+    stateDir: string;
+}
+export declare function reconcileAgentMdTree(opts: ReconcileOptions): ReconcileReport;
+//# sourceMappingURL=AgentMdReconcile.d.ts.map

package/dist/scheduler/AgentMdReconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentMdReconcile.d.ts","sourceRoot":"","sources":["../../src/scheduler/AgentMdReconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AA8BH,MAAM,MAAM,oBAAoB,GAC5B,iBAAiB,GACjB,WAAW,GACX,wBAAwB,GACxB,YAAY,GACZ,gBAAgB,CAAC;AAErB,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;CACxC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,OAAO,EAAE;QACP,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;KAC9C,CAAC;CACH;AAED,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAUD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,gBAAgB,GAAG,eAAe,CAoH5E"}