diff --git a/package.json b/package.json index e967e5d..5c89cd5 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,7 @@ "adlc-skills-cli": "bin/adlc-skills-cli.mjs" }, "scripts": { - "test": "node --test && node tests/e2e-node-gate.mjs --skip-agent", + "test": "node --test && node tests/e2e-node-gate.mjs --skip-agent && node tests/e2e-cross-session.mjs", "test:evals": "node --test evals/opencode-session-end/tests/test_check_session_end.mjs", "test:all": "npm test && npm run test:evals", "prepublishOnly": "npm test", diff --git a/src/commands/workflow.mjs b/src/commands/workflow.mjs index a418f0f..1e0df31 100644 --- a/src/commands/workflow.mjs +++ b/src/commands/workflow.mjs @@ -26,6 +26,7 @@ import { stateShow, } from "../workflow/state.mjs"; import { parkRun, restoreRun } from "../workflow/refs.mjs"; +import { buildBoardIndex } from "../workflow/board.mjs"; import { printWorkflowHelp } from "../help.mjs"; import { classifyWorkflowStatus } from "../exit-codes.mjs"; import { StepStatus } from "../workflow/base.mjs"; @@ -36,6 +37,7 @@ import { success, failure, note, + warn, panel, table, keyValue, @@ -69,6 +71,8 @@ export async function cmdWorkflow(args, flags, rawArgv) { return cmdWorkflowPark(rest, rawArgv); case "restore": return cmdWorkflowRestore(rest, rawArgv); + case "board": + return cmdWorkflowBoard(rest, rawArgv); case "search": return cmdWorkflowSearch(rest, rawArgv); case "add": @@ -508,6 +512,91 @@ function valuedFlagValues(rawArgv) { return values; } +// ── board (ADR-476 pane of glass v1) ────────────────────────────────────── + +// One view over every factory run: local run dirs + remote +// refs/factory-runs/* (ADR-475/490). The index is derived fresh every call +// and never persisted (ADR-325 stateless aggregation; ADR-490 disposable +// index). Degrades per source: an unreachable remote keeps the board +// local-only (warning, exit 0); unreadable refs are skipped and counted. +async function cmdWorkflowBoard(rest, rawArgv) { + const remote = extractFlagValue(rawArgv, "remote") ?? "origin"; + let board; + try { + board = buildBoardIndex({ projectRoot: process.cwd(), remote }); + } catch (exc) { + error(exc.message); + return 1; + } + + // Machine contract for the future web dashboard (ADR-325 SPA): stdout is + // the JSON index and nothing else; remote errors ride inside the doc. + if (hasFlag(rawArgv, "format") && extractFlagValue(rawArgv, "format") === "json") { + out( + JSON.stringify( + { runs: board.runs, remoteError: board.remoteError, skippedRemote: board.skippedRemote }, + null, + 2, + ), + ); + return 0; + } + + if (board.remoteError !== null) { + warn( + combine( + style(sym.warn, "yellow"), + ` remote "${remote}" unreachable — showing local runs only (`, + tint(board.remoteError, "gray"), + ")", + ), + ); + } + + if (board.runs.length === 0) { + out(""); + note(`No factory runs found (local ${RUNS_DIR} + ${remote}:refs/factory-runs/*)`); + if (board.skippedRemote > 0) { + note(`Skipped ${board.skippedRemote} unreadable remote ref(s)`); + } + out(""); + return 0; + } + + out(""); + out( + table({ + title: `Factory board — ${board.runs.length} run${board.runs.length === 1 ? "" : "s"} (${remote})`, + columns: [ + { header: "Run ID", style: ACCENT }, + { header: "Source" }, + { header: "Status" }, + { header: "Current", optional: true }, + { header: "Outcome", optional: true }, + { header: "Retention", optional: true }, + { header: "Issue", optional: true }, + { header: "Updated", optional: true }, + ], + rows: board.runs.map((r) => [ + r.run_id, + r.source, + statusCell(r.status ?? "unknown"), + r.current_step_id ?? "", + r.outcome ?? "", + r.retention_class ?? "", + r.issue_ref ?? "", + r.updated_at ?? "", + ]), + }), + ); + if (board.skippedRemote > 0) { + out(""); + note(`Skipped ${board.skippedRemote} unreadable remote ref(s) — no parsable state.json`); + } + out(""); + return 0; +} + // ── status ─────────────────────────────────────────────────────────────── async function cmdWorkflowStatus(rest) { diff --git a/src/dispatch.mjs b/src/dispatch.mjs index c87e4c6..6bf92c4 100644 --- a/src/dispatch.mjs +++ b/src/dispatch.mjs @@ -235,6 +235,7 @@ async function runNewTree({ command, args, flags }, argv) { case "state": case "park": case "restore": + case "board": case "search": case "add": case "list": diff --git a/src/help.mjs b/src/help.mjs index e91e386..c95d785 100644 --- a/src/help.mjs +++ b/src/help.mjs @@ -77,6 +77,7 @@ export function printCliHelp() { ["workflow resume ", "Resume a paused/failed run (optionally with --input)"], ["workflow park ", "Save a gate-paused run + thread handle to the remote run ref"], ["workflow restore ", "Restore a parked run from the remote run ref"], + ["workflow board [--remote ]", "Pane of glass: local runs + remote refs/factory-runs/* (--format json)"], ["workflow status [run_id]", "List runs / show one run's step states"], ["workflow validate ", "Validate a workflow definition (--headless checks gate verdicts)"], ["workflow search [query]", "Search available workflows in catalog"], @@ -418,6 +419,7 @@ export function printWorkflowHelp() { ["resume ", "Resume a paused/failed run (gates re-prompt)"], ["park ", "Save a gate-paused run (+ --handle-file ) to refs/factory-runs/ on --remote (default origin)"], ["restore ", "Fetch refs/factory-runs/ from --remote into .adlc/workflows/runs// (refuses an existing run dir or a different --issue-ref)"], + ["board [--remote ]", "Pane of glass (ADR-476): all factory runs — local run dirs + remote refs/factory-runs/* fetched namespaced; --format json for machines; degrades to local-only on unreachable remote"], ["status [run_id]", "List all runs / show one run's step states"], ["validate ", "Validate a workflow definition"], ["search [query]", "Search available workflows in catalog"], diff --git a/src/workflow/board.mjs b/src/workflow/board.mjs new file mode 100644 index 0000000..c4dc523 --- /dev/null +++ b/src/workflow/board.mjs @@ -0,0 +1,184 @@ +// Factory board — pane of glass v1 (ADR-476) over local run dirs and remote +// refs/factory-runs/* (ADR-475/490). The index is derived and disposable: +// computed fresh on every invocation, nothing persisted (ADR-325 stateless +// aggregation; ADR-490 keeps refs authoritative and the index replaceable). +// +// Remote reads fetch into refs/remotes//factory-runs/* — never the +// local refs/factory-runs/* a live machine may be pushing. Depth-1 + prune +// keeps the fetch light and drops refs deleted on the remote. + +import { existsSync, readFileSync, readdirSync, statSync } from "node:fs"; +import { join } from "node:path"; +import { spawnSync } from "node:child_process"; +import { checkRemote } from "./refs.mjs"; + +const RUNS_DIR = ".adlc/workflows/runs"; +const RUN_REF_PREFIX = "refs/factory-runs/"; +const REMOTE_REF_PREFIX = "refs/remotes/"; + +function git(projectRoot, args) { + return spawnSync("git", args, { + cwd: projectRoot, + encoding: "utf-8", + maxBuffer: 16 * 1024 * 1024, + }); +} + +function gitText(projectRoot, args) { + const r = git(projectRoot, args); + if (r.error || r.status !== 0) return null; + return String(r.stdout ?? ""); +} + +// ── local source ────────────────────────────────────────────────────────── + +function readJsonIfPresent(path) { + if (!existsSync(path)) return null; + try { + return JSON.parse(readFileSync(path, "utf-8")); + } catch { + return null; + } +} + +function localRuns(projectRoot) { + const runsDir = join(projectRoot, RUNS_DIR); + const rows = []; + if (!existsSync(runsDir)) return rows; + for (const entry of readdirSync(runsDir).sort()) { + const runDir = join(runsDir, entry); + try { + if (!statSync(runDir).isDirectory()) continue; + } catch { + continue; + } + const state = readJsonIfPresent(join(runDir, "state.json")); + if (!state || typeof state.run_id !== "string") continue; + const manifest = readJsonIfPresent(join(runDir, "trace", "manifest.json")); + rows.push({ state, manifest }); + } + return rows; +} + +// ── remote source ───────────────────────────────────────────────────────── + +// Fetch every remote run ref into the namespaced remotes area. Returns +// { error } on failure — the board degrades to local-only (ADR-325). +function fetchRemoteRefs(projectRoot, remote) { + const refspec = `+${RUN_REF_PREFIX}*:${REMOTE_REF_PREFIX}${remote}/factory-runs/*`; + const r = git(projectRoot, ["fetch", "--quiet", "--prune", "--depth", "1", remote, refspec]); + if (r.error || r.status !== 0) { + const detail = r.error ? r.error.message : String(r.stderr ?? "").trim(); + return { error: detail || "fetch failed" }; + } + return { error: null }; +} + +function remoteRunIds(projectRoot, remote) { + const listing = gitText(projectRoot, [ + "for-each-ref", "--format=%(refname)", `${REMOTE_REF_PREFIX}${remote}/factory-runs/`, + ]); + if (listing === null) return []; + return listing + .split("\n") + .map((line) => line.trim()) + .filter(Boolean) + .map((refname) => refname.slice(`${REMOTE_REF_PREFIX}${remote}/factory-runs/`.length)) + .filter((id) => id.length > 0); +} + +function remoteRunRow(projectRoot, remote, runId) { + const ref = `${REMOTE_REF_PREFIX}${remote}/factory-runs/${runId}`; + const sha = gitText(projectRoot, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]); + const stateText = gitText(projectRoot, ["show", `${ref}:state.json`]); + if (stateText === null) return null; // legacy/garbage ref — skipped, counted + let state; + try { + state = JSON.parse(stateText); + } catch { + return null; + } + if (!state || typeof state.run_id !== "string") return null; + const manifestText = gitText(projectRoot, ["show", `${ref}:trace/manifest.json`]); + let manifest = null; + if (manifestText !== null) { + try { + manifest = JSON.parse(manifestText); + } catch {} + } + return { state, manifest, remoteSha: sha ? sha.trim() : null }; +} + +// ── index ───────────────────────────────────────────────────────────────── + +function rowFrom({ state, manifest, remoteSha, source }) { + return { + run_id: state.run_id, + source, + workflow_id: state.workflow_id ?? manifest?.workflow_id ?? null, + status: state.status ?? manifest?.outcome ?? null, + current_step_id: state.current_step_id ?? null, + outcome: manifest?.outcome ?? state.status ?? null, + retention_class: manifest?.retention_class ?? null, + issue_ref: manifest?.issue_ref ?? state.inputs?.issue_ref ?? null, + updated_at: manifest?.updated_at ?? state.updated_at ?? null, + remote_sha: remoteSha ?? null, + }; +} + +// Build the pane-of-glass index. Degrades per source: a failed remote fetch +// sets remoteError and the board shows local runs only; refs that do not +// parse are skipped and counted in skippedRemote. +export function buildBoardIndex({ projectRoot = process.cwd(), remote = "origin" } = {}) { + // A remote is a name or URL, never a git option (refs.mjs checkRemote — + // same guard park/restore use): a value like `--upload-pack=` would + // be parsed by git fetch as an option and run . Validated here, at + // the single entry point before any git call, so both flag forms + // (`--remote x`, `--remote=x`) are covered. + checkRemote(remote); + const local = new Map(localRuns(projectRoot).map((r) => [r.state.run_id, r])); + + let remoteError = null; + let skippedRemote = 0; + const remoteMap = new Map(); + const fetch = fetchRemoteRefs(projectRoot, remote); + if (fetch.error !== null) { + remoteError = fetch.error; + } else { + for (const runId of remoteRunIds(projectRoot, remote)) { + const row = remoteRunRow(projectRoot, remote, runId); + if (row === null) { + skippedRemote += 1; + continue; + } + remoteMap.set(runId, row); + } + } + + const rows = []; + for (const [runId, entry] of local) { + const remoteEntry = remoteMap.get(runId); + rows.push( + rowFrom({ + state: entry.state, + manifest: entry.manifest, + remoteSha: remoteEntry?.remoteSha ?? null, + source: remoteEntry ? "both" : "local", + }), + ); + } + for (const [runId, entry] of remoteMap) { + if (local.has(runId)) continue; + rows.push( + rowFrom({ + state: entry.state, + manifest: entry.manifest, + remoteSha: entry.remoteSha, + source: "remote", + }), + ); + } + + rows.sort((a, b) => String(b.updated_at ?? "").localeCompare(String(a.updated_at ?? ""))); + return { runs: rows, remoteError, skippedRemote }; +} diff --git a/src/workflow/engine.mjs b/src/workflow/engine.mjs index bc6bd63..44e14d5 100644 --- a/src/workflow/engine.mjs +++ b/src/workflow/engine.mjs @@ -26,7 +26,8 @@ import { RunStatus, StepStatus, StepContext, typeName, repr } from "./base.mjs"; import { evaluateCondition } from "./expressions.mjs"; import { readAgent } from "../utils/init-options.mjs"; import { Lease } from "./lease.mjs"; -import { pushRunRef } from "./refs.mjs"; +import { syncRunRef } from "./refs.mjs"; +import { initTrace, appendTraceEvent, finalizeTrace } from "./trace.mjs"; import { currentHeadSha, hasContextGate } from "./gate-context.mjs"; import { loadBundledCatalog, @@ -526,6 +527,11 @@ export class RunState { } finally { closeSync(fd); } + // Trace bundle v1 (ADR-490): mirror the lifecycle entry into the + // ADR-362 stream. Fail-soft — telemetry never breaks a run. + try { + appendTraceEvent(this.runsDir, entry); + } catch {} }); } @@ -750,6 +756,11 @@ export class WorkflowEngine { state.runStartSha = currentHeadSha(String(this.projectRoot)); } await state.save(); + // Trace bundle v1 (ADR-490): identity + lifecycle stream from the start. + try { + initTrace(state.runsDir, { state, projectRoot: this.projectRoot, definition }); + appendTraceEvent(state.runsDir, { event: "run_started", workflow_id: definition.id }); + } catch {} this.emit("run_started", { run_id: state.runId, workflow_id: definition.id }); const context = new StepContext({ @@ -803,7 +814,14 @@ export class WorkflowEngine { this.emit("run_failed", { run_id: state.runId, error: state.error, status: state.status }); } try { - pushRunRef(this.projectRoot, state.runId, state.runsDir); + // Trace: close the bundle (retention) before the ref is pushed, so a + // pruned successful trace never reaches the remote. + finalizeTrace(state.runsDir, state); + } catch {} + try { + // Exit path (pause/terminal): push unconditionally so another machine + // can restore the run even if this pod is torn down immediately. + syncRunRef(this.projectRoot, state.runId, state.runsDir, { minIntervalSeconds: 0 }); } catch {} if (lease) lease.release(); } @@ -871,6 +889,11 @@ export class WorkflowEngine { state.error = null; state.status = RunStatus.RUNNING; await state.save(); + // Trace: resume keeps the original manifest identity and appends a marker. + try { + initTrace(state.runsDir, { state, projectRoot: this.projectRoot, definition }); + appendTraceEvent(state.runsDir, { event: "run_resumed", workflow_id: definition.id }); + } catch {} this.emit("run_started", { run_id: state.runId, workflow_id: definition.id, resumed: true }); // Resume from the current step — re-execute it so gates can prompt again. @@ -921,6 +944,9 @@ export class WorkflowEngine { state.currentStepIndex = stepOffset + i; } await state.save(); + // Step-boundary durability: throttled remote sync bounds the crash + // window to ADLC_WORKFLOW_PUSH_INTERVAL (ADR-475). + syncRunRef(this.projectRoot, state.runId, state.runsDir); if (lease) lease.renew(); this.emit("step_started", { run_id: state.runId, step_id: stepId, step_type: stepType }); diff --git a/src/workflow/redact.mjs b/src/workflow/redact.mjs new file mode 100644 index 0000000..e29133f --- /dev/null +++ b/src/workflow/redact.mjs @@ -0,0 +1,35 @@ +// Shared secret redaction for text bound for logs, notifiers, persisted run +// state, or the pushed run ref (ADR-478). Extracted from steps/shell.mjs so +// the refs transport can redact without importing a step implementation. + +// Secret-shaped env var names whose values never appear in outbound text. +const SECRET_ENV_NAME = /TOKEN|SECRET|PASSWORD|PASSWD|API_?KEY|PRIVATE_?KEY|CREDENTIAL|JWT/i; +// Well-known token formats (GitLab, GitHub, Slack, Anthropic/OpenAI-style keys, JWTs). +const TOKEN_PATTERNS = [ + /\bglpat-[A-Za-z0-9_-]{10,}/g, + /\bgl(?:dt|rt|cbt|ptt|ft|ffct|imt|oas|agent|soat)-[A-Za-z0-9_-]{10,}/g, + /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}/g, + /\bgithub_pat_[A-Za-z0-9_]{20,}/g, + /\bxox[abprs]-[A-Za-z0-9-]{10,}/g, + /\bsk-[A-Za-z0-9_-]{20,}/g, + /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, +]; + +/** Mask credentials in text bound for logs, notifiers or persisted run state. */ +export function redactSecrets(text, env = process.env) { + let out = text + // userinfo in URLs: https://user:token@host → https://***@host + .replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/gi, "$1***@") + // Authorization-style headers and key=value pairs: everything after the + // separator to the end of the line is masked, keeping only a known auth + // scheme. Multi-parameter schemes (AWS SigV4, Digest) carry credentials + // past the first word, and over-masking an error message costs nothing. + // A value on the next line (YAML, folded header) is masked too. + .replace(/\b(authorization|private-token|x-api-key)([ \t]*[:=](?:[ \t]*\r?\n)?[ \t]*)((?:bearer|basic|token|bot|digest|negotiate|apikey|key)[ \t]+)?[^\s][^\r\n]*/gi, "$1$2$3***"); + for (const re of TOKEN_PATTERNS) out = out.replace(re, "***"); + for (const [name, value] of Object.entries(env)) { + if (!value || value.length < 8 || !SECRET_ENV_NAME.test(name)) continue; + out = out.split(value).join("***"); + } + return out; +} diff --git a/src/workflow/refs.mjs b/src/workflow/refs.mjs index 8d3e8d2..49c07cb 100644 --- a/src/workflow/refs.mjs +++ b/src/workflow/refs.mjs @@ -3,10 +3,49 @@ // main history stays untouched. Called at session exit points (pause and // terminal states); best-effort: silently skipped outside a git repo. -import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs"; +import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync, copyFileSync } from "node:fs"; +import { tmpdir } from "node:os"; import { dirname, join, resolve, sep } from "node:path"; import { spawnSync } from "node:child_process"; import { err } from "../ui/index.mjs"; +import { redactSecrets } from "./redact.mjs"; + +// Machine-local run-dir files never cross machines (ADR-477): +// lease.json — liveness claim with hostname/pid/heartbeat +// .push-ts — local throttle stamp for remote run-ref sync +const EXCLUDED_RUN_FILES = new Set(["lease.json", ".push-ts"]); + +// Push throttle for state transitions (ADR-475 crash-window bound). The +// stamp lives inside the run dir and is excluded from the pushed tree. +const PUSH_STAMP = ".push-ts"; +const DEFAULT_PUSH_INTERVAL = 60; + +// ADR-490 retention is decided only at finalize. While the run is still +// executing (state.json status "running") its event stream must not reach +// the remote — a run that later completes would otherwise have already +// uploaded the very events.jsonl blobs that finalize prunes (the guarantee +// would be tip-only). Mid-run syncs stage the run dir without this file. +// Paused runs ship it (cross-session restore/resume needs the stream to +// continue where it left off — park, AC-T6) and terminal statuses ship the +// tree after finalizeTrace applied the retention class. +const MIDRUN_EXCLUDED_FILES = ["trace/events.jsonl"]; + +function pushIntervalSeconds() { + const raw = process.env.ADLC_WORKFLOW_PUSH_INTERVAL; + if (raw === undefined || raw === "") return DEFAULT_PUSH_INTERVAL; + const n = Number(raw); + return Number.isFinite(n) && n >= 0 ? n : DEFAULT_PUSH_INTERVAL; +} + +// Status recorded in the run dir's state.json, or null when unreadable — +// never throws, the sync stays fail-soft. +function runStatusOf(runDir) { + try { + return JSON.parse(readFileSync(join(runDir, "state.json"), "utf-8"))?.status ?? null; + } catch { + return null; + } +} export function pushRunRef(projectRoot, runId, runDir) { const git = (args, input) => @@ -31,8 +70,14 @@ export function pushRunRef(projectRoot, runId, runDir) { const hashDir = (absDir) => { const entries = []; for (const name of readdirSync(absDir).sort()) { + if (EXCLUDED_RUN_FILES.has(name)) continue; const abs = join(absDir, name); - if (statSync(abs).isDirectory()) { + // lstat, never stat: a symlink (file or directory) is skipped, not + // followed — a run dir must never ship or hash out-of-tree content, + // and a dangling symlink must not fail the walk (ADR-478). + const st = lstatSync(abs); + if (st.isSymbolicLink()) continue; + if (st.isDirectory()) { entries.push(`040000 tree ${hashDir(abs)}\t${name}`); } else { const h = git(["hash-object", "-w", abs]); @@ -59,6 +104,155 @@ export function pushRunRef(projectRoot, runId, runDir) { } } +// Redact secrets in every UTF-8 text file of the run dir, in place, before it +// is hashed into the pushed ref (ADR-478 redact-on-park). Binary/non-UTF-8 +// files are left untouched. Returns the number of files rewritten. +export function redactRunDir(runDir, env = process.env) { + const decoder = new TextDecoder("utf-8", { fatal: true }); + let rewritten = 0; + const walk = (absDir) => { + for (const name of readdirSync(absDir)) { + const abs = join(absDir, name); + // lstat, never stat: redaction must not write through a symlink into + // files outside the run dir, nor recurse into symlinked directories; + // a dangling symlink must not fail the walk (ADR-478). + const st = lstatSync(abs); + if (st.isSymbolicLink()) continue; + if (st.isDirectory()) { + walk(abs); + continue; + } + if (EXCLUDED_RUN_FILES.has(name)) continue; + const buf = readFileSync(abs); + let text; + try { + text = decoder.decode(buf); + } catch { + continue; // not UTF-8 text + } + const redacted = redactSecrets(text, env); + if (redacted !== text) { + writeFileSync(abs, redacted, "utf-8"); + rewritten += 1; + } + } + }; + walk(runDir); + return rewritten; +} + +// Stage a throwaway copy of the run dir for redaction: the pushed tree is +// built from the copy, never from the live run dir. Machine-local files +// (EXCLUDED_RUN_FILES, ADR-477) and symlinks (ADR-478, no traversal) are +// left out of the copy entirely. Returns { dir, cleanup } or null when the +// copy itself fails — callers treat null as "skip this push" (fail-closed, +// fail-soft). +function stageRunDir(runDir) { + let staged; + try { + staged = mkdtempSync(join(tmpdir(), "adlc-runref-")); + const copy = (absSrc, absDst) => { + for (const name of readdirSync(absSrc)) { + if (EXCLUDED_RUN_FILES.has(name)) continue; + const src = join(absSrc, name); + const dst = join(absDst, name); + // lstat, never stat: symlinks are skipped, not copied or followed. + const st = lstatSync(src); + if (st.isSymbolicLink()) continue; + if (st.isDirectory()) { + mkdirSync(dst, { recursive: true }); + copy(src, dst); + } else { + copyFileSync(src, dst); + } + } + }; + copy(runDir, staged); + } catch { + if (staged) { + try { rmSync(staged, { recursive: true, force: true }); } catch {} + } + return null; + } + return { + dir: staged, + cleanup() { + try { rmSync(staged, { recursive: true, force: true }); } catch {} + }, + }; +} + +// syncRunRef — record the run dir as refs/factory-runs/ locally, then +// force-push that ref to the remote so another machine can restore it +// (ADR-475). The remote push is throttled by ADLC_WORKFLOW_PUSH_INTERVAL +// seconds (default 60; 0 = every transition) and is fail-soft: an offline +// pod never fails the run, and the local ref stays valid for the next sync. +export function syncRunRef(projectRoot, runId, runDir, { remote = "origin", minIntervalSeconds = pushIntervalSeconds() } = {}) { + const ref = `refs/factory-runs/${runId}`; + const stamp = join(runDir, PUSH_STAMP); + if (minIntervalSeconds > 0 && existsSync(stamp)) { + // Unreadable stamp (EACCES, TOCTOU removal) counts as absent: proceed + // to push, never fail the transition (ADR-497 fail-soft). + let last = NaN; + try { + last = Number(readFileSync(stamp, "utf-8").trim()); + } catch { + last = NaN; + } + if (Number.isFinite(last) && Date.now() - last < minIntervalSeconds * 1000) { + return true; + } + } + // Every sync is redacted, but never in place: the live run dir must stay + // byte-identical across a transition, because resume() reads inputs.json + // (and later steps read their original values) from it — masking there + // would silently substitute "***" into a resumed run (ADR-497: "no run + // file edited in place except redaction at park"). The pushed tree is + // built from a throwaway staging copy instead: copy, redact the copy, + // hash+push the copy, discard it. Machine-local files (ADR-477) never + // enter the staging copy at all. Fail-closed: if redaction of the staged + // copy fails, the push is skipped entirely — the wire never receives + // unredacted content — but the transition itself stays fail-soft. + const staged = stageRunDir(runDir); + if (staged === null) return false; + try { + // ADR-490: while the run executes (status "running"), the retention + // class is still pending — the event stream stays off the wire until + // finalize decides it (paused/terminal pushes below ship the tree per + // retention class). Only the staged copy is trimmed; the live run dir + // keeps recording events. + if (runStatusOf(runDir) === "running") { + for (const rel of MIDRUN_EXCLUDED_FILES) { + rmSync(join(staged.dir, ...rel.split("/")), { force: true }); + } + } + try { + redactRunDir(staged.dir); + } catch (exc) { + err(`[workflow] run-ref redaction failed for ${runId}; push skipped: ${exc?.message ?? exc}`); + return true; + } + if (!pushRunRef(projectRoot, runId, staged.dir)) return false; + } finally { + staged.cleanup(); + } + const pushed = spawnSync("git", ["push", "--quiet", remote, `+${ref}:${ref}`], { + cwd: projectRoot, + encoding: "utf-8", + maxBuffer: 16 * 1024 * 1024, + timeout: 30_000, + }); + if (pushed.error || pushed.status !== 0) { + const detail = pushed.error ? pushed.error.message : String(pushed.stderr ?? "").trim(); + err(`[workflow] run-ref remote sync skipped: ${detail}`); + return true; + } + try { + writeFileSync(stamp, String(Date.now()), "utf-8"); + } catch {} + return true; +} + // Park and restore (ADR-391-amendment-3 §2–3): a run paused at a gate past // its in-pod wait is saved — with the gate's Slack thread handle — to // refs/factory-runs/ on a git remote, so a later pod in another clone @@ -66,9 +260,9 @@ export function pushRunRef(projectRoot, runId, runDir) { // the best-effort pushRunRef, a park or restore that silently did nothing // would lose the approver's answer or resume the wrong run. // -// pushRunRef hashes the whole runDir, inputs.json included: whatever was -// passed via --input lands on the remote verbatim. A secret-valued input -// must never be parked to a broadly-readable remote. +// pushRunRef hashes the whole runDir, inputs.json included, after +// redactRunDir masks secret-shaped values: whatever was passed via --input +// still lands on the remote, but a secret-valued input is masked first. const RUN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/; @@ -84,6 +278,11 @@ export function parkRun(projectRoot, runId, { handleFile, remote = "origin" } = throw new Error("park: the handle file must hold a JSON object"); } writeFileSync(join(runDir, "gate-handle.json"), JSON.stringify(handle, null, 2) + "\n", "utf-8"); + // ADR-478: redact every text file in place before it is hashed into the + // ref, so a secret that leaked into state/logs/inputs never reaches the + // remote. Machine-local files (lease.json, .push-ts) are excluded from the + // tree by pushRunRef (ADR-477). + redactRunDir(runDir); if (!pushRunRef(projectRoot, runId, runDir)) throw new Error(`park: could not record refs/factory-runs/${runId}`); const ref = `refs/factory-runs/${runId}`; // The run ref is rebuilt from scratch at every save, so it never descends @@ -154,7 +353,7 @@ function runDirFor(projectRoot, runId) { // (git's remote-helper transport runs directly) -- `remote` is // operator-supplied here (a local CLI flag), never attacker data from a // parked ref, so that trust assumption is accepted, not defended against. -function checkRemote(remote) { +export function checkRemote(remote) { if (typeof remote !== "string" || remote === "" || remote.startsWith("-") || /[\0\n]/.test(remote)) { throw new Error(`invalid remote ${JSON.stringify(remote)}`); } diff --git a/src/workflow/state.mjs b/src/workflow/state.mjs index dac032d..6aa66aa 100644 --- a/src/workflow/state.mjs +++ b/src/workflow/state.mjs @@ -9,7 +9,8 @@ import { join } from "node:path"; import { WorkflowEngine, WorkflowDefinition, RunState, RunStatus } from "./engine.mjs"; import { STEP_REGISTRY } from "./registry.mjs"; import { Lease } from "./lease.mjs"; -import { pushRunRef } from "./refs.mjs"; +import { syncRunRef } from "./refs.mjs"; +import { initTrace, appendTraceEvent, finalizeTrace } from "./trace.mjs"; // start: create a run (status running, index 0) from a workflow source. // Returns the run state. Does NOT execute steps — the LLM executor drives. @@ -43,8 +44,16 @@ export async function stateStart({ projectRoot = process.cwd(), workflowSource, state.status = RunStatus.RUNNING; state.currentStepIndex = 0; state.currentStepId = definition.steps[0]?.id ?? null; + // Trace bundle v1 (ADR-490): identity is durable from the first save, and + // the run-start event opens the lifecycle stream. + try { + initTrace(state.runsDir, { state, projectRoot, definition }); + appendTraceEvent(state.runsDir, { event: "run_started", workflow_id: definition.id }); + } catch {} await state.save(); - pushRunRef(projectRoot, state.runId, state.runsDir); + // Run start is durable immediately: a pod that dies right after start is + // still restorable from the remote ref (ADR-475). + syncRunRef(projectRoot, state.runId, state.runsDir, { minIntervalSeconds: 0 }); releaseCommandScoped(); return state; } @@ -118,7 +127,23 @@ export async function stateAdvance({ } await state.save(); - pushRunRef(projectRoot, runId, state.runsDir); + // Trace: record the helper transition, then close the bundle on a terminal + // status (retention prunes successful events before the ref sync below). + try { + appendTraceEvent(state.runsDir, { + event: "step_advanced", + step_id: stepId, + status, + output: output ?? null, + error: error ?? null, + }); + if ([RunStatus.COMPLETED, RunStatus.FAILED, RunStatus.ABORTED].includes(state.status)) { + finalizeTrace(state.runsDir, state); + } + } catch {} + // Throttled remote sync: on a crash, the remote lags by at most the + // throttle window (one step when steps are longer than the window). + syncRunRef(projectRoot, runId, state.runsDir); if (state.status === RunStatus.COMPLETED || !lease.persistent) lease.release(); return state; } @@ -133,7 +158,13 @@ export async function statePause({ projectRoot = process.cwd(), runId, stepId } state.currentStepIndex = idx; state.currentStepId = stepId; await state.save(); - pushRunRef(projectRoot, runId, state.runsDir); + // Trace: a pause is not terminal; keep the full bundle and mark the outcome. + try { + appendTraceEvent(state.runsDir, { event: "run_paused", step_id: stepId }); + finalizeTrace(state.runsDir, state); + } catch {} + // Exit path: push unconditionally so the pause survives a pod teardown. + syncRunRef(projectRoot, runId, state.runsDir, { minIntervalSeconds: 0 }); lease.release(); return state; } @@ -145,7 +176,13 @@ export async function stateFail({ projectRoot = process.cwd(), runId, error } = state.status = RunStatus.FAILED; state.error = error ?? "failed"; await state.save(); - pushRunRef(projectRoot, runId, state.runsDir); + // Trace: failures keep full events (ADR-490 retention). + try { + appendTraceEvent(state.runsDir, { event: "run_failed", error: state.error }); + finalizeTrace(state.runsDir, state); + } catch {} + // Exit path: push unconditionally so the failure is visible remotely. + syncRunRef(projectRoot, runId, state.runsDir, { minIntervalSeconds: 0 }); lease.release(); return state; } diff --git a/src/workflow/steps/shell.mjs b/src/workflow/steps/shell.mjs index e8f47bd..3e09fd6 100644 --- a/src/workflow/steps/shell.mjs +++ b/src/workflow/steps/shell.mjs @@ -5,6 +5,11 @@ import { exec } from "node:child_process"; import { StepBase, StepContext, StepResult, StepStatus, typeName } from "../base.mjs"; import { evaluateExpression } from "../expressions.mjs"; import { prepareStepOutput, readStepOutput, runContextEnv } from "./agent.mjs"; +import { redactSecrets } from "../redact.mjs"; + +// Re-exported for existing consumers/tests; the implementation lives in +// ../redact.mjs so the refs transport can redact without importing a step. +export { redactSecrets } from "../redact.mjs"; export class ShellStep extends StepBase { static typeKey = "shell"; @@ -151,38 +156,6 @@ function stderrTail(stderr, env = process.env) { return ` stderr: ${tail}`; } -// Secret-shaped env var names whose values never appear in an error message. -const SECRET_ENV_NAME = /TOKEN|SECRET|PASSWORD|PASSWD|API_?KEY|PRIVATE_?KEY|CREDENTIAL|JWT/i; -// Well-known token formats (GitLab, GitHub, Slack, Anthropic/OpenAI-style keys, JWTs). -const TOKEN_PATTERNS = [ - /\bglpat-[A-Za-z0-9_-]{10,}/g, - /\bgl(?:dt|rt|cbt|ptt|ft|ffct|imt|oas|agent|soat)-[A-Za-z0-9_-]{10,}/g, - /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}/g, - /\bgithub_pat_[A-Za-z0-9_]{20,}/g, - /\bxox[abprs]-[A-Za-z0-9-]{10,}/g, - /\bsk-[A-Za-z0-9_-]{20,}/g, - /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, -]; - -/** Mask credentials in text bound for logs, notifiers or persisted run state. */ -export function redactSecrets(text, env = process.env) { - let out = text - // userinfo in URLs: https://user:token@host → https://***@host - .replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/gi, "$1***@") - // Authorization-style headers and key=value pairs: everything after the - // separator to the end of the line is masked, keeping only a known auth - // scheme. Multi-parameter schemes (AWS SigV4, Digest) carry credentials - // past the first word, and over-masking an error message costs nothing. - // A value on the next line (YAML, folded header) is masked too. - .replace(/\b(authorization|private-token|x-api-key)([ \t]*[:=](?:[ \t]*\r?\n)?[ \t]*)((?:bearer|basic|token|bot|digest|negotiate|apikey|key)[ \t]+)?[^\s][^\r\n]*/gi, "$1$2$3***"); - for (const re of TOKEN_PATTERNS) out = out.replace(re, "***"); - for (const [name, value] of Object.entries(env)) { - if (!value || value.length < 8 || !SECRET_ENV_NAME.test(name)) continue; - out = out.split(value).join("***"); - } - return out; -} - function execAsync(cmd, opts) { return new Promise((resolveP) => { let interrupted = false; diff --git a/src/workflow/trace.mjs b/src/workflow/trace.mjs new file mode 100644 index 0000000..a16e560 --- /dev/null +++ b/src/workflow/trace.mjs @@ -0,0 +1,333 @@ +// Trace bundle v1 (ADR-490) — run identity, lifecycle events and artifact +// metadata written into the run dir, and therefore into the pushed run ref. +// +// Layout: +// trace/manifest.json always retained +// trace/events.jsonl ADR-362 envelope, ADR-364 canonical types +// trace/artifacts.json content-addressed artifact index +// +// Capture-time redaction (ADR-478 amended by ADR-488/490): every string that +// enters the trace passes through the shared text redactor first. Writes are +// fail-soft at the call sites — telemetry never fails a run. + +import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { isAbsolute, join } from "node:path"; +import { createHash } from "node:crypto"; +import { spawnSync } from "node:child_process"; +import { RunStatus } from "./base.mjs"; +import { redactSecrets } from "./redact.mjs"; +import { readAgent } from "../utils/init-options.mjs"; +import { currentHeadSha } from "./gate-context.mjs"; + +export const TRACE_SCHEMA_VERSION = 1; + +const TRACE_DIR = "trace"; +const DEFAULT_AGENT_ID = "adlc-cli"; + +// ADR-364 canonical event types, keyed by the run-log event name. +const CANONICAL_EVENT_TYPES = Object.freeze({ + workflow_failed: "error", + resume_failed: "error", + run_failed: "error", + workflow_finished: "complete", + run_completed: "complete", + gate_paused: "permission_request", + permission_request: "permission_request", +}); + +export function tracePaths(runDir) { + const dir = join(runDir, TRACE_DIR); + return { + dir, + manifest: join(dir, "manifest.json"), + events: join(dir, "events.jsonl"), + artifacts: join(dir, "artifacts.json"), + }; +} + +function nowIso() { + return new Date().toISOString(); +} + +function sha256Hex(value) { + return createHash("sha256").update(value).digest("hex"); +} + +function writeJson(path, value) { + writeFileSync(path, JSON.stringify(value, null, 2) + "\n", "utf-8"); +} + +// Walk a structured value and redact every string, so the emitted JSON stays +// valid (redacting a serialized document could corrupt it). +function redactDeep(value, env = process.env) { + if (typeof value === "string") return redactSecrets(value, env); + if (Array.isArray(value)) return value.map((v) => redactDeep(v, env)); + if (value && typeof value === "object") { + const out = {}; + for (const [k, v] of Object.entries(value)) out[k] = redactDeep(v, env); + return out; + } + return value; +} + +function readFileHash(projectRoot, candidates) { + for (const rel of candidates) { + const abs = join(projectRoot, rel); + if (!existsSync(abs)) continue; + try { + return sha256Hex(readFileSync(abs)); + } catch { + return null; + } + } + return null; +} + +function gitValue(projectRoot, args) { + const out = spawnSync("git", args, { + cwd: projectRoot, + encoding: "utf-8", + maxBuffer: 1024 * 1024, + }); + if (out.error || out.status !== 0) return null; + const text = String(out.stdout ?? "").trim(); + return text || null; +} + +function issueRefFor(state, issueRef) { + if (issueRef !== undefined && issueRef !== null && String(issueRef) !== "") return String(issueRef); + const input = state?.inputs?.issue_ref; + if (input !== undefined && input !== null && String(input) !== "") return String(input); + const env = (process.env.ADLC_ISSUE_REF ?? "").trim(); + return env || null; +} + +function manifestFor({ state, projectRoot, definition, issueRef, workloadClass }) { + const agent = readAgent(projectRoot) ?? process.env.ADLC_AGENT ?? null; + return { + schema_version: TRACE_SCHEMA_VERSION, + run_id: state.runId, + workflow_id: state.workflowId, + issue_ref: issueRefFor(state, issueRef), + repository: { + remote: gitValue(projectRoot, ["config", "--get", "remote.origin.url"]), + branch: gitValue(projectRoot, ["rev-parse", "--abbrev-ref", "HEAD"]), + run_start_sha: state.runStartSha ?? currentHeadSha(projectRoot), + head_sha: currentHeadSha(projectRoot), + }, + agent: { + id: agent, + session_id: process.env.ADLC_AGENT_SESSION_ID ?? null, + parent_session_id: process.env.ADLC_PARENT_SESSION_ID ?? null, + }, + model: { + name: definition?.defaultModel ?? null, + route: definition?.defaultIntegration ?? null, + }, + container: { + image_digest: process.env.ADLC_CONTAINER_IMAGE_DIGEST ?? null, + }, + config: { + skill_lock_hash: readFileHash(projectRoot, ["skills-lock.json"]), + mcp_config_hash: readFileHash(projectRoot, [".mcp.json", ".opencode/mcp.json"]), + }, + created_at: state.createdAt ?? nowIso(), + updated_at: nowIso(), + finished_at: null, + outcome: state.status ?? RunStatus.RUNNING, + gateway_cost: null, + retention_class: "pending", + workload_class: workloadClass ?? process.env.ADLC_WORKLOAD_CLASS ?? "unknown", + }; +} + +// Create the bundle for a run (idempotent). An existing manifest is updated, +// never recreated, so a resumed run keeps its original identity. +export function initTrace(runDir, { + state = null, + projectRoot = state?.projectRoot ?? process.cwd(), + definition = null, + issueRef = undefined, + workloadClass = null, +} = {}) { + const paths = tracePaths(runDir); + mkdirSync(paths.dir, { recursive: true }); + + let manifest; + if (existsSync(paths.manifest)) { + try { + manifest = JSON.parse(readFileSync(paths.manifest, "utf-8")); + manifest.updated_at = nowIso(); + if (state?.status) manifest.outcome = state.status; + } catch { + manifest = manifestFor({ state, projectRoot, definition, issueRef, workloadClass }); + } + } else { + manifest = manifestFor({ state, projectRoot, definition, issueRef, workloadClass }); + } + writeJson(paths.manifest, redactDeep(manifest)); + + if (!existsSync(paths.events)) writeFileSync(paths.events, "", "utf-8"); + if (!existsSync(paths.artifacts)) { + writeJson(paths.artifacts, { schema_version: TRACE_SCHEMA_VERSION, artifacts: [] }); + } + return manifest; +} + +function lastEventName(paths) { + if (!existsSync(paths.events)) return null; + try { + const text = readFileSync(paths.events, "utf-8").trimEnd(); + if (!text) return null; + const lastLine = text.slice(text.lastIndexOf("\n") + 1); + return JSON.parse(lastLine)?.payload?.adlc?.event ?? null; + } catch { + return null; + } +} + +// Append one ADR-362 envelope. The original run-log entry rides under +// payload.adlc so ADR-362 consumers keep parsing the stream unchanged. +export function appendTraceEvent(runDir, entry = {}, { agentId = DEFAULT_AGENT_ID } = {}) { + const paths = tracePaths(runDir); + mkdirSync(paths.dir, { recursive: true }); + if (!existsSync(paths.events)) writeFileSync(paths.events, "", "utf-8"); + + const eventName = String(entry.event ?? "log"); + const type = CANONICAL_EVENT_TYPES[eventName] ?? "log"; + const envelope = { + schema_version: 1, + agent_id: agentId, + ts: entry.timestamp ?? nowIso(), + type, + payload: { adlc: redactDeep({ ...entry }) }, + }; + appendFileSync(paths.events, JSON.stringify(envelope) + "\n", "utf-8"); + return envelope; +} + +function successSampleRate(raw = process.env.ADLC_TRACE_SUCCESS_SAMPLE_RATE) { + if (raw === undefined || raw === null || String(raw).trim() === "") return 0; + const rate = Number(raw); + if (!Number.isFinite(rate) || rate <= 0) return 0; + return rate >= 1 ? 1 : rate; +} + +// Deterministic per-run sampling: the same run always gets the same verdict, +// so re-applying the policy never flips a retained trace into a pruned one. +function sampledIn(runId, rate) { + if (rate >= 1) return true; + if (rate <= 0) return false; + const digest = createHash("sha256").update(String(runId)).digest(); + return digest.readUInt32BE(0) / 0x100000000 < rate; +} + +// Close the trace at a session boundary. Terminal statuses apply retention: +// failures and aborts keep full events; successes keep only the manifest +// unless the deployment's sampling policy selects the run (fail closed). +export function finalizeTrace(runDir, state, { sampleRate } = {}) { + const paths = tracePaths(runDir); + if (!existsSync(paths.manifest)) return null; + + let manifest; + try { + manifest = JSON.parse(readFileSync(paths.manifest, "utf-8")); + } catch { + return null; + } + + const status = state?.status ?? manifest.outcome; + manifest.outcome = status; + manifest.updated_at = nowIso(); + + // ADR-490 replay identity: head_sha must reflect the revision the run + // actually ended on, not only the one it started from. Steps can move the + // repo HEAD after initTrace captured it, so refresh at every finalize — + // run_start_sha keeps the run-start revision for the pair. + const headSha = currentHeadSha(state?.projectRoot ?? process.cwd()); + if (headSha && manifest.repository) manifest.repository.head_sha = headSha; + + if (status === RunStatus.PAUSED) { + if (lastEventName(paths) !== "run_paused") { + appendTraceEvent(runDir, { event: "run_paused", step_id: state?.currentStepId ?? null }); + } + } else if ([RunStatus.COMPLETED, RunStatus.FAILED, RunStatus.ABORTED].includes(status)) { + if (status === RunStatus.COMPLETED) { + if (lastEventName(paths) !== "run_completed") { + appendTraceEvent(runDir, { event: "run_completed", status }); + } + } else if (lastEventName(paths) !== "run_failed") { + appendTraceEvent(runDir, { event: "run_failed", status, error: state?.error ?? null }); + } + + manifest.finished_at = nowIso(); + if (status === RunStatus.COMPLETED) { + const rate = sampleRate ?? successSampleRate(); + if (sampledIn(manifest.run_id, rate)) { + manifest.retention_class = "full-sampled"; + manifest.trace_pruned = false; + } else { + manifest.retention_class = "manifest-only"; + manifest.trace_pruned = true; + rmSync(paths.events, { force: true }); + } + } else { + manifest.retention_class = "full"; + manifest.trace_pruned = false; + } + } + + writeJson(paths.manifest, redactDeep(manifest)); + return manifest; +} + +const ARTIFACT_FIELDS = ["media_type", "storage_uri", "retention_class", "sensitivity", "producing_event"]; +const SHA256_RE = /^[0-9a-f]{64}$/; + +// Append a content-addressed artifact entry. `path` (relative to the run dir) +// hashes a local file; otherwise an explicit content_sha256 is required. +// Invalid input throws — callers decide whether that is fatal. +export function recordArtifact(runDir, artifact = {}) { + const paths = tracePaths(runDir); + mkdirSync(paths.dir, { recursive: true }); + + let doc; + if (existsSync(paths.artifacts)) { + try { + doc = JSON.parse(readFileSync(paths.artifacts, "utf-8")); + } catch { + doc = { schema_version: TRACE_SCHEMA_VERSION, artifacts: [] }; + } + } else { + doc = { schema_version: TRACE_SCHEMA_VERSION, artifacts: [] }; + } + if (!Array.isArray(doc.artifacts)) doc.artifacts = []; + + const entry = { ...artifact }; + if (entry.content_sha256 !== undefined) { + if (!SHA256_RE.test(String(entry.content_sha256))) { + throw new Error("artifact content_sha256 must be a 64-character lowercase hex sha256 digest"); + } + } else if (entry.path) { + const abs = isAbsolute(entry.path) ? entry.path : join(runDir, entry.path); + const bytes = readFileSync(abs); + entry.content_sha256 = sha256Hex(bytes); + entry.size = bytes.length; + } else { + throw new Error("artifact requires content_sha256 or path"); + } + + if (!Number.isInteger(entry.size) || entry.size < 0) { + throw new Error("artifact size must be a non-negative integer"); + } + for (const field of ARTIFACT_FIELDS) { + if (typeof entry[field] !== "string" || entry[field].trim() === "") { + throw new Error(`artifact ${field} is required`); + } + } + + entry.created_at = nowIso(); + doc.artifacts.push(redactDeep(entry)); + writeJson(paths.artifacts, doc); + return entry; +} diff --git a/tests/e2e-cross-session.mjs b/tests/e2e-cross-session.mjs new file mode 100644 index 0000000..d4b0bae --- /dev/null +++ b/tests/e2e-cross-session.mjs @@ -0,0 +1,222 @@ +// E2E — cross-session run transport + trace bundle (Phases 0+1 verification). +// +// Two separate adlc-cli processes ("sessions"), two separate clones of one +// bare remote ("pods"), driven only through the real CLI binary: +// +// Session A (pod-a): run → paused at gate (exit 3) → park → exit +// Session B (pod-b): restore (guarded) → resume → completed (exit 0) +// +// Contract verified here: +// V1 a run paused at a gate exits 3 (lane contract) and parks to +// refs/factory-runs/ on the remote. +// V2 the pushed ref tree excludes machine-local lease.json / .push-ts +// (ADR-477) and carries the trace bundle (ADR-490). +// V3 restore refuses a mismatched --issue-ref and an existing run dir. +// V4 every event line restored from the ref is a valid ADR-362 envelope +// with an ADR-364 canonical type (ADR-362/364). +// V5 a seeded secret never crosses the session boundary: it is absent +// from the entire restored run dir (capture redaction, ADR-478). +// V6 resume in session B completes the run; default retention prunes the +// successful events and keeps the manifest (ADR-490 fail-closed). + +import { spawnSync } from "node:child_process"; +import { mkdtempSync, rmSync, writeFileSync, mkdirSync, readFileSync, existsSync, readdirSync, statSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const HERE = dirname(fileURLToPath(import.meta.url)); +const CLI = join(HERE, "..", "bin", "adlc-cli.mjs"); + +const SECRET = "crossSessionSecretValue42"; + +const base = mkdtempSync(join(tmpdir(), "adlc-e2e-cross-")); +const bare = join(base, "origin.git"); +const podA = join(base, "pod-a"); +const podB = join(base, "pod-b"); + +let failures = 0; +function check(label, ok) { + console.log(` ${ok ? "PASS" : "FAIL"}: ${label}`); + if (!ok) failures += 1; +} + +function git(cwd, ...args) { + const r = spawnSync("git", args, { cwd, encoding: "utf-8" }); + if (r.status !== 0) throw new Error(`git ${args.join(" ")} failed: ${r.stderr}`); + return r.stdout.trim(); +} + +function cli(cwd, args, env = {}) { + return spawnSync(process.execPath, [CLI, ...args], { + cwd, + encoding: "utf-8", + env: { ...process.env, ...env }, + }); +} + +const strip = (s) => s.replace(/\[[0-9;]*[A-Za-z]/g, ""); + +try { + // ── setup: bare remote + two clones ──────────────────────────────────── + git(base, "init", "-q", "--bare", "-b", "main", bare); + mkdirSync(podA); + git(podA, "init", "-q", "-b", "main"); + git(podA, "config", "user.email", "t@t.local"); + git(podA, "config", "user.name", "t"); + git(podA, "config", "commit.gpgsign", "false"); + writeFileSync(join(podA, ".gitignore"), ".adlc/workflows/\n", "utf-8"); + writeFileSync(join(podA, "README.md"), "base\n", "utf-8"); + git(podA, "add", "-A"); + git(podA, "commit", "-q", "-m", "base"); + git(podA, "remote", "add", "origin", bare); + git(podA, "push", "-q", "origin", "main"); + + const wfDir = join(podA, "wf"); + mkdirSync(wfDir); + writeFileSync(join(wfDir, "flow.yml"), `schema_version: "1.0" +workflow: + id: cross-session + name: Cross Session + version: "1.0.0" +inputs: + verdict: {type: string, enum: ["", approve, reject]} +steps: + - id: work + type: shell + run: "echo leaked=$CROSS_SESSION_TOKEN" + - id: approve + type: gate + message: "Approve before finishing?" + options: [approve, reject] + on_reject: abort + verdict_input: verdict + - id: finish + type: shell + run: "echo finished" +`, "utf-8"); + + // ── session A: run to the gate, then park ────────────────────────────── + console.log("== 1. session A: run → paused at gate =="); + const runA = cli(podA, ["workflow", "run", "wf/flow.yml", "--input", "verdict="], { + CROSS_SESSION_TOKEN: SECRET, + }); + const runText = strip(runA.stdout + runA.stderr); + const runIdMatch = runText.match(/resume ([A-Za-z0-9][A-Za-z0-9._-]*)/); + check("run exits 3 (paused, lane contract)", runA.status === 3); + check("run prints the resume hint with the run id", runIdMatch !== null); + const runId = runIdMatch ? runIdMatch[1] : "unknown"; + + writeFileSync(join(base, "handle.json"), JSON.stringify({ channel: "C1", thread_ts: "1.0" }), "utf-8"); + const parkA = cli(podA, ["workflow", "park", runId, "--handle-file", join(base, "handle.json")]); + check("park exits 0", parkA.status === 0); + + console.log("== 2. remote ref contents (V2) =="); + const ref = `refs/factory-runs/${runId}`; + const tree = git(bare, "ls-tree", "-r", "--name-only", ref).split("\n").filter(Boolean); + check("ref tree excludes lease.json (ADR-477)", !tree.includes("lease.json")); + check("ref tree excludes .push-ts (ADR-477)", !tree.includes(".push-ts")); + for (const rel of ["trace/manifest.json", "trace/events.jsonl", "trace/artifacts.json"]) { + check(`ref tree carries ${rel} (ADR-490)`, tree.includes(rel)); + } + const remoteManifest = JSON.parse(git(bare, "show", `${ref}:trace/manifest.json`)); + check("remote manifest outcome is paused", remoteManifest.outcome === "paused"); + + console.log("== 3. session B: guarded restore (V3) =="); + git(bare, "clone", "-q", bare, podB); + for (const args of [["user.email", "t@t.local"], ["user.name", "t"], ["commit.gpgsign", "false"]]) { + git(podB, "config", ...args); + } + git(podB, "remote", "remove", "origin"); + git(podB, "remote", "add", "origin", bare); + const wrongRef = cli(podB, ["workflow", "restore", runId, "--issue-ref", "issue-999"]); + check("restore refuses a mismatched issue-ref", wrongRef.status === 1); + check( + "restore names the mismatch", + strip(wrongRef.stderr + wrongRef.stdout).includes("issue_ref"), + ); + + const restoreB = cli(podB, ["workflow", "restore", runId]); + check("restore succeeds", restoreB.status === 0); + const againB = cli(podB, ["workflow", "restore", runId]); + check("second restore refuses an existing run dir", againB.status === 1); + + console.log("== 4. restored bundle validates (V4/V5) =="); + const runDirB = join(podB, ".adlc", "workflows", "runs", runId); + const eventsPath = join(runDirB, "trace", "events.jsonl"); + const canonical = new Set(["message", "tool", "permission_request", "error", "complete", "log"]); + const envelopes = readFileSync(eventsPath, "utf-8").split("\n").filter(Boolean).map((l) => JSON.parse(l)); + check("restored events file is non-empty", envelopes.length > 0); + check( + "every event is a valid ADR-362 envelope with a canonical type", + envelopes.every( + (e) => + e.schema_version === 1 && + typeof e.agent_id === "string" && + e.agent_id.length > 0 && + !Number.isNaN(Date.parse(e.ts)) && + canonical.has(e.type) && + typeof e.payload?.adlc?.event === "string", + ), + ); + check( + "run pause is recorded in the stream", + envelopes.some((e) => e.payload.adlc.event === "run_paused" || e.payload.adlc.event === "gate_paused"), + ); + + // V5: the secret printed by the work step must be absent from the whole + // restored run dir — shell-step redaction and trace redaction together. + let secretHits = 0; + const scan = (abs) => { + if (statSync(abs).isDirectory()) { + for (const name of readdirSync(abs)) scan(join(abs, name)); + return; + } + try { + if (readFileSync(abs, "utf-8").includes(SECRET)) secretHits += 1; + } catch {} // binary file + }; + scan(runDirB); + check(`seeded secret absent from the restored run dir (${secretHits} hits)`, secretHits === 0); + const maskText = readFileSync(join(runDirB, "state.json"), "utf-8"); + // The work step is `echo leaked=$CROSS_SESSION_TOKEN`. On POSIX the shell + // expands the variable, so the secret enters the step output and the + // capture-redaction path must mask it with `***`. On Windows the CLI's + // shell step runs through cmd.exe (Node's exec default — no shell override + // in src/workflow/steps/shell.mjs), which does not expand POSIX variables: + // the step output literally reads `leaked=$CROSS_SESSION_TOKEN`, the secret + // never enters the stream, and there is nothing to redact. So on win32 we + // assert the no-expansion behavior instead. The redaction path itself + // stays covered by the POSIX lanes and the unit tests, and the raw-secret + // absence scan above runs on all platforms. + if (process.platform === "win32") { + check( + "work-step output carries the unexpanded variable (cmd does not expand POSIX vars)", + maskText.includes("leaked=$CROSS_SESSION_TOKEN"), + ); + } else { + check("work-step output carries the mask", maskText.includes("***")); + } + + console.log("== 5. session B: resume → completed (V6) =="); + const resumeB = cli(podB, ["workflow", "resume", runId, "--input", "verdict=approve"]); + check("resume exits 0", resumeB.status === 0); + const showB = cli(podB, ["workflow", "state", "show", runId, "--format", "json"]); + const stateB = JSON.parse(showB.stdout); + check("final status is completed", stateB.status === "completed"); + + const manifestB = JSON.parse(readFileSync(join(runDirB, "trace", "manifest.json"), "utf-8")); + check("manifest outcome is completed", manifestB.outcome === "completed"); + check("default retention prunes successful events (fail-closed)", !existsSync(eventsPath)); + check("manifest survives retention", existsSync(join(runDirB, "trace", "manifest.json"))); + check("retention class is manifest-only", manifestB.retention_class === "manifest-only"); + check("manifest has no lease conflict fields", !existsSync(join(runDirB, "lease.json"))); +} finally { + try { rmSync(base, { recursive: true, force: true }); } catch {} +} + +if (failures > 0) { + console.log(`\nE2E FAILED (${failures} assertion${failures === 1 ? "" : "s"} failed)`); + process.exit(1); +} +console.log("\nE2E PASSED (all assertions green)"); diff --git a/tests/workflow-board.test.mjs b/tests/workflow-board.test.mjs new file mode 100644 index 0000000..98ca07c --- /dev/null +++ b/tests/workflow-board.test.mjs @@ -0,0 +1,315 @@ +// Phase 3 — factory board / pane of glass v1 (ADR-476, ADR-490 query index). +// +// Contract pinned here: +// AC-B1 local runs are listed with status, current step and trace +// outcome/retention; --format json emits a parseable index with +// the required row fields. +// AC-B2 remote-only runs (parked from another clone) appear with status +// read from the ref; runs present locally and remotely are marked +// synced and keep local detail. +// AC-B3 graceful degradation: an unreachable remote degrades to a +// local-only board (warning, exit 0); a ref whose tree lacks +// state.json is skipped and counted, never fatal. +// AC-B4 the remote fetch never overwrites local refs/factory-runs/* +// (namespaced fetch destination). + +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, rmSync, writeFileSync, mkdirSync, readFileSync, existsSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, dirname } from "node:path"; +import { execFileSync, spawnSync } from "node:child_process"; +import { fileURLToPath } from "node:url"; +import { stateStart, stateAdvance, statePause } from "../src/workflow/state.mjs"; +import { parkRun } from "../src/workflow/refs.mjs"; +import { buildBoardIndex } from "../src/workflow/board.mjs"; + +const HERE = dirname(fileURLToPath(import.meta.url)); +const CLI = join(HERE, "..", "bin", "adlc-cli.mjs"); + +const temps = []; +function tempDir(prefix) { + const d = mkdtempSync(join(tmpdir(), prefix)); + temps.push(d); + return d; +} +process.on("exit", () => { + for (const d of temps) { + try { rmSync(d, { recursive: true, force: true }); } catch {} + } +}); + +function git(cwd, ...args) { + return execFileSync("git", args, { cwd, encoding: "utf-8" }).trim(); +} + +function write(dir, rel, content) { + const abs = join(dir, rel); + mkdirSync(dirname(abs), { recursive: true }); + writeFileSync(abs, content, "utf-8"); +} + +function configure(dir) { + git(dir, "config", "user.email", "t@t.local"); + git(dir, "config", "user.name", "t"); + git(dir, "config", "commit.gpgsign", "false"); +} + +function repo({ remote = false } = {}) { + const dir = tempDir("board-repo-"); + git(dir, "init", "-q", "-b", "main"); + configure(dir); + write(dir, ".gitignore", ".adlc/workflows/\n"); + write(dir, "README.md", "base\n"); + git(dir, "add", "-A"); + git(dir, "commit", "-q", "-m", "base"); + let bare = null; + if (remote) { + bare = tempDir("board-bare-"); + git(bare, "init", "-q", "--bare", "-b", "main"); + git(dir, "remote", "add", "origin", bare); + git(dir, "push", "-q", "origin", "main"); + } + return { dir, bare }; +} + +function workflowFile({ gate = false } = {}) { + const path = join(tempDir("board-wf-"), "workflow.yml"); + const gateStep = gate + ? ` - id: approve + type: gate + message: "Approve?" + options: [approve, reject] + on_reject: abort + verdict_input: verdict +` + : ""; + writeFileSync(path, `schema_version: "1.0" +workflow: + id: board-wf + name: Board + version: "1.0.0" +inputs: + verdict: {type: string, enum: ["", approve, reject]} + issue_ref: {type: string, default: ""} +steps: + - id: one + type: shell + run: "echo one" +${gateStep} - id: two + type: shell + run: "echo two" +`, "utf-8"); + return path; +} + +function runDir(dir, runId) { + return join(dir, ".adlc", "workflows", "runs", runId); +} + +function byId(rows) { + return new Map(rows.map((r) => [r.run_id, r])); +} + +// ── AC-B1: local runs listed with detail; JSON contract ────────────────── + +test("AC-B1: board lists local runs with status, step and trace outcome", async () => { + const { dir } = repo(); + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "b1-run", inputs: { issue_ref: "issue-7" } }); + await stateAdvance({ projectRoot: dir, runId: "b1-run", stepId: "one", status: "failed", error: "boom" }); + + const board = buildBoardIndex({ projectRoot: dir, remote: "origin" }); + // No origin remote configured here — fetch fails softly (AC-B3 contract); + // AC-B1 pins the local row detail regardless. + assert.ok(board.remoteError, "no-remote repo must degrade, not throw"); + const row = byId(board.runs).get("b1-run"); + assert.ok(row, "local run must be listed"); + assert.equal(row.source, "local"); + assert.equal(row.status, "failed"); + assert.equal(row.workflow_id, "board-wf"); + assert.equal(row.outcome, "failed"); + assert.equal(row.retention_class, "full"); + assert.equal(row.issue_ref, "issue-7"); +}); + +test("AC-B1: --format json emits a parseable index with required fields", async () => { + const { dir } = repo(); + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "b1-json" }); + + const cli = spawnSync(process.execPath, [CLI, "workflow", "board", "--format", "json"], { + cwd: dir, + encoding: "utf-8", + }); + assert.equal(cli.status, 0, `board --format json must exit 0 (stderr: ${cli.stderr})`); + const doc = JSON.parse(cli.stdout); + assert.ok(Array.isArray(doc.runs)); + const row = byId(doc.runs).get("b1-json"); + assert.ok(row, "run row must be in the JSON index"); + for (const field of ["run_id", "source", "status", "workflow_id", "updated_at"]) { + assert.ok(field in row, `row must carry ${field}`); + } +}); + +// ── AC-B2: remote-only runs; sync marking ──────────────────────────────── + +test("AC-B2: a second clone sees a remote-parked run with status from the ref", async () => { + const { dir, bare } = repo({ remote: true }); + await stateStart({ projectRoot: dir, workflowSource: workflowFile({ gate: true }), runId: "b2-remote" }); + await stateAdvance({ projectRoot: dir, runId: "b2-remote", stepId: "one", status: "completed" }); + await statePause({ projectRoot: dir, runId: "b2-remote", stepId: "approve" }); + const handle = join(tempDir("board-handle-"), "handle.json"); + writeFileSync(handle, JSON.stringify({ channel: "C1", thread_ts: "1.0" }), "utf-8"); + parkRun(dir, "b2-remote", { handleFile: handle, remote: "origin" }); + + const b = join(tempDir("board-clone-"), "b"); + execFileSync("git", ["clone", "-q", bare, b]); + configure(b); + + const board = buildBoardIndex({ projectRoot: b, remote: "origin" }); + const row = byId(board.runs).get("b2-remote"); + assert.ok(row, "remote-parked run must be listed in a clone with no local runs"); + assert.equal(row.source, "remote"); + assert.equal(row.status, "paused"); + assert.equal(row.current_step_id, "approve"); + assert.equal(row.outcome, "paused"); + assert.match(row.remote_sha, /^[0-9a-f]{40}$/, "remote row carries the ref sha"); +}); + +test("AC-B2: a run present locally and remotely is marked synced and keeps local detail", async () => { + const { dir, bare } = repo({ remote: true }); + await stateStart({ projectRoot: dir, workflowSource: workflowFile({ gate: true }), runId: "b2-sync" }); + await stateAdvance({ projectRoot: dir, runId: "b2-sync", stepId: "one", status: "completed" }); + await statePause({ projectRoot: dir, runId: "b2-sync", stepId: "approve" }); + const handle = join(tempDir("board-handle-"), "handle.json"); + writeFileSync(handle, JSON.stringify({ channel: "C1", thread_ts: "1.0" }), "utf-8"); + parkRun(dir, "b2-sync", { handleFile: handle, remote: "origin" }); + + // Same clone that ran it: local state exists AND the ref is on the remote. + const board = buildBoardIndex({ projectRoot: dir, remote: "origin" }); + const row = byId(board.runs).get("b2-sync"); + assert.ok(row); + assert.equal(row.source, "both"); + assert.equal(row.status, "paused"); + assert.match(row.remote_sha, /^[0-9a-f]{40}$/, "synced row carries the remote sha"); +}); + +// ── AC-B3: graceful degradation ─────────────────────────────────────────── + +test("AC-B3: unreachable remote degrades to a local-only board with a warning", async () => { + const { dir } = repo(); + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "b3-local" }); + git(dir, "remote", "add", "origin", join(tempDir("board-dead-"), "nosuch.git")); + + const board = buildBoardIndex({ projectRoot: dir, remote: "origin" }); + assert.ok(board.remoteError, "remoteError must be set"); + const row = byId(board.runs).get("b3-local"); + assert.ok(row, "local run still listed"); + assert.equal(row.source, "local"); + + const cli = spawnSync(process.execPath, [CLI, "workflow", "board"], { + cwd: dir, + encoding: "utf-8", + }); + assert.equal(cli.status, 0, "board must exit 0 when the remote is unreachable"); + assert.ok((cli.stdout + cli.stderr).includes("b3-local"), "table still renders local runs"); + assert.ok((cli.stdout + cli.stderr).toLowerCase().includes("remote"), "a remote warning is shown"); +}); + +test("AC-B3: a ref without state.json is skipped and counted, never fatal", async () => { + const { dir, bare } = repo({ remote: true }); + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "b3-good" }); + await stateAdvance({ projectRoot: dir, runId: "b3-good", stepId: "one", status: "failed", error: "x" }); + + // A garbage "run ref": a commit whose tree has no state.json. + const tree = git(dir, "mktree", ""); + const commit = git(dir, "commit-tree", tree, "-m", "garbage"); + git(dir, "push", "-q", bare, `+${commit}:refs/factory-runs/b3-garbage`); + + const board = buildBoardIndex({ projectRoot: dir, remote: "origin" }); + assert.equal(board.remoteError, null); + assert.ok(board.skippedRemote >= 1, "garbage ref must be counted as skipped"); + assert.ok(byId(board.runs).get("b3-good"), "good run still listed"); + assert.ok(!byId(board.runs).has("b3-garbage"), "garbage ref must not appear"); +}); + +// ── AC-B4: namespaced fetch never touches local refs/factory-runs ──────── + +test("AC-B4: the remote fetch lands in refs/remotes//, not refs/factory-runs", async () => { + const { dir, bare } = repo({ remote: true }); + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "b4-local-only" }); + // Local ref pushed by syncRunRef belongs to the local namespace already. + + const b = join(tempDir("board-clone-"), "b"); + execFileSync("git", ["clone", "-q", bare, b]); + configure(b); + + buildBoardIndex({ projectRoot: b, remote: "origin" }); + const remotes = git(b, "for-each-ref", "--format=%(refname)", "refs/remotes/origin/factory-runs/"); + assert.ok( + remotes.split("\n").includes("refs/remotes/origin/factory-runs/b4-local-only"), + "fetched into refs/remotes namespace", + ); + const localRefs = git(b, "for-each-ref", "--format=%(refname)", "refs/factory-runs/"); + assert.ok(!localRefs.includes("refs/factory-runs/b4-local-only"), "local refs/factory-runs untouched"); +}); + +// ── security: --remote is never a git option ────────────────────────────── +// +// A remote beginning with "-" is parsed by git as an option, not a +// positional remote: `git fetch --upload-pack= ` runs +// through the shell. The board must reject such values before any git +// call (same checkRemote guard park/restore use), not execute them. + +test("security: --upload-pack remote is rejected, never executed (buildBoardIndex)", async () => { + const { dir } = repo(); + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "sec-run" }); + const marker = join(tempDir("board-sec-"), "PWNED"); + + assert.throws( + () => buildBoardIndex({ projectRoot: dir, remote: `--upload-pack=touch ${marker}` }), + /invalid remote/, + "buildBoardIndex must throw on an option-shaped remote", + ); + assert.ok(!existsSync(marker), "injection payload must NOT have executed"); +}); + +test("security: leading-dash remote is rejected by buildBoardIndex", async () => { + const { dir } = repo(); + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "sec-dash" }); + + assert.throws( + () => buildBoardIndex({ projectRoot: dir, remote: "--sort=evil" }), + /invalid remote/, + ); +}); + +test("security: CLI --remote= exits 1 without executing", async () => { + const { dir } = repo(); + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "sec-cli" }); + const marker = join(tempDir("board-sec-cli-"), "PWNED"); + + // Inline "--remote=value" form: bypasses the command layer's leading-dash + // check in extractFlagValue, so the guard must hold in buildBoardIndex. + const cli = spawnSync(process.execPath, [CLI, "workflow", "board", `--remote=--upload-pack=touch ${marker}`], { + cwd: dir, + encoding: "utf-8", + }); + assert.notEqual(cli.status, 0, "board must exit non-zero on an option-shaped remote"); + assert.match(cli.stderr, /invalid remote/, "usage error must name the invalid remote"); + assert.ok(!existsSync(marker), "injection payload must NOT have executed"); +}); + +test("security: CLI space-separated --remote is safe", async () => { + const { dir } = repo(); + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "sec-cli2" }); + const marker = join(tempDir("board-sec-cli2-"), "PWNED"); + + // Space-separated form: extractFlagValue drops leading-dash values, so the + // remote falls back to "origin" — nothing option-shaped reaches git. + const cli = spawnSync(process.execPath, [CLI, "workflow", "board", "--remote", `--upload-pack=touch ${marker}`], { + cwd: dir, + encoding: "utf-8", + }); + assert.equal(cli.status, 0, "space-separated option-shaped remote falls back to origin (unreachable ok)"); + assert.ok(!existsSync(marker), "injection payload must NOT have executed"); +}); diff --git a/tests/workflow-run-sync.test.mjs b/tests/workflow-run-sync.test.mjs new file mode 100644 index 0000000..d567974 --- /dev/null +++ b/tests/workflow-run-sync.test.mjs @@ -0,0 +1,442 @@ +// Phase 0 — durable run transport (ADR-475/477/478). +// +// Contract pinned here: +// AC-1 stateAdvance pushes refs/factory-runs/ to origin; the remote +// state.json reflects the advanced step. +// AC-2 ADLC_WORKFLOW_PUSH_INTERVAL throttles advance pushes; 0 forces them. +// AC-3 parkRun redacts secrets out of the run dir before pushing: the +// remote blobs and the local files carry "***", never the value. +// AC-4 the pushed tree excludes lease.json and .push-ts (ADR-477); a +// restored clone is claimable and resumes. +// AC-5 a missing/unreachable remote never fails an advance (fail-soft). + +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, rmSync, writeFileSync, readFileSync, mkdirSync, existsSync, chmodSync, symlinkSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, dirname, resolve } from "node:path"; +import { execFileSync } from "node:child_process"; +import { fileURLToPath } from "node:url"; +import { WorkflowEngine, RunState, RunStatus } from "../src/workflow/engine.mjs"; +import { STEP_REGISTRY } from "../src/workflow/registry.mjs"; +import { stateStart, stateAdvance, statePause } from "../src/workflow/state.mjs"; +import { parkRun, restoreRun, syncRunRef } from "../src/workflow/refs.mjs"; + +const CLI_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), ".."); + +const temps = []; +function tempDir(prefix) { + const d = mkdtempSync(join(tmpdir(), prefix)); + temps.push(d); + return d; +} +process.on("exit", () => { + for (const d of temps) { + try { rmSync(d, { recursive: true, force: true }); } catch {} + } +}); + +function git(cwd, ...args) { + return execFileSync("git", args, { cwd, encoding: "utf-8" }).trim(); +} + +function write(dir, rel, content) { + const abs = join(dir, rel); + mkdirSync(dirname(abs), { recursive: true }); + writeFileSync(abs, content, "utf-8"); +} + +function configure(dir) { + git(dir, "config", "user.email", "t@t.local"); + git(dir, "config", "user.name", "t"); + git(dir, "config", "commit.gpgsign", "false"); +} + +function commitAll(dir, msg) { + git(dir, "add", "-A"); + git(dir, "commit", "-q", "-m", msg); + return git(dir, "rev-parse", "HEAD"); +} + +// A repo with run dirs git-ignored; origin (bare) wired when asked. +function repo({ remote = false } = {}) { + const dir = tempDir("sync-repo-"); + git(dir, "init", "-q", "-b", "main"); + configure(dir); + write(dir, ".gitignore", ".adlc/workflows/\n"); + write(dir, "README.md", "base\n"); + commitAll(dir, "base"); + let bare = null; + if (remote) { + bare = tempDir("sync-bare-"); + git(bare, "init", "-q", "--bare", "-b", "main"); + git(dir, "remote", "add", "origin", bare); + git(dir, "push", "-q", "origin", "main"); + } + return { dir, bare }; +} + +function cloneOf(bare) { + const b = join(tempDir("sync-clone-"), "b"); + execFileSync("git", ["clone", "-q", bare, b]); + configure(b); + return b; +} + +function workflowFile() { + const path = join(tempDir("sync-wf-"), "workflow.yml"); + writeFileSync(path, `schema_version: "1.0" +workflow: + id: sync-wf + name: Sync + version: "1.0.0" +steps: + - id: one + type: shell + run: "echo one" + - id: two + type: shell + run: "echo two" +`, "utf-8"); + return path; +} + +function runDir(dir, runId) { + return join(dir, ".adlc", "workflows", "runs", runId); +} + +// Run a test body with a temporary ADLC_WORKFLOW_PUSH_INTERVAL value. +async function withPushInterval(seconds, fn) { + const prev = process.env.ADLC_WORKFLOW_PUSH_INTERVAL; + process.env.ADLC_WORKFLOW_PUSH_INTERVAL = String(seconds); + try { + return await fn(); + } finally { + if (prev === undefined) delete process.env.ADLC_WORKFLOW_PUSH_INTERVAL; + else process.env.ADLC_WORKFLOW_PUSH_INTERVAL = prev; + } +} + +function remoteRefSha(bare, runId) { + const out = git(bare, "rev-parse", `refs/factory-runs/${runId}`); + return out; +} + +function remoteShow(bare, runId, path) { + return git(bare, "show", `refs/factory-runs/${runId}:${path}`); +} + +function remoteTree(bare, runId) { + return git(bare, "ls-tree", "-r", "--name-only", `refs/factory-runs/${runId}`).split("\n").filter(Boolean); +} + +// ── AC-1: advance pushes to origin ──────────────────────────────────────── + +test("AC-1: stateAdvance pushes the run ref to origin with the advanced state", async () => { + const { dir, bare } = repo({ remote: true }); + await withPushInterval(0, async () => { + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "ac1" }); + assert.ok(remoteRefSha(bare, "ac1"), "start must push the run ref"); + await stateAdvance({ projectRoot: dir, runId: "ac1", stepId: "one", status: "completed" }); + const remote = JSON.parse(remoteShow(bare, "ac1", "state.json")); + assert.equal(remote.current_step_index, 1); + assert.equal(remote.step_results.one.status, "completed"); + }); +}); + +// ── AC-2: throttle ──────────────────────────────────────────────────────── + +test("AC-2: advance pushes are throttled inside the interval and forced at 0", async () => { + const { dir, bare } = repo({ remote: true }); + await withPushInterval(3600, async () => { + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "ac2" }); + const afterStart = remoteRefSha(bare, "ac2"); + await stateAdvance({ projectRoot: dir, runId: "ac2", stepId: "one", status: "completed" }); + assert.equal(remoteRefSha(bare, "ac2"), afterStart, "advance inside the interval must not push"); + const local = JSON.parse(readFileSync(join(runDir(dir, "ac2"), "state.json"), "utf-8")); + assert.equal(local.current_step_index, 1, "local state still advances"); + }); + await withPushInterval(0, async () => { + await stateAdvance({ projectRoot: dir, runId: "ac2", stepId: "two", status: "completed" }); + const remote = JSON.parse(remoteShow(bare, "ac2", "state.json")); + assert.equal(remote.status, RunStatus.COMPLETED); + }); +}); + +// ── AC-3: park-time redaction ───────────────────────────────────────────── + +test("AC-3: parkRun redacts secret values from the local run dir and the pushed ref", async () => { + const SECRET = "supersecretvalue123456"; + const { dir, bare } = repo({ remote: true }); + const prev = process.env.TEST_TOKEN; + process.env.TEST_TOKEN = SECRET; + try { + await withPushInterval(0, async () => { + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "ac3" }); + await stateAdvance({ projectRoot: dir, runId: "ac3", stepId: "one", status: "completed" }); + await statePause({ projectRoot: dir, runId: "ac3", stepId: "two" }); + + // Seed the secret the way a real leak would: into the persisted log and state. + const logPath = join(runDir(dir, "ac3"), "log.jsonl"); + const priorLog = existsSync(logPath) ? readFileSync(logPath, "utf-8") : ""; + writeFileSync(logPath, priorLog + `{"event":"leak","note":"token ${SECRET}"}\n`, "utf-8"); + const statePath = join(runDir(dir, "ac3"), "state.json"); + const state = JSON.parse(readFileSync(statePath, "utf-8")); + state.error = `leaked ${SECRET}`; + writeFileSync(statePath, JSON.stringify(state, null, 2), "utf-8"); + + const handle = join(tempDir("sync-handle-"), "handle.json"); + writeFileSync(handle, JSON.stringify({ channel: "C1", thread_ts: "1.0" }), "utf-8"); + parkRun(dir, "ac3", { handleFile: handle, remote: "origin" }); + + for (const rel of ["log.jsonl", "state.json"]) { + const localText = readFileSync(join(runDir(dir, "ac3"), rel), "utf-8"); + assert.ok(!localText.includes(SECRET), `local ${rel} must be redacted`); + assert.ok(localText.includes("***"), `local ${rel} must carry the mask`); + const remoteText = remoteShow(bare, "ac3", rel); + assert.ok(!remoteText.includes(SECRET), `remote ${rel} must not leak`); + assert.ok(remoteText.includes("***"), `remote ${rel} must carry the mask`); + } + }); + } finally { + if (prev === undefined) delete process.env.TEST_TOKEN; + else process.env.TEST_TOKEN = prev; + } +}); + +// ── AC-4: machine-local files stay out of the ref; restore is claimable ─── + +test("AC-4: the pushed tree excludes lease.json and .push-ts; restore resumes", async () => { + const { dir, bare } = repo({ remote: true }); + await withPushInterval(0, async () => { + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "ac4" }); + await stateAdvance({ projectRoot: dir, runId: "ac4", stepId: "one", status: "completed" }); + await statePause({ projectRoot: dir, runId: "ac4", stepId: "two" }); + + // A live foreign lease + the throttle stamp exist locally at park time. + write(join(dir, ".adlc", "workflows", "runs", "ac4"), "lease.json", JSON.stringify({ + run_id: "ac4", holder: "otherhost:4242", heartbeat_ts: Date.now(), ttl_seconds: 3600, pid: 4242, hostname: "otherhost", + })); + assert.ok(existsSync(join(runDir(dir, "ac4"), ".push-ts")), "sync writes the throttle stamp"); + + const handle = join(tempDir("sync-handle-"), "handle.json"); + writeFileSync(handle, JSON.stringify({ channel: "C1", thread_ts: "1.0" }), "utf-8"); + parkRun(dir, "ac4", { handleFile: handle, remote: "origin" }); + + const tree = remoteTree(bare, "ac4"); + assert.ok(!tree.includes("lease.json"), `lease.json must not cross machines (tree: ${tree.join(", ")})`); + assert.ok(!tree.includes(".push-ts"), ".push-ts must not cross machines"); + + const b = cloneOf(bare); + restoreRun(b, "ac4", { remote: "origin" }); + assert.ok(!existsSync(join(runDir(b, "ac4"), "lease.json")), "restored run must not inherit a foreign lease"); + + const engine = new WorkflowEngine(b); + const state = await engine.resume("ac4", null, STEP_REGISTRY); + assert.equal(state.status, RunStatus.COMPLETED, "restored run must resume without a lease conflict"); + }); +}); + +// ── AC-5: fail-soft without a remote ────────────────────────────────────── + +test("AC-5: advance without an origin still succeeds (fail-soft push)", async () => { + const { dir } = repo({ remote: false }); + await withPushInterval(0, async () => { + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "ac5" }); + const state = await stateAdvance({ projectRoot: dir, runId: "ac5", stepId: "one", status: "completed" }); + assert.equal(state.currentStepIndex, 1); + assert.ok(existsSync(join(runDir(dir, "ac5"), "state.json"))); + }); +}); + +// ── I-1: transition pushes are redacted, not just park ───────────────────── + +test("I-1: transition push masks secret-valued inputs on the remote from run start", async () => { + const SECRET = "supersecretvalue123456"; + const { dir, bare } = repo({ remote: true }); + const wf = join(tempDir("sync-wf-"), "workflow.yml"); + writeFileSync(wf, `schema_version: "1.0" +workflow: + id: sync-wf-in + name: SyncIn + version: "1.0.0" +inputs: + token: + type: string +steps: + - id: one + type: shell + run: "echo one" +`, "utf-8"); + const prev = process.env.TEST_TOKEN; + process.env.TEST_TOKEN = SECRET; + try { + await withPushInterval(0, async () => { + await stateStart({ projectRoot: dir, workflowSource: wf, runId: "i1", inputs: { token: SECRET } }); + const remoteInputs = remoteShow(bare, "i1", "inputs.json"); + assert.ok(!remoteInputs.includes(SECRET), "remote inputs.json must not leak the secret on the first push"); + assert.ok(remoteInputs.includes("***"), "remote inputs.json must carry the mask"); + }); + } finally { + if (prev === undefined) delete process.env.TEST_TOKEN; + else process.env.TEST_TOKEN = prev; + } +}); + +// ── I-2: unreadable throttle stamp is treated as absent (fail-soft) ──────── + +test("I-2: unreadable .push-ts (EISDIR) does not throw and the transition still pushes", async () => { + const { dir, bare } = repo({ remote: true }); + await withPushInterval(0, async () => { + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "i2" }); + }); + const stamp = join(runDir(dir, "i2"), ".push-ts"); + assert.ok(existsSync(stamp), "start push writes the throttle stamp"); + // Simulate an unreadable stamp cross-platform: chmod 000 has no effect on + // Windows ACLs, but a directory at the stamp path makes readFileSync + // throw EISDIR on Linux, macOS, and Windows alike. + rmSync(stamp); + mkdirSync(stamp); + await withPushInterval(3600, async () => { + // Must not throw (EACCES on stamp read) and must still push: an + // unreadable stamp counts as absent, so the throttle window is over. + const state = await stateAdvance({ projectRoot: dir, runId: "i2", stepId: "one", status: "completed" }); + assert.equal(state.currentStepIndex, 1); + const remote = JSON.parse(remoteShow(bare, "i2", "state.json")); + assert.equal(remote.current_step_index, 1, "advance must push when the stamp is unreadable"); + }); +}); + +// ── I-3: symlinks in the run dir are skipped, not followed ───────────────── + +test("I-3: symlinks inside the run dir are not followed, not pushed, not written through", async () => { + const SECRET = "supersecretvalue123456"; + const { dir, bare } = repo({ remote: true }); + const prev = process.env.TEST_TOKEN; + process.env.TEST_TOKEN = SECRET; + try { + await withPushInterval(0, async () => { + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "i3" }); + const rd = runDir(dir, "i3"); + const outside = tempDir("sync-outside-"); + write(outside, "secret.txt", `token=${SECRET}\n`); + write(join(outside, "nested"), "deep.txt", `deep ${SECRET}\n`); + symlinkSync(join(outside, "secret.txt"), join(rd, "leak-file")); + symlinkSync(join(outside, "nested"), join(rd, "leak-dir")); + symlinkSync(join(outside, "missing"), join(rd, "dangling")); + write(rd, "marker.txt", "present\n"); + // Must not throw on the dangling symlink; must push a clean tree. + const pushed = syncRunRef(dir, "i3", rd, { minIntervalSeconds: 0 }); + assert.equal(pushed, true, "syncRunRef must succeed despite the dangling symlink"); + const tree = remoteTree(bare, "i3"); + assert.ok(tree.includes("marker.txt"), "the push must actually happen (marker file visible on the remote)"); + assert.ok(!tree.includes("leak-file"), "file symlink must not enter the pushed tree"); + assert.ok(!tree.some((p) => p === "leak-dir" || p.startsWith("leak-dir/")), "dir symlink must not be traversed into the pushed tree"); + assert.ok(!tree.includes("dangling"), "dangling symlink must not enter the pushed tree"); + // Redaction must not write through the symlinks into outside files. + assert.ok(!readFileSync(join(outside, "secret.txt"), "utf-8").includes("***"), "redaction must not write through the file symlink"); + assert.ok(!readFileSync(join(outside, "nested", "deep.txt"), "utf-8").includes("***"), "redaction must not traverse the dir symlink"); + }); + } finally { + if (prev === undefined) delete process.env.TEST_TOKEN; + else process.env.TEST_TOKEN = prev; + } +}); + +// ── I-4: transition redaction is staged, local run dir stays raw ────────── + +test("I-4a: transition sync masks the remote but leaves local inputs.json raw across pause", async () => { + const SECRET = "supersecretvalue123456"; + const { dir, bare } = repo({ remote: true }); + const wf = join(tempDir("sync-wf-"), "workflow.yml"); + writeFileSync(wf, `schema_version: "1.0" +workflow: + id: sync-wf-in4 + name: SyncIn4 + version: "1.0.0" +inputs: + token: + type: string +steps: + - id: one + type: shell + run: "echo one" + - id: two + type: shell + run: "echo two" +`, "utf-8"); + const prev = process.env.TEST_TOKEN; + process.env.TEST_TOKEN = SECRET; + try { + await withPushInterval(0, async () => { + await stateStart({ projectRoot: dir, workflowSource: wf, runId: "i4a", inputs: { token: SECRET } }); + const localAfterStart = JSON.parse(readFileSync(join(runDir(dir, "i4a"), "inputs.json"), "utf-8")); + assert.equal(localAfterStart.inputs.token, SECRET, "local inputs.json must stay raw after the start sync (resume depends on it)"); + const remoteInputs = remoteShow(bare, "i4a", "inputs.json"); + assert.ok(!remoteInputs.includes(SECRET), "remote inputs.json must be masked"); + assert.ok(remoteInputs.includes("***"), "remote inputs.json must carry the mask"); + await statePause({ projectRoot: dir, runId: "i4a", stepId: "two" }); + const localAfterPause = JSON.parse(readFileSync(join(runDir(dir, "i4a"), "inputs.json"), "utf-8")); + assert.equal(localAfterPause.inputs.token, SECRET, "local inputs.json must stay raw after the pause sync"); + // Resume-level check: a resume that does not re-pass inputs reads + // inputs.json — it must still see the raw secret value. + const state = RunState.load("i4a", dir); + assert.deepEqual(state.inputs, { token: SECRET }, "loaded run state must carry the raw input for resume"); + }); + } finally { + if (prev === undefined) delete process.env.TEST_TOKEN; + else process.env.TEST_TOKEN = prev; + } +}); + +test("I-4b: redaction failure skips the push entirely (fail-closed), no throw, remote unchanged", async () => { + const SECRET = "supersecretvalue123456"; + const { dir, bare } = repo({ remote: true }); + const wf = join(tempDir("sync-wf-"), "workflow.yml"); + writeFileSync(wf, `schema_version: "1.0" +workflow: + id: sync-wf-in4b + name: SyncIn4b + version: "1.0.0" +inputs: + token: + type: string +steps: + - id: one + type: shell + run: "echo one" +`, "utf-8"); + const prev = process.env.TEST_TOKEN; + process.env.TEST_TOKEN = SECRET; + try { + await withPushInterval(0, async () => { + await stateStart({ projectRoot: dir, workflowSource: wf, runId: "i4b", inputs: { token: SECRET } }); + // Baseline remote state exists and is masked. + const before = remoteRefSha(bare, "i4b"); + // Re-secret the local file so the staged copy needs a rewrite, then + // force redaction to fail portably: a read-only inputs.json (chmod 444 + // maps to the Windows read-only attribute) makes the in-place rewrite + // throw inside redactRunDir. + const localInputs = join(runDir(dir, "i4b"), "inputs.json"); + writeFileSync(localInputs, JSON.stringify({ inputs: { token: SECRET } }) + "\n", "utf-8"); + chmodSync(localInputs, 0o444); + let threw = null; + try { + syncRunRef(dir, "i4b", runDir(dir, "i4b"), { minIntervalSeconds: 0 }); + } catch (exc) { + threw = exc; + } + assert.equal(threw, null, "syncRunRef must not throw when redaction fails"); + assert.equal(remoteRefSha(bare, "i4b"), before, "remote ref must be unchanged when redaction fails (no unredacted push)"); + }); + } finally { + try { chmodSync(join(runDir(dir, "i4b"), "inputs.json"), 0o666); } catch {} + if (prev === undefined) delete process.env.TEST_TOKEN; + else process.env.TEST_TOKEN = prev; + } +}); + +// Keep CLI_ROOT referenced so the test fails loudly if the worktree moves. +test("worktree layout sanity", () => { + assert.ok(existsSync(join(CLI_ROOT, "bin", "adlc-cli.mjs"))); +}); diff --git a/tests/workflow-trace.test.mjs b/tests/workflow-trace.test.mjs new file mode 100644 index 0000000..29a1982 --- /dev/null +++ b/tests/workflow-trace.test.mjs @@ -0,0 +1,452 @@ +// Phase 1 — trace bundle v1 (ADR-490), fed by existing engine/run-log events. +// +// Contract pinned here: +// AC-T1 run start creates trace/manifest.json, trace/events.jsonl and +// trace/artifacts.json with a valid manifest. +// AC-T2 transitions append ADR-362 envelopes with ADR-364 canonical types +// and the original event name under payload.adlc. +// AC-T3 secrets never reach events.jsonl or manifest.json. +// AC-T4 retention is fail-closed: failed runs keep full events, successful +// runs keep only the manifest unless a sampling policy says otherwise. +// AC-T5 artifacts.json is content-addressed and validates. +// AC-T6 trace files travel in the run ref (park/restore). + +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, rmSync, writeFileSync, readFileSync, mkdirSync, existsSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, dirname } from "node:path"; +import { execFileSync } from "node:child_process"; +import { createHash } from "node:crypto"; +import { WorkflowEngine, RunStatus } from "../src/workflow/engine.mjs"; +import { STEP_REGISTRY } from "../src/workflow/registry.mjs"; +import { stateStart, stateAdvance, statePause } from "../src/workflow/state.mjs"; +import { parkRun, restoreRun } from "../src/workflow/refs.mjs"; +import { + TRACE_SCHEMA_VERSION, + appendTraceEvent, + recordArtifact, + tracePaths, +} from "../src/workflow/trace.mjs"; + +const temps = []; +function tempDir(prefix) { + const d = mkdtempSync(join(tmpdir(), prefix)); + temps.push(d); + return d; +} +process.on("exit", () => { + for (const d of temps) { + try { rmSync(d, { recursive: true, force: true }); } catch {} + } +}); + +function git(cwd, ...args) { + return execFileSync("git", args, { cwd, encoding: "utf-8" }).trim(); +} + +function write(dir, rel, content) { + const abs = join(dir, rel); + mkdirSync(dirname(abs), { recursive: true }); + writeFileSync(abs, content, "utf-8"); +} + +function configure(dir) { + git(dir, "config", "user.email", "t@t.local"); + git(dir, "config", "user.name", "t"); + git(dir, "config", "commit.gpgsign", "false"); +} + +function commitAll(dir, msg) { + git(dir, "add", "-A"); + git(dir, "commit", "-q", "-m", msg); + return git(dir, "rev-parse", "HEAD"); +} + +function repo({ remote = false } = {}) { + const dir = tempDir("trace-repo-"); + git(dir, "init", "-q", "-b", "main"); + configure(dir); + write(dir, ".gitignore", ".adlc/workflows/\n"); + write(dir, "README.md", "base\n"); + write(dir, "skills-lock.json", JSON.stringify({ skills: [] }) + "\n"); + write(dir, ".mcp.json", JSON.stringify({ mcpServers: {} }) + "\n"); + commitAll(dir, "base"); + let bare = null; + if (remote) { + bare = tempDir("trace-bare-"); + git(bare, "init", "-q", "--bare", "-b", "main"); + git(dir, "remote", "add", "origin", bare); + git(dir, "push", "-q", "origin", "main"); + } + return { dir, bare }; +} + +function cloneOf(bare) { + const b = join(tempDir("trace-clone-"), "b"); + execFileSync("git", ["clone", "-q", bare, b]); + configure(b); + return b; +} + +function workflowFile({ gate = false } = {}) { + const path = join(tempDir("trace-wf-"), "workflow.yml"); + const gateStep = gate + ? ` - id: approve + type: gate + message: "Approve?" + options: [approve, reject] + on_reject: abort + verdict_input: verdict +` + : ""; + writeFileSync(path, `schema_version: "1.0" +workflow: + id: trace-wf + name: Trace + version: "1.0.0" +inputs: + verdict: {type: string, enum: ["", approve, reject]} + issue_ref: {type: string, default: ""} +steps: + - id: one + type: shell + run: "echo one" +${gateStep} - id: two + type: shell + run: "echo two" +`, "utf-8"); + return path; +} + +function runDir(dir, runId) { + return join(dir, ".adlc", "workflows", "runs", runId); +} + +function readJson(path) { + return JSON.parse(readFileSync(path, "utf-8")); +} + +function readEvents(runDirAbs) { + const path = tracePaths(runDirAbs).events; + if (!existsSync(path)) return []; + return readFileSync(path, "utf-8") + .split("\n") + .filter(Boolean) + .map((line) => JSON.parse(line)); +} + +async function withEnv(name, value, fn) { + const prev = process.env[name]; + process.env[name] = String(value); + try { + return await fn(); + } finally { + if (prev === undefined) delete process.env[name]; + else process.env[name] = prev; + } +} + +// ── AC-T1: run start creates the bundle ─────────────────────────────────── + +test("AC-T1: stateStart creates a valid trace manifest, events file and artifacts file", async () => { + const { dir } = repo(); + const state = await stateStart({ + projectRoot: dir, + workflowSource: workflowFile(), + runId: "t1", + inputs: { issue_ref: "issue-1" }, + }); + const rd = runDir(dir, "t1"); + const paths = tracePaths(rd); + assert.ok(existsSync(paths.manifest), "manifest.json must exist"); + assert.ok(existsSync(paths.events), "events.jsonl must exist"); + assert.ok(existsSync(paths.artifacts), "artifacts.json must exist"); + + const manifest = readJson(paths.manifest); + assert.equal(manifest.schema_version, TRACE_SCHEMA_VERSION); + assert.equal(manifest.run_id, "t1"); + assert.equal(manifest.workflow_id, state.workflowId); + assert.equal(manifest.outcome, "running"); + assert.equal(manifest.retention_class, "pending"); + assert.equal(manifest.issue_ref, "issue-1"); + assert.match(manifest.config.skill_lock_hash, /^[0-9a-f]{64}$/); + assert.match(manifest.config.mcp_config_hash, /^[0-9a-f]{64}$/); + + const artifacts = readJson(paths.artifacts); + assert.equal(artifacts.schema_version, TRACE_SCHEMA_VERSION); + assert.deepEqual(artifacts.artifacts, []); + + const events = readEvents(rd); + assert.ok(events.length >= 1, "run_started must be recorded"); + assert.equal(events[0].payload.adlc.event, "run_started"); +}); + +// ── AC-T2: ADR-362 envelopes with canonical types ──────────────────────── + +test("AC-T2: transitions append ADR-362 envelopes with canonical ADR-364 types", async () => { + const { dir } = repo(); + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "t2" }); + await stateAdvance({ projectRoot: dir, runId: "t2", stepId: "one", status: "failed", error: "boom" }); + + const rd = runDir(dir, "t2"); + const events = readEvents(rd); + const canonical = new Set(["message", "tool", "permission_request", "error", "complete", "log"]); + for (const event of events) { + assert.equal(event.schema_version, 1, "envelope schema_version"); + assert.equal(typeof event.agent_id, "string"); + assert.ok(event.agent_id.length > 0, "agent_id must be present"); + assert.ok(!Number.isNaN(Date.parse(event.ts)), "ts must parse"); + assert.ok(canonical.has(event.type), `canonical type, got ${event.type}`); + assert.equal(typeof event.payload, "object"); + assert.equal(typeof event.payload.adlc.event, "string"); + } + assert.ok(events.some((e) => e.payload.adlc.event === "step_advanced" && e.type === "log")); + assert.ok(events.some((e) => e.payload.adlc.event === "run_failed" && e.type === "error")); + + // Mapping of gate and completion names is stable. + const synthetic = join(tempDir("trace-map-"), "run"); + mkdirSync(synthetic, { recursive: true }); + appendTraceEvent(synthetic, { event: "gate_paused", step_id: "g" }); + appendTraceEvent(synthetic, { event: "workflow_finished", status: "completed" }); + const mapped = readEvents(synthetic); + assert.equal(mapped[0].type, "permission_request"); + assert.equal(mapped[1].type, "complete"); +}); + +test("AC-T2: a completed engine run ends with a complete event when retained", async () => { + const { dir } = repo(); + await withEnv("ADLC_TRACE_SUCCESS_SAMPLE_RATE", 1, async () => { + const engine = new WorkflowEngine(dir); + const state = await engine.execute(engine.loadWorkflow(workflowFile()), {}, "t2-engine", STEP_REGISTRY); + assert.equal(state.status, RunStatus.COMPLETED); + const events = readEvents(runDir(dir, "t2-engine")); + assert.ok(events.length > 0); + assert.equal(events.at(-1).type, "complete"); + assert.equal(events.at(-1).payload.adlc.event, "run_completed"); + }); +}); + +// ── AC-T3: secrets never reach the trace ───────────────────────────────── + +test("AC-T3: secrets in logs, step output and issue_ref are masked in the trace", async () => { + const SECRET = "supersecrettracevalue123"; + const { dir } = repo(); + const prev = process.env.TRACE_TEST_TOKEN; + process.env.TRACE_TEST_TOKEN = SECRET; + try { + const state = await stateStart({ + projectRoot: dir, + workflowSource: workflowFile(), + runId: "t3", + inputs: { issue_ref: `https://bot:${SECRET}@example.test/issue/3` }, + }); + const rd = runDir(dir, "t3"); + await state.appendLog({ event: "leak", note: `token ${SECRET}` }); + await stateAdvance({ + projectRoot: dir, + runId: "t3", + stepId: "one", + status: "failed", + output: { stdout: `printed ${SECRET}` }, + error: `failed with ${SECRET}`, + }); + + // Trace files are capture-redacted; other run files are machine-local and + // are redacted at park by redactRunDir (ADR-478). + for (const rel of ["trace/events.jsonl", "trace/manifest.json"]) { + const text = readFileSync(join(rd, rel), "utf-8"); + assert.ok(!text.includes(SECRET), `${rel} must not contain the secret`); + } + const eventsText = readFileSync(tracePaths(rd).events, "utf-8"); + assert.ok(eventsText.includes("***"), "events must carry the mask"); + const manifest = readJson(tracePaths(rd).manifest); + assert.ok(!manifest.issue_ref.includes(SECRET)); + assert.ok(manifest.issue_ref.includes("***")); + } finally { + if (prev === undefined) delete process.env.TRACE_TEST_TOKEN; + else process.env.TRACE_TEST_TOKEN = prev; + } +}); + +// ── AC-T4: fail-closed retention ───────────────────────────────────────── + +test("AC-T4: a failed run keeps full events and marks retention full", async () => { + const { dir } = repo(); + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "t4-fail" }); + await stateAdvance({ projectRoot: dir, runId: "t4-fail", stepId: "one", status: "failed", error: "boom" }); + const rd = runDir(dir, "t4-fail"); + assert.ok(existsSync(tracePaths(rd).events), "failed run keeps events"); + const manifest = readJson(tracePaths(rd).manifest); + assert.equal(manifest.outcome, "failed"); + assert.equal(manifest.retention_class, "full"); + assert.ok(manifest.finished_at); +}); + +test("AC-T4: a completed run keeps only the manifest under the default policy", async () => { + const { dir } = repo(); + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "t4-default" }); + await stateAdvance({ projectRoot: dir, runId: "t4-default", stepId: "one", status: "completed" }); + await stateAdvance({ projectRoot: dir, runId: "t4-default", stepId: "two", status: "completed" }); + const rd = runDir(dir, "t4-default"); + const manifest = readJson(tracePaths(rd).manifest); + assert.equal(manifest.outcome, "completed"); + assert.equal(manifest.retention_class, "manifest-only"); + assert.ok(!existsSync(tracePaths(rd).events), "successful events are pruned by default"); + assert.ok(existsSync(tracePaths(rd).manifest), "manifest is never pruned"); +}); + +test("AC-T4: an explicit sample rate retains successful events", async () => { + const { dir } = repo(); + await withEnv("ADLC_TRACE_SUCCESS_SAMPLE_RATE", 1, async () => { + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "t4-sample" }); + await stateAdvance({ projectRoot: dir, runId: "t4-sample", stepId: "one", status: "completed" }); + await stateAdvance({ projectRoot: dir, runId: "t4-sample", stepId: "two", status: "completed" }); + }); + const rd = runDir(dir, "t4-sample"); + const manifest = readJson(tracePaths(rd).manifest); + assert.equal(manifest.retention_class, "full-sampled"); + assert.ok(existsSync(tracePaths(rd).events), "sampled success keeps events"); +}); + +// ── AC-T5: content-addressed artifacts ─────────────────────────────────── + +test("AC-T5: recordArtifact appends a content-addressed entry and rejects a bad hash", async () => { + const { dir } = repo(); + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "t5" }); + const rd = runDir(dir, "t5"); + write(rd, "evidence/report.txt", "hello trace\n"); + const expected = createHash("sha256").update("hello trace\n").digest("hex"); + + recordArtifact(rd, { + path: "evidence/report.txt", + media_type: "text/plain", + storage_uri: "run://evidence/report.txt", + retention_class: "full", + sensitivity: "internal", + producing_event: "evt-1", + }); + + const artifacts = readJson(tracePaths(rd).artifacts); + assert.equal(artifacts.artifacts.length, 1); + const entry = artifacts.artifacts[0]; + assert.equal(entry.content_sha256, expected); + assert.equal(entry.size, Buffer.byteLength("hello trace\n")); + assert.equal(entry.media_type, "text/plain"); + assert.equal(entry.sensitivity, "internal"); + + assert.throws(() => { + recordArtifact(rd, { + content_sha256: "not-a-hash", + media_type: "text/plain", + size: 1, + storage_uri: "run://x", + retention_class: "full", + sensitivity: "internal", + producing_event: "evt-2", + }); + }, /sha256/i); +}); + +// ── AC-T6: trace files travel in the run ref ───────────────────────────── + +test("AC-T6: park/restore carries trace files into a second clone", async () => { + const { dir, bare } = repo({ remote: true }); + await stateStart({ projectRoot: dir, workflowSource: workflowFile({ gate: true }), runId: "t6" }); + await stateAdvance({ projectRoot: dir, runId: "t6", stepId: "one", status: "completed" }); + await statePause({ projectRoot: dir, runId: "t6", stepId: "approve" }); + + const handle = join(tempDir("trace-handle-"), "handle.json"); + writeFileSync(handle, JSON.stringify({ channel: "C1", thread_ts: "1.0" }), "utf-8"); + parkRun(dir, "t6", { handleFile: handle, remote: "origin" }); + + const tree = git(bare, "ls-tree", "-r", "--name-only", "refs/factory-runs/t6").split("\n").filter(Boolean); + for (const rel of ["trace/manifest.json", "trace/events.jsonl", "trace/artifacts.json"]) { + assert.ok(tree.includes(rel), `${rel} must be in the ref (tree: ${tree.join(", ")})`); + } + + const b = cloneOf(bare); + restoreRun(b, "t6", { remote: "origin" }); + const restored = runDir(b, "t6"); + const manifest = readJson(tracePaths(restored).manifest); + assert.equal(manifest.run_id, "t6"); + assert.equal(manifest.outcome, "paused"); + assert.ok(existsSync(tracePaths(restored).events), "paused run keeps events"); + + const engine = new WorkflowEngine(b); + const state = await engine.resume("t6", { verdict: "approve" }, STEP_REGISTRY); + assert.equal(state.status, RunStatus.COMPLETED); + assert.ok(existsSync(tracePaths(restored).manifest), "restored run keeps its manifest"); +}); + +// ── I-1 (review pr-83): mid-run syncs keep the event stream off the remote ─ +// +// ADR-490 retention is decided only at finalize. While the run is still +// executing, its event stream must not reach the remote — a run that later +// completes (and is pruned to manifest-only) would otherwise already have +// uploaded the full events.jsonl blobs to the remote object store. Paused +// runs ship the stream (cross-session resume needs continuity, AC-T6) and +// terminal pushes ship the tree per retention class. + +test("I-1: mid-run syncs exclude trace/events.jsonl; paused and terminal pushes ship it per retention", async () => { + const { dir, bare } = repo({ remote: true }); + await withEnv("ADLC_WORKFLOW_PUSH_INTERVAL", "0", async () => { + const treeOf = (runId) => + git(bare, "ls-tree", "-r", "--name-only", `refs/factory-runs/${runId}`).split("\n").filter(Boolean); + + // Mid-run (status running): identity and artifact index travel, the + // event stream does not. + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "i1-run" }); + const midTree = treeOf("i1-run"); + assert.ok(!midTree.includes("trace/events.jsonl"), `mid-run push must not ship events.jsonl (tree: ${midTree.join(", ")})`); + assert.ok(midTree.includes("trace/manifest.json"), "manifest still travels mid-run"); + assert.ok(midTree.includes("trace/artifacts.json"), "artifact index still travels mid-run"); + assert.ok(existsSync(join(runDir(dir, "i1-run"), "trace", "events.jsonl")), "the local stream keeps recording"); + + // Paused (park semantics, AC-T6): the stream ships so a restored run + // keeps its pre-pause events. + await statePause({ projectRoot: dir, runId: "i1-run", stepId: "two" }); + const pausedTree = treeOf("i1-run"); + assert.ok(pausedTree.includes("trace/events.jsonl"), `paused push must ship events.jsonl (tree: ${pausedTree.join(", ")})`); + + // Terminal failed (retention full): the stream ships. + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "i1-fail" }); + await stateAdvance({ projectRoot: dir, runId: "i1-fail", stepId: "one", status: "failed", error: "boom" }); + const failedTree = treeOf("i1-fail"); + assert.ok(failedTree.includes("trace/events.jsonl"), `terminal failed push must ship events.jsonl (tree: ${failedTree.join(", ")})`); + + // Terminal completed with default sampling (manifest-only): the pruned + // stream never reaches the remote, the manifest does. + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "i1-done" }); + await stateAdvance({ projectRoot: dir, runId: "i1-done", stepId: "one", status: "completed" }); + await stateAdvance({ projectRoot: dir, runId: "i1-done", stepId: "two", status: "completed" }); + const doneTree = treeOf("i1-done"); + assert.ok(!doneTree.includes("trace/events.jsonl"), `pruned successful run must not ship events.jsonl (tree: ${doneTree.join(", ")})`); + assert.ok(doneTree.includes("trace/manifest.json"), "manifest-only run still ships its manifest"); + }); +}); + +// ── I-2 (review pr-83): manifest head_sha records the post-step revision ──── +// +// ADR-490 replay identity: the manifest must carry the revision the run +// actually ended on, not only the one it started from. + +test("I-2: finalize refreshes manifest head_sha when steps moved the repo HEAD", async () => { + const { dir } = repo(); + const startSha = git(dir, "rev-parse", "HEAD"); + await stateStart({ projectRoot: dir, workflowSource: workflowFile(), runId: "i2-sha" }); + + const before = readJson(tracePaths(runDir(dir, "i2-sha")).manifest); + assert.equal(before.repository.head_sha, startSha, "run-start manifest records the start HEAD"); + + // Steps moved the repo HEAD after the run started. + write(dir, "step-work.txt", "moved head\n"); + commitAll(dir, "step work"); + const movedSha = git(dir, "rev-parse", "HEAD"); + assert.notEqual(movedSha, startSha); + + await stateAdvance({ projectRoot: dir, runId: "i2-sha", stepId: "one", status: "failed", error: "boom" }); + const after = readJson(tracePaths(runDir(dir, "i2-sha")).manifest); + assert.equal(after.repository.head_sha, movedSha, "finalize must record the post-step revision"); + assert.equal(after.repository.run_start_sha, startSha, "run_start_sha keeps the run-start revision"); +});