@opengsd/gsd-core 1.7.0-rc.1 → 1.7.0-rc.3

package/gsd-core/bin/lib/capability-source.cjs

@@ -153,16 +153,31 @@ function _setCapabilitySourceHttpGet(fn) {
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-/** Resolve the running GSD version; fail-closed to '0.0.0'. */
-function readHostVersion() {
+/**
+ * Resolve the running GSD version; fail-closed to '0.0.0'.
+ *
+ * Prefer the authoritative `gsd-core/VERSION` the installer writes for EVERY runtime
+ * (libDir = gsd-core/bin/lib/, so `../../VERSION` = gsd-core/VERSION), so installed
+ * layouts report the true version even when the walked-up `../../../package.json` is
+ * absent or belongs to the user's own project (#1920). Fall back to the runtime-root
+ * package.json (dev/source tree), then fail-closed. Mirrors resolveVersionFrom() (#1383).
+ */
+function readHostVersion(libDir = __dirname) {
+    const SEMVER_PREFIX = /^\d+\.\d+\.\d+/;
     try {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const pkg = require('../../../package.json');
-        return typeof pkg.version === 'string' && pkg.version ? pkg.version : '0.0.0';
+        const v = node_fs_1.default.readFileSync(node_path_1.default.join(libDir, '..', '..', 'VERSION'), 'utf8').trim();
+        if (SEMVER_PREFIX.test(v))
+            return v;
     }
-    catch {
-        return '0.0.0';
+    catch { /* not an installed tree (no gsd-core/VERSION) */ }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const pkg = require(node_path_1.default.join(libDir, '..', '..', '..', 'package.json'));
+        if (pkg && typeof pkg.version === 'string' && SEMVER_PREFIX.test(pkg.version))
+            return pkg.version;
     }
+    catch { /* runtime root has no package.json */ }
+    return '0.0.0';
 }
 /** Compute sha512-<base64> integrity over a buffer. */
 function computeIntegrity(buf) {

package/gsd-core/bin/lib/capability-validator.cjs

@@ -704,7 +704,12 @@ const VALID_CONFIG_FORMATS = new Set(['settings-json', 'toml', 'markdown', 'mark
 const VALID_CONFIG_HOME_KINDS = new Set(['dot-home', 'dot-home-nested', 'xdg', 'generic-agents-root']);
 const VALID_COMMAND_STYLES = new Set(['slash-hyphen', 'shell-var']);
 const VALID_HOOKS_SURFACES = new Set(['settings-json', 'codex-hooks-json', 'cursor-hooks-json', 'copilot-inline', 'cline-rules', 'none']);
-const VALID_HOOK_EVENTS = new Set(['claude', 'gemini', 'opencode-subset']);
+const VALID_HOOK_EVENTS = new Set(['claude', 'gemini']);
+// extensionEvents — the plugin/extension-system event dialect (ADR-1239 amendment / #1943).
+// DISTINCT from hookEvents (managed-hook dialect): extensionEvents describes the
+// plugin-owned event subset imperative hosts expose (opencode / pi); 'none' = the
+// host exposes no extension surface (engine owns the bus, e.g. VS Code).
+const VALID_EXTENSION_EVENTS = new Set(['opencode', 'pi', 'none']);
 const VALID_SANDBOX_TIERS = new Set(['none', 'codex-agent-sandbox']);
 const VALID_ARTIFACT_KIND_NAMES = new Set(['commands', 'agents', 'skills', 'kimi-agents']);
 const VALID_ARTIFACT_NESTINGS = new Set(['flat', 'nested']);
@@ -978,7 +983,9 @@ function validateRuntimeBody(cap) {
     );
   }
 
-  // hookEvents — optional; if present must be in closed 3-enum (ADR-1016 Decision 5)
+  // hookEvents — optional; if present must be in closed enum (ADR-1016 Decision 5).
+  // Managed-hook dialect only (claude/gemini). The OpenCode extension-system event
+  // subset is NOT a hookEvents value — it is `extensionEvents` (ADR-1239 / #1943).
   if (r.hookEvents !== undefined) {
     if (r.hookEvents === '__proto__' || r.hookEvents === 'constructor' || r.hookEvents === 'prototype') {
       errors.push('runtime.hookEvents "' + r.hookEvents + '" is a reserved name');
@@ -990,6 +997,20 @@ function validateRuntimeBody(cap) {
     }
   }
 
+  // extensionEvents — optional; the extension-system event dialect (ADR-1239 amendment / #1943).
+  // Distinct from hookEvents. Only imperative-embedding hosts (with a plugin/extension
+  // API) set it; declarative hosts do not.
+  if (r.extensionEvents !== undefined) {
+    if (r.extensionEvents === '__proto__' || r.extensionEvents === 'constructor' || r.extensionEvents === 'prototype') {
+      errors.push('runtime.extensionEvents "' + r.extensionEvents + '" is a reserved name');
+    } else if (!VALID_EXTENSION_EVENTS.has(r.extensionEvents)) {
+      errors.push(
+        'runtime.extensionEvents must be one of: ' + [...VALID_EXTENSION_EVENTS].join(', ') +
+        ' (got: ' + JSON.stringify(r.extensionEvents) + ')',
+      );
+    }
+  }
+
   // sandboxTier — closed 2-enum (ADR-1016 Decision 6); inline literal guard (CodeQL barrier)
   if (r.sandboxTier === '__proto__' || r.sandboxTier === 'constructor' || r.sandboxTier === 'prototype') {
     errors.push('runtime.sandboxTier "' + r.sandboxTier + '" is a reserved name');
@@ -2225,6 +2246,7 @@ module.exports = {
   VALID_COMMAND_STYLES,
   VALID_HOOKS_SURFACES,
   VALID_HOOK_EVENTS,
+  VALID_EXTENSION_EVENTS,
   VALID_SANDBOX_TIERS,
   VALID_ARTIFACT_KIND_NAMES,
   VALID_ARTIFACT_NESTINGS,

package/gsd-core/bin/lib/check-command-router.cjs

@@ -34,6 +34,10 @@ const { getRoadmapPhaseWithFallback } = roadmapModule;
 const gapCheckerModule = require("./gap-checker.cjs");
 const { runGapAnalysis } = gapCheckerModule;
 const prohibition_enforcement_cjs_1 = require("./prohibition-enforcement.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const gatePredicateEval = require("./gate-predicate-evaluator.cjs");
+const { evaluatePredicate } = gatePredicateEval;
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 function normalizePhrase(text) {
     // eslint-disable-next-line @typescript-eslint/no-base-to-string
@@ -778,6 +782,100 @@ function cmdGapAnalysisPlanPost(projectDir, args, raw) {
         message: result.table || result.summary || '',
     }, raw, undefined);
 }
+// ─── predicate (generic gate-predicate evaluator, #2008) ──────────────────────
+/**
+ * Production subprocess binding for the gate-predicate evaluator. Wraps the
+ * bounded `execTool` seam (shell-command-projection) as a `runBoundedShell`
+ * the pure evaluator consumes. `sh -c` runs the interpolated command; the
+ * subprocess inherits the process env and is killed (SIGTERM) on timeout.
+ *
+ * `timedOut` is derived from the kill signal: spawnSync sets `signal: 'SIGTERM'`
+ * when the `timeout` fires, distinct from a normal non-zero exit code. A command
+ * that self-terminates with SIGTERM is indistinguishable at this seam and is
+ * reported as a timeout — either way the gate blocks (non-zero), so the outcome
+ * is fail-closed and correct. See ADR-2008.
+ */
+function buildPredicateDeps() {
+    return {
+        runBoundedShell(opts) {
+            const r = (0, shell_command_projection_cjs_1.execTool)('sh', ['-c', opts.command], { cwd: opts.cwd, timeout: opts.timeoutMs });
+            return {
+                exitCode: r.exitCode,
+                stdout: r.stdout,
+                stderr: r.stderr,
+                signal: r.signal,
+                timedOut: r.signal === 'SIGTERM',
+            };
+        },
+    };
+}
+/** Parse `--flag value` pairs from an args array into a map (last write wins). */
+function parsePredicateFlags(args) {
+    const out = {};
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (typeof a !== 'string')
+            continue;
+        if (!a.startsWith('--'))
+            continue;
+        const key = a.slice(2);
+        const next = args[i + 1];
+        if (key.length > 0 && typeof next === 'string' && !next.startsWith('--')) {
+            out[key] = next;
+            i++;
+        }
+    }
+    return out;
+}
+/**
+ * `check predicate` — generic evaluator for capability gate `check.predicate`
+ * blocks (#2008). The workflow gate-dispatch invokes this for any gate whose
+ * `check` carries a `predicate` (instead of a `query`); the predicate object is
+ * passed as `--predicate '<json>'`. Emits the standard `{ block, message,
+ * details? }` gate contract on success. A malformed predicate / unknown kind
+ * THROWS inside the evaluator and is mapped here to `error()` (non-zero exit),
+ * which the workflow's two-step gate contract treats as a step-1 command failure
+ * routed per the gate's `onError`.
+ *
+ * Invocation:
+ *   gsd_run check predicate --predicate '<json>' \
+ *     [--phase-dir <dir>] [--phase-number <n>] [--phase-req-ids <ids>] --raw
+ *
+ * The subprocess runs at the runtime project root (the `cwd` passed to this
+ * router), inheriting the process env. Interpolation placeholders
+ * ${PHASE_NUMBER}/${PHASE_DIR}/${PHASE_REQ_IDS} are substituted from the flags.
+ */
+function cmdCheckPredicate(projectDir, args, raw) {
+    const flags = parsePredicateFlags(args);
+    const predicateJson = flags['predicate'];
+    if (!predicateJson) {
+        error('predicate requires --predicate <json> (the gate hook check.predicate object)', ERROR_REASON.SDK_MISSING_ARG);
+        return;
+    }
+    let predicate;
+    try {
+        predicate = JSON.parse(predicateJson);
+    }
+    catch {
+        error('predicate --predicate value must be valid JSON', ERROR_REASON.USAGE);
+        return;
+    }
+    const ctx = {
+        cwd: projectDir,
+        phaseNumber: flags['phase-number'],
+        phaseDir: flags['phase-dir'],
+        phaseReqIds: flags['phase-req-ids'],
+    };
+    let result;
+    try {
+        result = evaluatePredicate(predicate, ctx, buildPredicateDeps());
+    }
+    catch (e) {
+        error(`gate predicate evaluation failed: ${e.message}`, ERROR_REASON.USAGE);
+        return;
+    }
+    output(result, raw, undefined);
+}
 function routeCheckCommand({ args, cwd, raw }) {
     // Normalize dots to hyphens in the subcommand so both forms are accepted.
     // This makes `check.query = "ui.plan-gate"` (dotted form in capability.json gates)
@@ -830,6 +928,15 @@ function routeCheckCommand({ args, cwd, raw }) {
         cmdVerifyCodebaseDrift(cwd, raw);
         return;
     }
+    if (subcommand === 'predicate') {
+        // Generic gate-predicate evaluator (#2008). The workflow gate-dispatch calls
+        // this for any gate whose `check` carries a `predicate` (instead of a `query`),
+        // passing the predicate object as --predicate '<json>'. NOTE: unlike the
+        // `check.query` subcommands above (which take positional phase args), this
+        // subcommand parses --flag value pairs.
+        cmdCheckPredicate(cwd, args, raw);
+        return;
+    }
     if (subcommand === 'prohibition-enforcement') {
         // The deterministic test-tier prohibition PRODUCER/gate (#1259, ADR-550 D5d). Locates the
         // wired mechanical check (node-test or lint-rule), confirms fail-first, runs it, builds
@@ -838,7 +945,7 @@ function routeCheckCommand({ args, cwd, raw }) {
         (0, prohibition_enforcement_cjs_1.routeProhibitionEnforcement)(args, raw);
         return;
     }
-    error('Unknown check subcommand. Available: auto-mode, decision-coverage-plan, decision-coverage-verify, gap-analysis-plan-post, prohibition-enforcement, tdd-review-checkpoint, ui-plan-gate, ui-safety-gate, verify-schema-drift, verify-codebase-drift', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+    error('Unknown check subcommand. Available: auto-mode, decision-coverage-plan, decision-coverage-verify, gap-analysis-plan-post, predicate, prohibition-enforcement, tdd-review-checkpoint, ui-plan-gate, ui-safety-gate, verify-schema-drift, verify-codebase-drift', ERROR_REASON.SDK_UNKNOWN_COMMAND);
 }
 module.exports = {
     routeCheckCommand,
@@ -848,4 +955,7 @@ module.exports = {
     computeUiSafetyGate,
     cmdGapAnalysisPlanPost,
     cmdTddReviewCheckpoint,
+    cmdCheckPredicate,
+    buildPredicateDeps,
+    parsePredicateFlags,
 };

package/gsd-core/bin/lib/clusters.cjs

@@ -20,6 +20,7 @@ exports.CLUSTERS = void 0;
 exports.allClusteredSkills = allClusteredSkills;
 exports.CLUSTERS = Object.freeze({
     core_loop: Object.freeze([
+        'next',
         'new-project',
         'discuss-phase',
         'plan-phase',

package/gsd-core/bin/lib/commands.cjs

@@ -1302,7 +1302,8 @@ function cmdStats(cwd, format, raw) {
         const roadmapContent = extractCurrentMilestone(roadmapRaw, cwd);
         // Matches both plain numeric (Phase 1:) and milestone-prefixed (Phase 2-01:) headings.
         // Also tolerates optional [bracket-token] scope prefix on phase headings.
-        const headingPattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)\s*:\s*([^\n]+)/gi;
+        // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+        const headingPattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]*\))?\s*:\s*([^\n]+)/gi;
         let match;
         while ((match = headingPattern.exec(roadmapContent)) !== null) {
             const key = normalizePhaseName(match[1]);

package/gsd-core/bin/lib/config.cjs

@@ -531,7 +531,12 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
         parsedValue = true;
     else if (val === 'false')
         parsedValue = false;
-    else if (!isNaN(Number(val)) && val !== '')
+    // #1581: Number.isFinite (not !isNaN) so 'Infinity'/'-Infinity' are NOT
+    // coerced to non-finite numbers that JSON.stringify later renders as `null`
+    // (disk=null while the CLI echoed 'Infinity'). They fall through to the
+    // JSON branch (which rejects them) and stay strings, then per-key validators
+    // reject them with a non-zero exit.
+    else if (Number.isFinite(Number(val)) && val !== '')
         parsedValue = Number(val);
     else if (typeof val === 'string' && (val.startsWith('[') || val.startsWith('{'))) {
         try {
@@ -539,6 +544,11 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
         }
         catch { /* keep as string */ }
     }
+    // #1581: project_code is an identifier string — never number-coerce it. A
+    // leading-zero code like '007' must persist verbatim (not collapse to 7).
+    if (kp === 'project_code') {
+        parsedValue = val;
+    }
     const VALID_CONTEXT_VALUES = ['dev', 'research', 'review'];
     if (kp === 'context')
         assertEnumValue(parsedValue, val, VALID_CONTEXT_VALUES, 'context value');
@@ -551,6 +561,14 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
             error(`Invalid workflow.drift_threshold '${val}'. Must be a positive integer.`);
         }
     }
+    // #1581: context_window must be a finite positive integer. 'Infinity' is no
+    // longer number-coerced (see the parse block above) so it reaches here as a
+    // string and is rejected; '0', negatives, and non-integers are also rejected.
+    if (kp === 'context_window') {
+        if (typeof parsedValue !== 'number' || !Number.isFinite(parsedValue) || !Number.isInteger(parsedValue) || parsedValue < 1) {
+            error(`Invalid context_window '${val}'. Must be a positive integer (token count).`, ERROR_REASON.USAGE);
+        }
+    }
     // Post-planning gap checker (#2493)
     if (kp === 'workflow.post_planning_gaps') {
         if (typeof parsedValue !== 'boolean') {

package/gsd-core/bin/lib/core-utils.cjs

@@ -183,6 +183,46 @@ function extractCanonicalPlanId(filename) {
     }
     return base;
 }
+/**
+ * Count summaries that correspond to a real plan (#1988).
+ *
+ * A summary counts toward phase completion iff it pairs with an existing plan
+ * file. This excludes stray non-plan summaries — e.g. `30-FIX-CR02-SUMMARY.md`,
+ * `30-GAPCLOSURE-SUMMARY.md` — that inflate the raw `*-SUMMARY.md` count and
+ * silently flip a phase to Complete when plans are actually missing summaries.
+ *
+ * Pairing is layout-agnostic. For each plan, up to three candidate summary
+ * filenames are generated and any match suffices:
+ *   1. marker swap `PLAN`→`SUMMARY` on the basename — root padded
+ *      (`30-01-PLAN.md`↔`30-01-SUMMARY.md`), nested (`PLAN-01.md`↔
+ *      `SUMMARY-01.md`, incl. a `plans/` prefix), and bare (`PLAN.md`↔
+ *      `SUMMARY.md`);
+ *   2. `<stem>-SUMMARY.md` — bare (`PLAN.md`↔`PLAN-SUMMARY.md`) and legacy
+ *      (`14-PLAN-01.md`↔`14-PLAN-01-SUMMARY.md`);
+ *   3. extended `<n>-PLAN-<m>…`→`<n>-<m>-SUMMARY.md`
+ *      (`3-PLAN-01-setup.md`↔`3-01-SUMMARY.md`).
+ * The swap is applied to the basename only so a lowercase `plans/` dir prefix
+ * isn't corrupted to `SUMMARYs/…`.
+ */
+function countMatchedSummaries(planFiles, summaryFiles) {
+    const summarySet = new Set(summaryFiles);
+    let matched = 0;
+    for (const plan of planFiles) {
+        const slashIdx = plan.lastIndexOf('/');
+        const dir = slashIdx >= 0 ? plan.slice(0, slashIdx + 1) : '';
+        const base = (dir ? plan.slice(dir.length) : plan).replace(/\.md$/i, '');
+        const candidates = [
+            dir + base.replace(/PLAN/i, 'SUMMARY') + '.md',
+            dir + base + '-SUMMARY.md',
+        ];
+        const extended = base.match(/^(\d+)-PLAN-(\d+)/i);
+        if (extended)
+            candidates.push(dir + extended[1] + '-' + extended[2] + '-SUMMARY.md');
+        if (candidates.some((c) => summarySet.has(c)))
+            matched++;
+    }
+    return matched;
+}
 module.exports = {
     toPosixPath,
     detectSubRepos,
@@ -195,4 +235,5 @@ module.exports = {
     readSubdirectories,
     timeAgo,
     extractCanonicalPlanId,
+    countMatchedSummaries,
 };

package/gsd-core/bin/lib/external-job.cjs

@@ -0,0 +1,287 @@
+"use strict";
+/**
+ * external-job.cts — scheduler-adapter producer module for the async
+ * external-job contract (#1164 / #1105).
+ *
+ * The CORE loop CONSUMES manifests at `.planning/async-jobs/<job>.json`
+ * (#1165 — external_job_waiting half-state); this module is the Capability
+ * half that PRODUCES them. SLURM is the first backend; the design stays
+ * scheduler-pluggable via the `backend` field (planning-artifacts.md).
+ *
+ * Pure helpers (state map, build, validate, parsers) take no I/O; the writer
+ * takes injected `fs` and `clock` seams so tests drive it without touching disk
+ * or wall-clock time (CLAUDE.md clock-seam + injectable-deps conventions).
+ *
+ * Build: `src/*.cts` -> `gsd-core/bin/lib/*.cjs` (ADR-457 build-at-publish).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+// ─── Closed status enum (stability contract — Hyrum's Law) ────────────────────
+const MANIFEST_VERSION = '1.0';
+const MANIFEST_STATUS = [
+    'submitted',
+    'running',
+    'completed-unverified',
+    'failed',
+    'cancelled',
+    'timeout',
+];
+const NON_TERMINAL_STATUSES = ['submitted', 'running'];
+const TERMINAL_FAILURE_STATUSES = ['failed', 'cancelled', 'timeout'];
+// ─── SLURM state -> manifest status ───────────────────────────────────────────
+//
+// Source: SLURM job state codes (squeue/sacct State column). Producers for
+// other backends map their own states onto the closed enum above; this table
+// is SLURM-specific and lives behind the `backend: 'slurm'` field.
+const SLURM_STATE_MAP = {
+    PENDING: 'submitted',
+    CONFIGURING: 'submitted',
+    RUNNING: 'running',
+    COMPLETING: 'running',
+    COMPLETED: 'completed-unverified',
+    FAILED: 'failed',
+    CANCELLED: 'cancelled',
+    TIMEOUT: 'timeout',
+    OUT_OF_MEMORY: 'failed',
+    BOOT_FAIL: 'failed',
+    NODE_FAIL: 'failed',
+    PREEMPTED: 'failed',
+};
+/**
+ * Map a raw SLURM state string to the closed, scheduler-agnostic manifest
+ * status. Case-insensitive; trims whitespace; strips a trailing by-part
+ * ("CANCELLED by 1001" -> "CANCELLED"). Returns `null` for any unknown
+ * state so the caller can decide whether to surface or fail — never guesses
+ * (CLAUDE.md anti-guessing).
+ */
+function mapSlurmState(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const key = raw.trim().toUpperCase();
+    const head = key.split(/\s+/)[0];
+    if (head && Object.prototype.hasOwnProperty.call(SLURM_STATE_MAP, head)) {
+        return SLURM_STATE_MAP[head];
+    }
+    return null;
+}
+const REQUIRED_FIELDS = [
+    'plan_id',
+    'phase',
+    'job_id',
+    'backend',
+    'submit_command',
+    'status',
+    'expected_artifacts',
+    'verification_command',
+    'resume_command',
+];
+function assertString(v, key) {
+    if (typeof v !== 'string' || v.length === 0) {
+        throw new Error(`buildManifest: field "${key}" must be a non-empty string`);
+    }
+}
+const STATUS_LIST = MANIFEST_STATUS;
+/**
+ * Build a versioned, frozen manifest. Stamps `version` and `submitted_at`
+ * (via the injected clock seam) and normalises `terminal_details`:
+ * `null` unless the status is a terminal failure AND details were supplied.
+ * Throws on missing required fields or an out-of-enum status.
+ */
+function buildManifest(input, opts = {}) {
+    const inputRecord = input;
+    for (const key of REQUIRED_FIELDS) {
+        const v = inputRecord[key];
+        if (key === 'expected_artifacts') {
+            if (!Array.isArray(v) || v.length === 0 || !v.every((x) => typeof x === 'string')) {
+                throw new Error('buildManifest: field "expected_artifacts" must be a non-empty string[]');
+            }
+            continue;
+        }
+        assertString(v, key);
+    }
+    if (!STATUS_LIST.includes(input.status)) {
+        throw new Error(`buildManifest: field "status" must be one of ${MANIFEST_STATUS.join(', ')}`);
+    }
+    const clock = opts.clock ?? { nowIso: () => new Date().toISOString() };
+    const isTerminalFailure = TERMINAL_FAILURE_STATUSES.includes(input.status);
+    const terminal_details = isTerminalFailure && input.terminal_details ? input.terminal_details : null;
+    return Object.freeze({
+        version: MANIFEST_VERSION,
+        job_id: input.job_id,
+        plan_id: input.plan_id,
+        phase: input.phase,
+        backend: input.backend,
+        submit_command: input.submit_command,
+        status: input.status,
+        expected_artifacts: [...input.expected_artifacts],
+        verification_command: input.verification_command,
+        resume_command: input.resume_command,
+        submitted_at: clock.nowIso(),
+        terminal_details,
+    });
+}
+/**
+ * Producer-side schema validator — the mirror of the consumer trust boundary
+ * (planning-artifacts.md). Producers MUST emit a manifest this accepts; the
+ * core loop re-validates defensively on read.
+ */
+function validateManifest(value) {
+    if (!value || typeof value !== 'object') {
+        return { ok: false, errors: ['manifest must be an object'] };
+    }
+    const m = value;
+    const errors = [];
+    if (m.version !== MANIFEST_VERSION)
+        errors.push(`version must be "${MANIFEST_VERSION}"`);
+    for (const f of ['job_id', 'plan_id', 'phase', 'backend', 'submit_command', 'verification_command', 'resume_command', 'submitted_at']) {
+        if (typeof m[f] !== 'string' || m[f].length === 0) {
+            errors.push(`field "${f}" must be a non-empty string`);
+        }
+    }
+    if (typeof m.status !== 'string' || !STATUS_LIST.includes(m.status)) {
+        errors.push(`status must be one of ${MANIFEST_STATUS.join(', ')}`);
+    }
+    if (!Array.isArray(m.expected_artifacts) || !m.expected_artifacts.every((x) => typeof x === 'string')) {
+        errors.push('expected_artifacts must be a string[]');
+    }
+    if (m.terminal_details !== null && typeof m.terminal_details !== 'object') {
+        errors.push('terminal_details must be null or an object');
+    }
+    return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+/**
+ * Parse `sbatch --parsable` output. Accepts either a bare job id
+ * (`"12345"`) or the `"12345;clustername"` form. Rejects prose like
+ * `"Submitted batch job 12345"` (that is the non-parsable default format).
+ */
+function parseSbatchParsable(stdout) {
+    if (typeof stdout !== 'string')
+        return { ok: false, kind: 'non_string', raw: String(stdout) };
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return { ok: false, kind: 'empty', raw: stdout };
+    const head = trimmed.split(';')[0].split(/\s+/)[0];
+    if (!/^\d+$/.test(head))
+        return { ok: false, kind: 'not_numeric', raw: trimmed };
+    return { ok: true, job_id: head };
+}
+/**
+ * Parse a single `squeue` line of the form `"<jobid> <state>"`. Returns `null`
+ * for a header or any row that does not have at least two tokens.
+ */
+function parseSqueueLine(line) {
+    if (typeof line !== 'string')
+        return null;
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 2)
+        return null;
+    const [job_id, state] = parts;
+    if (!/^\d+$/.test(job_id))
+        return null;
+    return { job_id, state };
+}
+/**
+ * Parse a `sacct -P` row given as pre-split columns where index 0 is the job
+ * id and index 1 is the state. Returns `null` for malformed rows.
+ */
+function parseSacctRow(cols) {
+    if (cols.length < 2)
+        return null;
+    const job_id = cols[0];
+    const state = cols[1];
+    if (typeof job_id !== 'string' || typeof state !== 'string')
+        return null;
+    if (!/^\d+$/.test(job_id))
+        return null;
+    return { job_id, state };
+}
+/**
+ * Pure path projection: `.planning/async-jobs/<job_id>.json`.
+ */
+function manifestPath(planningDir, jobId) {
+    return node_path_1.default.join(planningDir, 'async-jobs', `${jobId}.json`);
+}
+function _isNonTerminal(status) {
+    return typeof status === 'string' && NON_TERMINAL_STATUSES.includes(status);
+}
+/**
+ * Write a manifest to `.planning/async-jobs/<job_id>.json`.
+ *
+ * Fail-closed rules (mirror of the consumer contract, planning-artifacts.md):
+ *  - If any existing manifest in the dir shares `plan_id` but has a different
+ *    `job_id` AND is non-terminal -> refuse (`duplicate_plan_id`); dispatching
+ *    again would duplicate the external job.
+ *  - If the target file exists but is not valid JSON -> refuse
+ *    (`malformed_existing`); never silently clobber.
+ *  - Same `job_id` for the same `plan_id` -> allowed (status progression).
+ *  - A prior job for the same `plan_id` that is already terminal -> allowed
+ *    (the duplicate guard only protects against re-dispatching live work).
+ */
+function writeManifest(manifest, planningDir, opts = {}) {
+    const fs = opts.fs ?? node_fs_1.default;
+    const dir = node_path_1.default.join(planningDir, 'async-jobs');
+    const target = manifestPath(planningDir, manifest.job_id);
+    let names;
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        names = fs.readdirSync(dir);
+    }
+    catch (e) {
+        return { ok: false, kind: 'io_error', message: e.message };
+    }
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        const p = node_path_1.default.join(dir, name);
+        let raw;
+        try {
+            raw = String(fs.readFileSync(p));
+        }
+        catch {
+            continue;
+        }
+        let existing;
+        try {
+            existing = JSON.parse(raw);
+        }
+        catch {
+            if (p === target) {
+                return { ok: false, kind: 'malformed_existing', message: `target manifest ${p} is not valid JSON` };
+            }
+            continue;
+        }
+        const samePlan = existing.plan_id === manifest.plan_id;
+        const sameJob = existing.job_id === manifest.job_id;
+        if (samePlan && !sameJob && _isNonTerminal(existing.status)) {
+            return {
+                ok: false,
+                kind: 'duplicate_plan_id',
+                message: `plan_id "${manifest.plan_id}" already has non-terminal job "${String(existing.job_id)}" at ${p}; dispatching again would duplicate the external job`,
+            };
+        }
+    }
+    try {
+        fs.writeFileSync(target, JSON.stringify(manifest, null, 2) + '\n');
+    }
+    catch (e) {
+        return { ok: false, kind: 'io_error', message: e.message };
+    }
+    return { ok: true, path: target };
+}
+module.exports = {
+    MANIFEST_VERSION,
+    MANIFEST_STATUS,
+    NON_TERMINAL_STATUSES,
+    TERMINAL_FAILURE_STATUSES,
+    mapSlurmState,
+    buildManifest,
+    validateManifest,
+    parseSbatchParsable,
+    parseSqueueLine,
+    parseSacctRow,
+    writeManifest,
+    manifestPath,
+};