smol-symphony 0.2.0 → 0.3.0

package/dist/src/core/doctor/checks.js

@@ -0,0 +1,303 @@
+// Functional core — `symphony doctor` preflight + startup banner + HTTP-port resolution.
+//
+// The orchestrator's startup path validates prerequisites FATALLY (`bailStartup`
+// exits on the first failure), so a first-time adopter fixes one cliff, re-runs,
+// hits the next, and so on. The doctor runs every probe NON-FATALLY and prints a
+// PASS/FAIL line per check with a one-line fix on failure, so the whole adoption
+// surface is legible in one pass.
+//
+// These helpers are PURE: each takes a raw probe OBSERVATION (gathered by the
+// shell — fs reads, port binds, image resolution) and returns a typed
+// {@link DoctorCheck} row, or renders the aligned report / startup banner. No IO,
+// no clock, no randomness — the only imports are type-only, from src/types.
+// ─── version helpers ─────────────────────────────────────────────────────────
+/**
+ * Extract a `[major, minor, patch]` tuple from a version-ish string. Reads the
+ * first up-to-three integer runs, defaulting missing components to 0, so it
+ * handles both a running version (`v23.6.0`) and an `engines` floor spec
+ * (`>=23.6.0`).
+ */
+function parseVersionTuple(s) {
+    const nums = (s.match(/\d+/g) ?? []).slice(0, 3).map((n) => parseInt(n, 10));
+    return [nums[0] ?? 0, nums[1] ?? 0, nums[2] ?? 0];
+}
+function compareVersionTuples(a, b) {
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] < b[i] ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * node >= the package `engines.node` floor. `current` is `process.version`
+ * (`v23.6.0`); `floor` is the raw `engines.node` spec (`>=23.6.0`) or null when
+ * it can't be read (then the check passes, reporting the running version only —
+ * the doctor should never fail on its own inability to read package.json).
+ */
+export function checkNodeVersion(current, floor) {
+    if (floor === null) {
+        return { key: 'node', pass: true, detail: `${current} (no engines floor declared)`, fix: '' };
+    }
+    const min = parseVersionTuple(floor);
+    const floorText = min.join('.');
+    const pass = compareVersionTuples(parseVersionTuple(current), min) >= 0;
+    return {
+        key: 'node',
+        pass,
+        detail: `${current} (engines floor >=${floorText})`,
+        fix: `install Node >=${floorText} (e.g. nvm install ${min[0]}) and re-run`,
+    };
+}
+// ─── workflow ────────────────────────────────────────────────────────────────
+/**
+ * WORKFLOW.yaml parses and declares the required state roles (active / terminal /
+ * holding). A parse failure is a single FAIL; a parsed-but-incomplete state map
+ * names exactly which roles are missing.
+ */
+export function checkWorkflow(obs) {
+    if (obs.parseError !== null) {
+        return {
+            key: 'workflow',
+            pass: false,
+            detail: `does not parse: ${obs.parseError}`,
+            fix: 'fix the YAML / states block in WORKFLOW.yaml',
+        };
+    }
+    const missing = [];
+    if (!obs.hasActive)
+        missing.push('active');
+    if (!obs.hasTerminal)
+        missing.push('terminal');
+    if (!obs.hasHolding)
+        missing.push('holding');
+    if (missing.length > 0) {
+        return {
+            key: 'workflow',
+            pass: false,
+            detail: `missing required state role(s): ${missing.join(', ')}`,
+            fix: `declare at least one state with role: ${missing.join(', role: ')}`,
+        };
+    }
+    return {
+        key: 'workflow',
+        pass: true,
+        detail: `${obs.stateNames.join(', ')} (active/terminal/holding present)`,
+        fix: '',
+    };
+}
+// ─── gondolin image ──────────────────────────────────────────────────────────
+/**
+ * A digest-shaped (content-addressed) image id printed by `npm run build:image`:
+ * a `sha256:`-prefixed or bare long hex run, or a UUID-shaped build id (the form
+ * Gondolin actually prints, e.g. `cb875342-03ef-56e0-9306-dde8628aa17d`).
+ */
+function looksLikeDigest(image) {
+    return (/^(sha256:)?[0-9a-f]{12,}$/i.test(image) ||
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(image));
+}
+/** A path-shaped image selector (an asset directory rather than a registry ref). */
+function looksLikePath(image) {
+    return image.includes('/') || image.startsWith('.') || image.startsWith('~');
+}
+/**
+ * `gondolin.image` is pinned (a digest / build id, an asset path, or an explicit
+ * `name:tag` — not a bare floating name Gondolin silently defaults to `:latest`)
+ * **and** resolvable. Pinned-ness is a pure property of the string; resolvability
+ * is probed against Gondolin's own resolver in the shell, because a pinned ref
+ * whose built image is not importable from the local store passes the shape test
+ * but still fails at VM bring-up. Both must hold for a PASS.
+ */
+export function checkGondolinImage(obs) {
+    const key = 'gondolin.image';
+    const fix = 'set gondolin.image (a build id, name:tag, or asset dir from `npm run build:image`) or gondolin.oci_image (an OCI ref auto-converted on first reconcile) in WORKFLOW.yaml';
+    // Mirror runtime precedence (`resolveImagePath`, src/core/runner/vm-plan.ts): the
+    // pre-converted `gondolin.image` escape hatch ALWAYS wins when set, so the doctor
+    // validates IT — and fails on an unpinned/unresolvable selector REGARDLESS of
+    // oci_image, because dispatch would boot that selector and fail. The soft
+    // oci_image auto-convert path applies only when `image` is null/empty.
+    if (obs.image && obs.image.length > 0) {
+        const image = obs.image;
+        // A bare floating name (no tag, not a build id, not a path) is unpinned — flag it
+        // before resolution, since Gondolin would silently resolve it to `:latest`.
+        if (!looksLikePath(image) && !looksLikeDigest(image) && !image.includes(':')) {
+            return {
+                key,
+                pass: false,
+                detail: `unpinned ref "${image}" (no tag or digest — floats)`,
+                fix: 'pin a name:tag or digest (`npm run build:image` prints one)',
+            };
+        }
+        // Pinned. Resolvability decides: probe Gondolin's resolver rather than trust the
+        // string shape, so a `does-not-exist:tag` that boots-fails is caught here.
+        const res = obs.resolution;
+        if (res === null || !res.resolved) {
+            return {
+                key,
+                pass: false,
+                detail: `pinned but unresolvable: ${res?.detail ?? 'not probed'}`,
+                fix: 'run `npm run build:image` (or import the asset dir) so the pinned image resolves locally',
+            };
+        }
+        return { key, pass: true, detail: `${image} (resolved: ${res.source ?? 'ok'})`, fix: '' };
+    }
+    // No escape-hatch `image` set — auto-convert path (issue 206): `gondolin.oci_image`.
+    // A not-yet-converted asset is a SOFT/info state (the reconcile loop builds it on
+    // first poll), NOT a hard failure — except when it can never be built (pullPolicy:
+    // never AND the OCI ref isn't in the local container store, so there's nothing to
+    // convert).
+    if (obs.oci) {
+        const { ref, converted, locallyResolvable, pullPolicy } = obs.oci;
+        if (converted) {
+            return { key, pass: true, detail: `oci_image ${ref} (converted asset cached)`, fix: '' };
+        }
+        if (pullPolicy === 'never' && !locallyResolvable) {
+            return {
+                key,
+                pass: false,
+                detail: `oci_image ${ref} not converted and not in the local container store (oci_pull_policy: never)`,
+                fix: 'pull the OCI image locally, or set gondolin.oci_pull_policy to if-not-present/always so reconcile can pull it',
+            };
+        }
+        return {
+            key,
+            pass: true,
+            detail: `oci_image ${ref} — not yet converted; will build on first reconcile (one-time)`,
+            fix: '',
+        };
+    }
+    // Managed prebuilt-image source (issue 224): neither `image` nor `oci_image` set, but
+    // `gondolin.managed_image` is active. PASS when the host arch has a published asset
+    // (cached, or fetchable on first reconcile); FAIL on an unsupported arch (no asset).
+    if (obs.managed) {
+        const { supported, arch, ref, cached } = obs.managed;
+        if (!supported) {
+            return {
+                key,
+                pass: false,
+                detail: `managed image source has no published asset for this host architecture${arch ? ` (${arch})` : ''}`,
+                fix: 'managed assets are published for x86_64 and arm64 only; on another arch set gondolin.image (a pre-built local asset) or gondolin.oci_image',
+            };
+        }
+        if (cached) {
+            return { key, pass: true, detail: `managed image ${ref} (fetched asset cached)`, fix: '' };
+        }
+        return {
+            key,
+            pass: true,
+            detail: `managed image ${ref} — not yet fetched; will download on first reconcile (one-time)`,
+            fix: '',
+        };
+    }
+    // Neither `image`, `oci_image`, nor a managed source configured.
+    return { key, pass: false, detail: 'not set', fix };
+}
+// ─── tracker root ────────────────────────────────────────────────────────────
+/** `tracker.root` exists, is a directory, and is writable by symphony. */
+export function checkTrackerRoot(obs) {
+    const key = 'tracker.root';
+    if (!obs.root) {
+        return { key, pass: false, detail: 'not set', fix: 'set tracker.root in WORKFLOW.yaml' };
+    }
+    if (!obs.exists) {
+        return { key, pass: false, detail: `not found: ${obs.root}`, fix: `mkdir -p ${obs.root}` };
+    }
+    if (!obs.isDirectory) {
+        return {
+            key,
+            pass: false,
+            detail: `not a directory: ${obs.root}`,
+            fix: `remove the file at ${obs.root} and create a directory there`,
+        };
+    }
+    if (!obs.writable) {
+        return {
+            key,
+            pass: false,
+            detail: `not writable: ${obs.root}`,
+            fix: `grant write permission on ${obs.root} (chmod/chown so symphony can write issue files)`,
+        };
+    }
+    return { key, pass: true, detail: `${obs.root} (writable)`, fix: '' };
+}
+// ─── dashboard port ──────────────────────────────────────────────────────────
+/** The dashboard port is free / bindable. An ephemeral (0) port is always free. */
+export function checkDashboardPort(obs) {
+    const key = 'dashboard.port';
+    if (obs.port === 0) {
+        return { key, pass: true, detail: 'ephemeral (kernel-assigned — always free)', fix: '' };
+    }
+    if (obs.bindable) {
+        return { key, pass: true, detail: `${obs.port} (bindable)`, fix: '' };
+    }
+    return {
+        key,
+        pass: false,
+        detail: `${obs.port} not bindable${obs.reason ? ` (${obs.reason})` : ''}`,
+        fix: 'free the port or set a different server.port / --port',
+    };
+}
+// ─── report ──────────────────────────────────────────────────────────────────
+/** True iff every doctor check passed. The doctor exits 0 iff this is true. */
+export function doctorReportPassed(checks) {
+    return checks.every((c) => c.pass);
+}
+/**
+ * Render the doctor report as aligned, color-free columns matching symphony's
+ * quiet-workshop banner voice: a PASS/FAIL status, the padded key, and the
+ * detail, with an indented `fix:` line under each failure.
+ */
+export function formatDoctorReport(checks) {
+    const keyWidth = checks.reduce((w, c) => Math.max(w, c.key.length), 0);
+    const lines = ['symphony doctor', ''];
+    for (const c of checks) {
+        lines.push(`${c.pass ? 'PASS' : 'FAIL'}  ${c.key.padEnd(keyWidth)}  ${c.detail}`);
+        if (!c.pass && c.fix)
+            lines.push(`      fix: ${c.fix}`);
+    }
+    const pass = checks.filter((c) => c.pass).length;
+    lines.push('', `${checks.length} checks · ${pass} pass · ${checks.length - pass} fail`);
+    return lines.join('\n') + '\n';
+}
+// ─── http port + startup banner ──────────────────────────────────────────────
+/**
+ * Resolve the HTTP port: CLI `--port` wins, then `server.port`, otherwise 0
+ * (ephemeral). Returning 0 when neither is set lets the kernel pick a free port,
+ * so symphony "just works" with no config and two concurrent instances never
+ * collide; an explicit `--port`/`server.port` still pins a fixed port.
+ */
+export function resolveHttpPort(cliPort, configPort) {
+    return cliPort ?? configPort ?? 0;
+}
+/**
+ * Map a wildcard bind address to a clickable loopback host for the dashboard URL
+ * line — `0.0.0.0`/`::` aren't dialable, `localhost` is.
+ */
+function displayHost(host) {
+    return host === '0.0.0.0' || host === '::' ? 'localhost' : host;
+}
+/**
+ * Build the human-facing startup summary. Defaulting `server.port` to an
+ * ephemeral port means the operator can't know the bound port from config alone,
+ * so the banner reports the *actually-bound* HTTP port (`boundPort`) and the
+ * dashboard URL. Kept pure so it is unit-testable.
+ *
+ * Names where the operator's three orientation points live: the dashboard URL,
+ * the resolved log file (the env override path when SYMPHONY_LOG_FILE is set,
+ * else <logs.root>/symphony.log; `(disabled)` when file logging is off), and the
+ * tracker + workspace roots — so nobody has to guess where state lives once the
+ * roots move out of the repo. Kept pure so the content is unit-testable without IO.
+ */
+export function formatStartupBanner(opts) {
+    const lines = [
+        `symphony ${opts.version}`,
+        `  workflow      ${opts.workflowPath}`,
+        `  tracker root  ${opts.trackerRoot ?? '<unset>'}`,
+        `  workspace     ${opts.workspaceRoot ?? '<unset>'}`,
+        `  dashboard     http://${displayHost(opts.host)}:${opts.boundPort}/`,
+        `  log file      ${opts.logFile ?? '(disabled)'}`,
+        `  adapter       ${opts.adapter}`,
+        `  image         ${opts.image ?? '<unset>'}`,
+    ];
+    return lines.join('\n') + '\n';
+}
+//# sourceMappingURL=checks.js.map

package/dist/src/core/doctor/checks.js.map

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

package/dist/src/core/git/result.js

@@ -0,0 +1,107 @@
+// FCIS rewrite — pure classifiers for git push results + gh PR-create output.
+//
+// These are the two pure DECISIONS the IO effect-interpreter used to run inline:
+//   • classifyPushResult — whether a `git push` exited clean and, on failure,
+//     whether the failure is a non-fast-forward rejection (the keystone of the
+//     push_branch NFF → force-with-lease recovery; actions-runner reads the flag).
+//   • parsePrNumberFromUrl — extract the PR number + canonical URL from the
+//     `gh pr create` stdout (the trailing line is the created PR URL).
+//
+// Both were stranded in `shell/effect-interpreter-families.ts` (the regex twin of
+// `runlog/summary.ts:PR_URL_RE`). Pulling them into core means the push-recovery
+// and PR-number decisions are unit-tested once and can't drift from the regexes
+// the rest of core already uses.
+//
+// HARD CONSTRAINTS (gate-enforced): 100% SYNCHRONOUS, no IO/node/clock/random,
+// imports ONLY from src/types/**.
+/**
+ * A non-fast-forward push rejection. Matched against the combined stdout+stderr
+ * of the `git push`. The alternatives cover git's TRUE non-fast-forward phrasings:
+ *   • `! [rejected] … (non-fast-forward)` / `(non-fast-forward)`
+ *   • `! [rejected] … (fetch first)` / `fetch first`
+ *   • `Updates were rejected because the tip … is behind …`
+ *
+ * It deliberately does NOT match the bare word `rejected`. git emits
+ * `! [remote rejected] … (push declined …)` for SERVER-SIDE declines —
+ * branch-protection rules, pre-receive hooks, or a PAT lacking `workflow` scope
+ * (the 227 case: GitHub refusing a `.github/workflows/` edit). Those are NOT
+ * non-fast-forwards and are NOT recoverable by force-with-lease. The old bare
+ * `rejected` alternative false-positived them into the NFF fetch→force recovery,
+ * whose fetch then died `couldn't find remote ref` (the push had never landed) and
+ * MASKED the real decline message the operator needs (issue 227). A declined push
+ * now fails fast with its own stderr instead.
+ */
+const NON_FAST_FORWARD_RE = /non-fast-forward|fetch first|Updates were rejected/i;
+/** Canonical `…/pull/<n>` URL → number capture (shared shape with runlog PR_URL_RE). */
+const PR_URL_RE = /\/pull\/(\d+)/;
+/**
+ * A SERVER-SIDE push decline caused by the push credential lacking the GitHub
+ * `workflow` scope / fine-grained Workflows:write permission. GitHub refuses any
+ * push whose diff creates or updates a file under `.github/workflows/` unless the
+ * token carries that scope — the shared fine-grained PAT symphony's in-VM agent
+ * pushes with (`gh auth setup-git`) is INTENTIONALLY not granted it, so such a
+ * push is always declined and can only be landed by a manual SSH push (issue 235).
+ *
+ * git surfaces this as `! [remote rejected] … (refusing to allow a Personal Access
+ * Token to create or update workflow `.github/workflows/…` without `workflow`
+ * scope)`. The two alternatives catch the "refusing to allow … workflow" decline
+ * and the trailing "… without `workflow` scope" clause. This is DISTINCT from a
+ * non-fast-forward (see NON_FAST_FORWARD_RE): a scope decline is never recoverable
+ * by force-with-lease.
+ */
+const WORKFLOW_SCOPE_DECLINE_RE = /refusing to allow[\s\S]*?\bworkflow\b|\bworkflow\b[^\n]{0,20}\bscope\b/i;
+/** The actionable prefix a workflow-scope decline is rewritten under (also the
+ *  idempotency guard so {@link describeHandoffFailure} never double-wraps). */
+const MANUAL_PUSH_PREFIX = 'manual SSH push required';
+/**
+ * True when a push failure reason is the GitHub workflow-scope server-side
+ * decline (a `.github/workflows/` edit pushed by the Workflows:write-less PAT).
+ */
+export function isWorkflowScopeDecline(reason) {
+    return WORKFLOW_SCOPE_DECLINE_RE.test(reason);
+}
+/**
+ * Rewrite a failed-handoff reason into an operator-actionable one. A workflow-scope
+ * decline (see {@link isWorkflowScopeDecline}) becomes a "manual SSH push required"
+ * message naming the cause + the fix, keeping the original git error appended so
+ * the raw stderr stays inspectable; every other reason passes through unchanged.
+ * Idempotent — an already-rewritten reason is returned as-is.
+ */
+export function describeHandoffFailure(reason) {
+    if (reason.startsWith(MANUAL_PUSH_PREFIX))
+        return reason;
+    if (isWorkflowScopeDecline(reason)) {
+        return (`${MANUAL_PUSH_PREFIX} — the shared fine-grained PAT is not granted ` +
+            `Workflows:write, so GitHub server-side-declines any push touching ` +
+            `.github/workflows/. Land this branch with a manual SSH push (the token ` +
+            `never enters the VM). Original git error: ${reason}`);
+    }
+    return reason;
+}
+/**
+ * Classify a `git push` RunResultData: clean iff `exit_code === 0`; on a non-zero
+ * exit, flag a non-fast-forward rejection from the combined output. A clean push
+ * is never reported as non-fast-forward. Pure mirror of the inline interpreter
+ * `pushStatus` decision. (`clean` = exited 0; `nonFastForward` = recoverable via
+ * force-with-lease.)
+ */
+export function classifyPushResult(result) {
+    const clean = result.exit_code === 0;
+    return {
+        clean,
+        nonFastForward: !clean && NON_FAST_FORWARD_RE.test(`${result.stdout}\n${result.stderr}`),
+    };
+}
+/**
+ * Parse the `gh pr create` stdout into the created PR's number + URL. `gh` prints
+ * the PR URL as the last non-empty line; we scan it for the `/pull/<n>` segment.
+ * Returns `{ number: 0, url }` when no PR number can be parsed (the original's
+ * behavior — a created-but-unparseable URL still surfaces the URL, number 0), and
+ * `{ number: 0, url: '' }` when stdout carried no URL at all.
+ */
+export function parsePrNumberFromUrl(stdout) {
+    const url = stdout.trim().split('\n').pop() ?? '';
+    const m = PR_URL_RE.exec(url);
+    return { number: m ? Number(m[1]) : 0, url };
+}
+//# sourceMappingURL=result.js.map

package/dist/src/core/git/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../../../src/core/git/result.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,EAAE;AACF,iFAAiF;AACjF,8EAA8E;AAC9E,+EAA+E;AAC/E,mFAAmF;AACnF,4EAA4E;AAC5E,uEAAuE;AACvE,EAAE;AACF,kFAAkF;AAClF,iFAAiF;AACjF,gFAAgF;AAChF,iCAAiC;AACjC,EAAE;AACF,+EAA+E;AAC/E,kCAAkC;AAIlC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,mBAAmB,GAAG,qDAAqD,CAAC;AAElF,wFAAwF;AACxF,MAAM,SAAS,GAAG,eAAe,CAAC;AAElC;;;;;;;;;;;;;;GAcG;AACH,MAAM,yBAAyB,GAC7B,yEAAyE,CAAC;AAE5E;+EAC+E;AAC/E,MAAM,kBAAkB,GAAG,0BAA0B,CAAC;AAEtD;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAc;IACnD,OAAO,yBAAyB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAc;IACnD,IAAI,MAAM,CAAC,UAAU,CAAC,kBAAkB,CAAC;QAAE,OAAO,MAAM,CAAC;IACzD,IAAI,sBAAsB,CAAC,MAAM,CAAC,EAAE,CAAC;QACnC,OAAO,CACL,GAAG,kBAAkB,gDAAgD;YACrE,oEAAoE;YACpE,yEAAyE;YACzE,6CAA6C,MAAM,EAAE,CACtD,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAqB;IACtD,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,KAAK,CAAC,CAAC;IACrC,OAAO;QACL,KAAK;QACL,cAAc,EAAE,CAAC,KAAK,IAAI,mBAAmB,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;KACzF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;IAClD,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC;AAC/C,CAAC"}

package/dist/src/core/http/decisions.js

@@ -0,0 +1,225 @@
+// FCIS rewrite — PURE HTTP decision layer.
+//
+// Ported faithfully from the original (read-only reference):
+//   src/http-handlers.ts:decideCreateIssue (+ decideTriageTransition, now
+//     generalized into decideMoveTransition — the operator move; issue 126)
+//   src/orchestrator-decisions.ts:buildIssueDetailDto (+ its two private section builders)
+//
+// Each function takes already-parsed inputs and returns a decision (validated
+// command + HTTP status, or a DTO) WITHOUT touching IncomingMessage /
+// ServerResponse / the filesystem / the wall clock. The HTTP shell stays a thin
+// dispatcher: parse → decide (here) → emit.
+//
+// 100% synchronous. No async/await/Promise, no IO, no node: imports, no
+// process/fetch, no wall-clock or randomness. Imports ONLY from src/types.
+//
+// NOTE on dates: buildIssueDetailDto formats `retry.due_at_ms` into ISO-8601 via
+// the local pure `epochMsToIso` helper (NOT the `Date` constructor — that is
+// lint-banned in core since it can't tell a deterministic ms-conversion from a
+// wall-clock read). The conversion is a deterministic function of its argument.
+import { resolveDeclaredName, isInFlowTransition } from '../state-resolve.js';
+// ─── POST /api/v1/issues body validation ────────────────────────────────────
+// `identifier` and `state` are optional: identifier is derived from the title when
+// omitted (by the shell), state defaults to the first declared active state
+// (typically `Todo`). State is restricted to declared non-terminal states (active
+// or holding) so the kanban's `+ new issue` affordance can target Triage and so
+// terminal states stay closed to direct creation. Values containing path
+// separators / `..` are rejected by the set lookup so the request cannot escape
+// the tracker root via path.join.
+export function decideCreateIssue(body, states) {
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+        return { ok: false, status: 400, code: 'bad_request', message: 'body must be a JSON object' };
+    }
+    const b = body;
+    const identifier = typeof b.identifier === 'string' ? b.identifier.trim() : '';
+    const title = typeof b.title === 'string' ? b.title.trim() : '';
+    const stateInput = typeof b.state === 'string' ? b.state.trim() : '';
+    if (!title) {
+        return { ok: false, status: 400, code: 'bad_request', message: 'title is required' };
+    }
+    const firstActiveName = states.find((s) => s.role === 'active')?.name ?? '';
+    const state = stateInput || firstActiveName;
+    if (!state) {
+        return {
+            ok: false,
+            status: 400,
+            code: 'bad_request',
+            message: 'state is required (no active states declared to default to)',
+        };
+    }
+    const allowedNames = states.filter((s) => s.role !== 'terminal').map((s) => s.name);
+    const allowedStates = new Set(allowedNames);
+    if (!allowedStates.has(state)) {
+        return {
+            ok: false,
+            status: 400,
+            code: 'bad_request',
+            message: `state must be one of: ${allowedNames.join(', ') || '<none configured>'}`,
+        };
+    }
+    const description = typeof b.description === 'string' ? b.description : undefined;
+    const priority = typeof b.priority === 'number' && Number.isFinite(b.priority) ? b.priority : null;
+    const labels = Array.isArray(b.labels)
+        ? b.labels.filter((x) => typeof x === 'string')
+        : [];
+    const blocked_by = Array.isArray(b.blocked_by)
+        ? b.blocked_by.filter((x) => typeof x === 'string')
+        : [];
+    return { ok: true, identifier, title, state, description, priority, labels, blocked_by };
+}
+// ─── Operator move transition (POST /api/v1/issues/<id>/move) ─────────────────
+// Replaces the old fixed approve/discard `decideTriageTransition` (issue 126):
+// the operator (the human-in-the-loop) can move ANY issue to ANY declared state.
+// Approve becomes "move to <first active>", discard "move to <terminal>" — both
+// ordinary in-flow moves with no separate code path.
+//
+// The decider validates the body's target `state` (declared, canonicalized),
+// then:
+//   - 400 when the target is blank or not a declared state;
+//   - 409 `from_state_mismatch` when the body's claimed `from_state` does not
+//     match the file's ACTUAL on-disk directory (`actualFromState`, resolved by
+//     the shell) — hardens a hand-crafted POST and kills the move-by-id
+//     ambiguity (the file moved out from under the operator);
+//   - otherwise ok, carrying the canonical target, the actual from-state (so the
+//     shell moves the RIGHT file), and the soft `offFlow` warning flag.
+//
+// `offFlow` is keyed on the SAME graph the agent path enforces: a move is
+// off-flow when the actual from-state's `allowed_transitions` is non-null and
+// does not include the target (the exact condition `decideTransition` rejects on
+// — but here the operator move still applies; the flag is observability only).
+// A null list, or an undeclared from-state, is in-flow (the open default); a
+// self-transition is always in-flow. The shared predicate is
+// `isInFlowTransition` (src/core/state-resolve.ts).
+export function decideMoveTransition(body, states, actualFromState) {
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+        return { ok: false, status: 400, code: 'bad_request', message: 'body must be a JSON object' };
+    }
+    const b = body;
+    const target = typeof b.state === 'string' ? b.state.trim() : '';
+    const claimedFrom = typeof b.from_state === 'string' ? b.from_state.trim() : '';
+    if (!target) {
+        return { ok: false, status: 400, code: 'bad_request', message: 'state is required' };
+    }
+    const order = states.map((s) => s.name);
+    const canonicalTarget = resolveDeclaredName(order, target);
+    if (canonicalTarget === null) {
+        return {
+            ok: false,
+            status: 400,
+            code: 'bad_request',
+            message: `state must be one of: ${order.join(', ') || '<none configured>'}`,
+        };
+    }
+    // Claimed from-state must match the file's actual directory (case-insensitive,
+    // matching the rest of symphony). A mismatch means the operator's view is stale
+    // or the POST was hand-crafted — refuse rather than move the wrong file.
+    if (claimedFrom && claimedFrom.toLowerCase() !== actualFromState.toLowerCase()) {
+        return {
+            ok: false,
+            status: 409,
+            code: 'from_state_mismatch',
+            message: `issue is in "${actualFromState}", not "${claimedFrom}"`,
+        };
+    }
+    // Off-flow flag keyed on the ACTUAL from-state's allowed_transitions. An
+    // undeclared from-state (an orphan directory) canonicalizes to null ⇒ open ⇒
+    // in-flow, matching the agent path's "skip the gate when from is undeclared".
+    const canonicalFrom = resolveDeclaredName(order, actualFromState);
+    const allowed = canonicalFrom !== null
+        ? states.find((s) => s.name === canonicalFrom)?.allowed_transitions ?? null
+        : null;
+    const offFlow = !isInFlowTransition(allowed, canonicalFrom ?? actualFromState, canonicalTarget);
+    return { ok: true, toState: canonicalTarget, fromState: actualFromState, offFlow };
+}
+// ─── Issue-detail DTO (GET /api/v1/<identifier>) ──────────────────────────────
+// Pure with respect to the views supplied by the shell (the running/retry scans
+// are impure and live in the shell). Returns null when neither a running nor a
+// retrying entry matches the identifier.
+/**
+ * Build the issue-detail DTO served by `GET /api/v1/<identifier>`. Pure with
+ * respect to the views supplied by the shell. Returns null when neither a
+ * running nor a retrying entry matches.
+ */
+export function buildIssueDetailDto(identifier, entry, retry) {
+    if (!entry && !retry)
+        return null;
+    // A pending `continuation` is a clean post-transition handoff (e.g.
+    // Review → Todo), not a failure — surface it as a calm `resuming` state so an
+    // API client can tell it apart from a stuck `failure`-backoff `retrying`. (The
+    // dashboard pill collapses a continuation into `running` under the Three-Pill
+    // Rule — issue 154 — since a live-updating list would otherwise flash. This
+    // point-query DTO never flashes, so it keeps the finer-grained `resuming`
+    // distinction.)
+    const status = entry
+        ? 'running'
+        : retry?.kind === 'continuation'
+            ? 'resuming'
+            : 'retrying';
+    return {
+        issue_identifier: identifier,
+        issue_id: entry?.issue_id ?? retry?.issue_id ?? null,
+        status,
+        workspace: entry ? { path: entry.workspace_path } : null,
+        attempts: { current_retry_attempt: retry?.attempt ?? null },
+        running: entry ? buildIssueDetailRunningSection(entry) : null,
+        retry: retry ? buildIssueDetailRetrySection(retry) : null,
+        recent_events: entry?.recent_events ?? [],
+        last_error: entry?.last_error ?? retry?.error ?? null,
+        tracked: {},
+    };
+}
+function buildIssueDetailRunningSection(entry) {
+    return {
+        session_id: entry.session_id,
+        turn_count: entry.turn_count,
+        state: entry.state,
+        started_at: entry.started_at,
+        last_event: entry.last_event,
+        last_message: entry.last_message,
+        last_event_at: entry.last_event_at,
+        tokens: {
+            input_tokens: entry.input_tokens,
+            output_tokens: entry.output_tokens,
+            total_tokens: entry.total_tokens,
+        },
+    };
+}
+function buildIssueDetailRetrySection(retry) {
+    return {
+        attempt: retry.attempt,
+        due_at: epochMsToIso(retry.due_at_ms),
+        error: retry.error,
+        kind: retry.kind,
+    };
+}
+// Pure epoch-ms → ISO-8601 UTC string, byte-for-byte identical to
+// `new Date(ms).toISOString()` but WITHOUT the `Date` constructor (which the
+// core-purity lint bans, as it cannot tell a deterministic ms-conversion from a
+// wall-clock read). Civil-date split uses Howard Hinnant's days→y/m/d algorithm.
+function epochMsToIso(ms) {
+    const totalMs = Math.trunc(ms);
+    const days = Math.floor(totalMs / 86_400_000);
+    const ofDayMs = totalMs - days * 86_400_000; // 0..86_399_999
+    const msPart = ofDayMs % 1000;
+    const secs = (ofDayMs - msPart) / 1000;
+    const ss = secs % 60;
+    const mins = (secs - ss) / 60;
+    const mm = mins % 60;
+    const hh = (mins - mm) / 60;
+    // days since 1970-01-01 → year/month/day (era-based, Gregorian)
+    const z = days + 719_468;
+    const era = Math.floor(z / 146_097);
+    const doe = z - era * 146_097;
+    const yoe = Math.floor((doe - Math.floor(doe / 1460) + Math.floor(doe / 36_524) - Math.floor(doe / 146_096)) / 365);
+    const doy = doe - (365 * yoe + Math.floor(yoe / 4) - Math.floor(yoe / 100));
+    const mp = Math.floor((5 * doy + 2) / 153);
+    const d = doy - Math.floor((153 * mp + 2) / 5) + 1;
+    const m = mp < 10 ? mp + 3 : mp - 9;
+    const year = yoe + era * 400 + (m <= 2 ? 1 : 0);
+    const p2 = (n) => String(n).padStart(2, '0');
+    const yStr = year < 0 || year > 9999
+        ? (year < 0 ? '-' : '+') + String(Math.abs(year)).padStart(6, '0')
+        : String(year).padStart(4, '0');
+    return `${yStr}-${p2(m)}-${p2(d)}T${p2(hh)}:${p2(mm)}:${p2(ss)}.${String(msPart).padStart(3, '0')}Z`;
+}
+//# sourceMappingURL=decisions.js.map