From 25446bc77593e61ad6c61cb505221891030a485e Mon Sep 17 00:00:00 2001 From: factory-review-fix Date: Sat, 7 Nov 2026 19:27:04 +0200 Subject: [PATCH 1/8] feat(workflow): sync run refs to origin on state transitions and redact at park - syncRunRef force-pushes refs/factory-runs/ after each transition, throttled by ADLC_WORKFLOW_PUSH_INTERVAL (default 60s, 0 = every one), fail-soft so an offline pod never fails the run (ADR-475) - stateStart/statePause/stateFail and Engine.finishSession push unconditionally (exit paths); step starts push throttled - parkRun redacts every UTF-8 run file in place before hashing, so a leaked secret never reaches the remote (ADR-478) - run refs exclude machine-local lease.json and .push-ts (ADR-477) - extract the text redactor to workflow/redact.mjs; shell.mjs re-exports - tests: workflow-run-sync.test.mjs covers AC-1..AC-5 --- src/workflow/engine.mjs | 9 +- src/workflow/redact.mjs | 35 +++++ src/workflow/refs.mjs | 93 ++++++++++- src/workflow/state.mjs | 16 +- src/workflow/steps/shell.mjs | 37 +---- tests/workflow-run-sync.test.mjs | 255 +++++++++++++++++++++++++++++++ 6 files changed, 403 insertions(+), 42 deletions(-) create mode 100644 src/workflow/redact.mjs create mode 100644 tests/workflow-run-sync.test.mjs diff --git a/src/workflow/engine.mjs b/src/workflow/engine.mjs index bc6bd63..c0fd913 100644 --- a/src/workflow/engine.mjs +++ b/src/workflow/engine.mjs @@ -26,7 +26,7 @@ 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 { currentHeadSha, hasContextGate } from "./gate-context.mjs"; import { loadBundledCatalog, @@ -803,7 +803,9 @@ 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); + // 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(); } @@ -921,6 +923,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..69bf291 100644 --- a/src/workflow/refs.mjs +++ b/src/workflow/refs.mjs @@ -7,6 +7,24 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, wri 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; + +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; +} export function pushRunRef(projectRoot, runId, runDir) { const git = (args, input) => @@ -31,6 +49,7 @@ 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()) { entries.push(`040000 tree ${hashDir(abs)}\t${name}`); @@ -59,6 +78,69 @@ 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); + if (statSync(abs).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; +} + +// 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() } = {}) { + if (!pushRunRef(projectRoot, runId, runDir)) return false; + const ref = `refs/factory-runs/${runId}`; + const stamp = join(runDir, PUSH_STAMP); + if (minIntervalSeconds > 0 && existsSync(stamp)) { + const last = Number(readFileSync(stamp, "utf-8").trim()); + if (Number.isFinite(last) && Date.now() - last < minIntervalSeconds * 1000) { + return true; + } + } + const pushed = spawnSync("git", ["push", "--quiet", remote, `+${ref}:${ref}`], { + cwd: projectRoot, + encoding: "utf-8", + maxBuffer: 16 * 1024 * 1024, + }); + 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 +148,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 +166,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 diff --git a/src/workflow/state.mjs b/src/workflow/state.mjs index dac032d..aad5647 100644 --- a/src/workflow/state.mjs +++ b/src/workflow/state.mjs @@ -9,7 +9,7 @@ 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"; // start: create a run (status running, index 0) from a workflow source. // Returns the run state. Does NOT execute steps — the LLM executor drives. @@ -44,7 +44,9 @@ export async function stateStart({ projectRoot = process.cwd(), workflowSource, state.currentStepIndex = 0; state.currentStepId = definition.steps[0]?.id ?? null; 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 +120,9 @@ export async function stateAdvance({ } await state.save(); - pushRunRef(projectRoot, runId, state.runsDir); + // 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 +137,8 @@ export async function statePause({ projectRoot = process.cwd(), runId, stepId } state.currentStepIndex = idx; state.currentStepId = stepId; await state.save(); - pushRunRef(projectRoot, runId, state.runsDir); + // Exit path: push unconditionally so the pause survives a pod teardown. + syncRunRef(projectRoot, runId, state.runsDir, { minIntervalSeconds: 0 }); lease.release(); return state; } @@ -145,7 +150,8 @@ 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); + // 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/tests/workflow-run-sync.test.mjs b/tests/workflow-run-sync.test.mjs new file mode 100644 index 0000000..6263e0a --- /dev/null +++ b/tests/workflow-run-sync.test.mjs @@ -0,0 +1,255 @@ +// 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 } 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, 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"; + +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"))); + }); +}); + +// 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"))); +}); From cdc52d06cf99d3e3e116f194c623f345399687fa Mon Sep 17 00:00:00 2001 From: factory-review-fix Date: Sat, 7 Nov 2026 21:29:05 +0200 Subject: [PATCH 2/8] fix(workflow): redact every run-ref sync, fail-soft stamp read, skip symlinks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix three Important review findings on PR #82 (iter 1): - I-1: syncRunRef now runs redactRunDir before every push, not just at park — the remote sees the run dir on every state transition, so a secret-valued input must be masked before the first push lands on origin (ADR-478, ADR-497). Redaction failure is fail-soft (warn). - I-2: an unreadable .push-ts throttle stamp (EACCES, TOCTOU removal) is treated as absent — syncRunRef proceeds to push instead of throwing past state.save() and marking a healthy run FAILED (ADR-497 fail-soft). - I-3: both run-dir walkers (hashDir, redactRunDir) use lstat and skip symlinks — redaction can no longer write through a symlink outside the run dir, symlinked directories are not traversed into the pushed tree, and dangling symlinks no longer fail the push. Also adds a 30s timeout to the git push spawnSync (review nit N-1). New regression tests I-1..I-3 in tests/workflow-run-sync.test.mjs pin each contract; full suite 922/922. --- src/workflow/refs.mjs | 35 ++++++++++-- tests/workflow-run-sync.test.mjs | 94 +++++++++++++++++++++++++++++++- 2 files changed, 123 insertions(+), 6 deletions(-) diff --git a/src/workflow/refs.mjs b/src/workflow/refs.mjs index 69bf291..af76a33 100644 --- a/src/workflow/refs.mjs +++ b/src/workflow/refs.mjs @@ -3,7 +3,7 @@ // 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, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs"; import { dirname, join, resolve, sep } from "node:path"; import { spawnSync } from "node:child_process"; import { err } from "../ui/index.mjs"; @@ -51,7 +51,12 @@ export function pushRunRef(projectRoot, runId, runDir) { 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]); @@ -87,7 +92,12 @@ export function redactRunDir(runDir, env = process.env) { const walk = (absDir) => { for (const name of readdirSync(absDir)) { const abs = join(absDir, name); - if (statSync(abs).isDirectory()) { + // 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; } @@ -116,11 +126,27 @@ export function redactRunDir(runDir, env = process.env) { // 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() } = {}) { + // Every sync is redacted, not just park: the remote sees the run dir on + // every transition, so a secret-valued input must be masked before the + // first push lands on origin (ADR-478, ADR-497). Fail-soft: a redaction + // hiccup must not fail the transition either. + try { + redactRunDir(runDir); + } catch (exc) { + err(`[workflow] run-ref redaction skipped for ${runId}: ${exc?.message ?? exc}`); + } if (!pushRunRef(projectRoot, runId, runDir)) return false; const ref = `refs/factory-runs/${runId}`; const stamp = join(runDir, PUSH_STAMP); if (minIntervalSeconds > 0 && existsSync(stamp)) { - const last = Number(readFileSync(stamp, "utf-8").trim()); + // 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; } @@ -129,6 +155,7 @@ export function syncRunRef(projectRoot, runId, runDir, { remote = "origin", minI 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(); diff --git a/tests/workflow-run-sync.test.mjs b/tests/workflow-run-sync.test.mjs index 6263e0a..2b502b3 100644 --- a/tests/workflow-run-sync.test.mjs +++ b/tests/workflow-run-sync.test.mjs @@ -12,7 +12,7 @@ import { test } from "node:test"; import assert from "node:assert/strict"; -import { mkdtempSync, rmSync, writeFileSync, readFileSync, mkdirSync, existsSync } from "node:fs"; +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"; @@ -20,7 +20,7 @@ import { fileURLToPath } from "node:url"; 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 { parkRun, restoreRun, syncRunRef } from "../src/workflow/refs.mjs"; const CLI_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), ".."); @@ -249,6 +249,96 @@ test("AC-5: advance without an origin still succeeds (fail-soft push)", async () }); }); +// ── 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 (chmod 000) 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"); + chmodSync(stamp, 0o000); + 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; + } +}); + // 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"))); From f4d8a0da5d3d5d6b5100fde90b7638e9babc9726 Mon Sep 17 00:00:00 2001 From: factory-review-fix Date: Sat, 7 Nov 2026 21:36:22 +0200 Subject: [PATCH 3/8] test(workflow): simulate unreadable .push-ts cross-platform (EISDIR) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Windows CI failure (iter 1): chmod 000 does not make a file unreadable on Windows — POSIX mode bits don't map to Windows ACLs — so the stamp read succeeded, the throttle saw a recent push, and the advance was skipped, failing the I-2 assertion on all three windows jobs. Replace the chmod simulation with a directory at the .push-ts path: readFileSync on a directory throws EISDIR on Linux, macOS, and Windows alike, exercising the exact guarded read path in syncRunRef on every platform. Production code unchanged. Full suite 922/922. --- tests/workflow-run-sync.test.mjs | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/tests/workflow-run-sync.test.mjs b/tests/workflow-run-sync.test.mjs index 2b502b3..f7bcd3c 100644 --- a/tests/workflow-run-sync.test.mjs +++ b/tests/workflow-run-sync.test.mjs @@ -12,7 +12,7 @@ import { test } from "node:test"; import assert from "node:assert/strict"; -import { mkdtempSync, rmSync, writeFileSync, readFileSync, mkdirSync, existsSync, chmodSync, symlinkSync } from "node:fs"; +import { mkdtempSync, rmSync, writeFileSync, readFileSync, mkdirSync, existsSync, symlinkSync } from "node:fs"; import { tmpdir } from "node:os"; import { join, dirname, resolve } from "node:path"; import { execFileSync } from "node:child_process"; @@ -285,14 +285,18 @@ steps: // ── I-2: unreadable throttle stamp is treated as absent (fail-soft) ──────── -test("I-2: unreadable .push-ts (chmod 000) does not throw and the transition still pushes", async () => { +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"); - chmodSync(stamp, 0o000); + // 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. From a2390452553e3d20cab3a1c80bf2b997210f2858 Mon Sep 17 00:00:00 2001 From: factory-review-fix Date: Sat, 7 Nov 2026 21:58:19 +0200 Subject: [PATCH 4/8] fix(workflow): redact transition pushes via staging copy, keep local run dir raw MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix Important finding I-4 (converge iter 3): the iter-1 in-place redaction in syncRunRef silently masked token-shaped secret inputs in the LIVE local run dir on the first transition — a resume() that does not re-pass inputs then fed '***' into remaining steps, and a failed run could not be resumed with its original inputs (RunState.load reads inputs.json as the only input source). This regressed pre-fix behavior (local dir stayed raw; only parkRun redacted) and contradicted ADR-497 ('no run file edited in place except redaction at park') and ADR-478 ('local debugging may keep raw output; the wire must not'). syncRunRef now builds the pushed tree from a throwaway staging copy: copy the run dir to a temp dir (machine-local files excluded per ADR-477, symlinks skipped per ADR-478), redact the copy, hash+push the copy, discard it. The live run dir stays byte-identical across transitions. Fail-closed: if redaction of the staged copy fails, the push is skipped entirely — the wire never receives unredacted content — while the transition itself stays fail-soft (no throw). New regression tests I-4a/I-4b pin: local inputs.json stays raw across start/pause syncs while the remote stays masked (incl. resume-level state.inputs check), and a redaction failure (read-only inputs.json) skips the push with no throw and an unchanged remote. Full suite 924/924. --- src/workflow/refs.mjs | 77 +++++++++++++++++++++---- tests/workflow-run-sync.test.mjs | 97 +++++++++++++++++++++++++++++++- 2 files changed, 161 insertions(+), 13 deletions(-) diff --git a/src/workflow/refs.mjs b/src/workflow/refs.mjs index af76a33..90f4d4b 100644 --- a/src/workflow/refs.mjs +++ b/src/workflow/refs.mjs @@ -3,7 +3,8 @@ // main history stays untouched. Called at session exit points (pause and // terminal states); best-effort: silently skipped outside a git repo. -import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, 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"; @@ -120,22 +121,53 @@ export function redactRunDir(runDir, env = process.env) { 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() } = {}) { - // Every sync is redacted, not just park: the remote sees the run dir on - // every transition, so a secret-valued input must be masked before the - // first push lands on origin (ADR-478, ADR-497). Fail-soft: a redaction - // hiccup must not fail the transition either. - try { - redactRunDir(runDir); - } catch (exc) { - err(`[workflow] run-ref redaction skipped for ${runId}: ${exc?.message ?? exc}`); - } - if (!pushRunRef(projectRoot, runId, runDir)) return false; const ref = `refs/factory-runs/${runId}`; const stamp = join(runDir, PUSH_STAMP); if (minIntervalSeconds > 0 && existsSync(stamp)) { @@ -151,6 +183,29 @@ export function syncRunRef(projectRoot, runId, runDir, { remote = "origin", minI 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 { + 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", diff --git a/tests/workflow-run-sync.test.mjs b/tests/workflow-run-sync.test.mjs index f7bcd3c..d567974 100644 --- a/tests/workflow-run-sync.test.mjs +++ b/tests/workflow-run-sync.test.mjs @@ -12,12 +12,12 @@ import { test } from "node:test"; import assert from "node:assert/strict"; -import { mkdtempSync, rmSync, writeFileSync, readFileSync, mkdirSync, existsSync, symlinkSync } from "node:fs"; +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, RunStatus } from "../src/workflow/engine.mjs"; +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"; @@ -343,6 +343,99 @@ test("I-3: symlinks inside the run dir are not followed, not pushed, not written } }); +// ── 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"))); From fdcaadeae1281f8ae95426e073deb378e976cd8a Mon Sep 17 00:00:00 2001 From: factory-review-fix Date: Sat, 7 Nov 2026 20:07:31 +0200 Subject: [PATCH 5/8] =?UTF-8?q?feat(workflow):=20trace=20bundle=20v1=20?= =?UTF-8?q?=E2=80=94=20manifest,=20ADR-362=20event=20stream,=20artifacts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Implements ADR-490 bundle v1 with engine lifecycle events as the producer (ADR-498): ADR-488 session journals remain a later, additive producer. - trace/manifest.json: schema v1 identity — run/workflow/issue refs, repo SHAs and remote, agent/session IDs, model+route, container digest, skill-lock and MCP-config hashes, outcome, retention class, workload class; always retained - trace/events.jsonl: RunState.appendLog mirrors every lifecycle entry as an ADR-362 envelope (schema_version 1, agent_id, ts, type, payload) with ADR-364 canonical types; original entry under payload.adlc; state helpers and engine run/resume/finishSession append transition events - capture-time redaction: every string entering the trace passes the shared redactor (redactDeep keeps JSON valid) - fail-closed retention: failed/aborted keep full events; completed runs prune to manifest-only unless ADLC_TRACE_SUCCESS_SAMPLE_RATE selects them (deterministic sha256(run_id) sampling); finalize runs before the ref sync so pruned traces never reach the remote - trace/artifacts.json: content-addressed entries (sha256, media type, size, storage URI, retention, sensitivity, producing event) with strict validation - all trace writes fail-soft: telemetry never fails a run - tests: workflow-trace.test.mjs covers AC-T1..AC-T6 (928/928 + E2E green) --- src/workflow/engine.mjs | 21 ++ src/workflow/state.mjs | 31 +++ src/workflow/trace.mjs | 326 +++++++++++++++++++++++++++++ tests/workflow-trace.test.mjs | 380 ++++++++++++++++++++++++++++++++++ 4 files changed, 758 insertions(+) create mode 100644 src/workflow/trace.mjs create mode 100644 tests/workflow-trace.test.mjs diff --git a/src/workflow/engine.mjs b/src/workflow/engine.mjs index c0fd913..44e14d5 100644 --- a/src/workflow/engine.mjs +++ b/src/workflow/engine.mjs @@ -27,6 +27,7 @@ import { evaluateCondition } from "./expressions.mjs"; import { readAgent } from "../utils/init-options.mjs"; import { Lease } from "./lease.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({ @@ -802,6 +813,11 @@ export class WorkflowEngine { } else if (state.status === RunStatus.FAILED || state.status === RunStatus.ABORTED) { this.emit("run_failed", { run_id: state.runId, error: state.error, status: state.status }); } + try { + // 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. @@ -873,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. diff --git a/src/workflow/state.mjs b/src/workflow/state.mjs index aad5647..6aa66aa 100644 --- a/src/workflow/state.mjs +++ b/src/workflow/state.mjs @@ -10,6 +10,7 @@ import { WorkflowEngine, WorkflowDefinition, RunState, RunStatus } from "./engin import { STEP_REGISTRY } from "./registry.mjs"; import { Lease } from "./lease.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,6 +44,12 @@ 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(); // Run start is durable immediately: a pod that dies right after start is // still restorable from the remote ref (ADR-475). @@ -120,6 +127,20 @@ export async function stateAdvance({ } await state.save(); + // 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); @@ -137,6 +158,11 @@ export async function statePause({ projectRoot = process.cwd(), runId, stepId } state.currentStepIndex = idx; state.currentStepId = stepId; await state.save(); + // 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(); @@ -150,6 +176,11 @@ export async function stateFail({ projectRoot = process.cwd(), runId, error } = state.status = RunStatus.FAILED; state.error = error ?? "failed"; await state.save(); + // 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(); diff --git a/src/workflow/trace.mjs b/src/workflow/trace.mjs new file mode 100644 index 0000000..67ededb --- /dev/null +++ b/src/workflow/trace.mjs @@ -0,0 +1,326 @@ +// 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(); + + 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/workflow-trace.test.mjs b/tests/workflow-trace.test.mjs new file mode 100644 index 0000000..55e72ad --- /dev/null +++ b/tests/workflow-trace.test.mjs @@ -0,0 +1,380 @@ +// 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"); +}); From 4ed847cf5e7e86259405b81248eb60bd59effdfb Mon Sep 17 00:00:00 2001 From: factory-review-fix Date: Sat, 7 Nov 2026 22:24:18 +0200 Subject: [PATCH 6/8] fix(workflow): keep mid-run event stream off the remote; record post-step head_sha MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review pr-83 iter-1 Important findings (ADR-490 spec compliance): I-1 — mid-run syncs pushed trace/events.jsonl while retention was still pending, so a run that later completed had already uploaded the very blobs finalize prunes; the "pruned trace never reaches the remote" guarantee was tip-only. syncRunRef now trims trace/events.jsonl from the staged copy while state.json reports status "running"; paused runs (cross-session restore/resume continuity, park/AC-T6) and terminal statuses ship the tree per retention class. The live run dir keeps recording events. I-2 — the manifest recorded head_sha once at init and never refreshed it, so a completed run's final revision was missing from the bundle (ADR-490 replay identity). finalizeTrace now refreshes repository.head_sha; run_start_sha keeps the run-start revision. Tests: I-1 asserts the mid-run remote tree lacks trace/events.jsonl while running and ships it paused/terminal per retention; I-2 asserts finalize records the post-step HEAD after steps moved the repo. --- src/workflow/refs.mjs | 30 +++++++++++++++ src/workflow/trace.mjs | 7 ++++ tests/workflow-trace.test.mjs | 72 +++++++++++++++++++++++++++++++++++ 3 files changed, 109 insertions(+) diff --git a/src/workflow/refs.mjs b/src/workflow/refs.mjs index 90f4d4b..7a0dd7b 100644 --- a/src/workflow/refs.mjs +++ b/src/workflow/refs.mjs @@ -20,6 +20,16 @@ const EXCLUDED_RUN_FILES = new Set(["lease.json", ".push-ts"]); 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; @@ -27,6 +37,16 @@ function pushIntervalSeconds() { 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) => spawnSync("git", args, { @@ -196,6 +216,16 @@ export function syncRunRef(projectRoot, runId, runDir, { remote = "origin", minI 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) { diff --git a/src/workflow/trace.mjs b/src/workflow/trace.mjs index 67ededb..a16e560 100644 --- a/src/workflow/trace.mjs +++ b/src/workflow/trace.mjs @@ -240,6 +240,13 @@ export function finalizeTrace(runDir, state, { sampleRate } = {}) { 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 }); diff --git a/tests/workflow-trace.test.mjs b/tests/workflow-trace.test.mjs index 55e72ad..29a1982 100644 --- a/tests/workflow-trace.test.mjs +++ b/tests/workflow-trace.test.mjs @@ -378,3 +378,75 @@ test("AC-T6: park/restore carries trace files into a second clone", async () => 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"); +}); From 5ee84ddb13e6e425206d3e18441e26ab5918f518 Mon Sep 17 00:00:00 2001 From: factory-review-fix Date: Sat, 7 Nov 2026 20:17:11 +0200 Subject: [PATCH 7/8] =?UTF-8?q?test(workflow):=20cross-session=20e2e=20?= =?UTF-8?q?=E2=80=94=20two=20CLI=20sessions,=20two=20clones,=20one=20remot?= =?UTF-8?q?e?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 2 local verification of Phases 0+1, as a repeatable drill instead of a one-off manual run: - Session A (clone A): workflow run → paused at gate (exit 3, lane contract) → park to refs/factory-runs/ - Session B (clone B): guarded restore → resume → completed (exit 0) Verified invariants: - V1 pause exit code + resume hint carry the run id - V2 ref tree excludes machine-local lease.json/.push-ts (ADR-477) and carries trace/{manifest,events,artifacts} (ADR-490) - V3 restore refuses mismatched --issue-ref and an existing run dir - V4 every restored event line is a valid ADR-362 envelope with an ADR-364 canonical type - V5 a seeded secret never crosses the session boundary (0 hits in the restored run dir; step output carries the mask) - V6 default retention prunes successful events and keeps the manifest (fail-closed), no lease conflict after cross-session resume Drill joins npm test (25 assertions, 928/928 + 2 E2E green). --- package.json | 2 +- tests/e2e-cross-session.mjs | 205 ++++++++++++++++++++++++++++++++++++ 2 files changed, 206 insertions(+), 1 deletion(-) create mode 100644 tests/e2e-cross-session.mjs 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/tests/e2e-cross-session.mjs b/tests/e2e-cross-session.mjs new file mode 100644 index 0000000..2ccf529 --- /dev/null +++ b/tests/e2e-cross-session.mjs @@ -0,0 +1,205 @@ +// 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"); + 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)"); From b857f8d02f6b3bbb9b7146407a89a70b4ce9e786 Mon Sep 17 00:00:00 2001 From: factory-review-fix Date: Sat, 7 Nov 2026 22:57:20 +0200 Subject: [PATCH 8/8] test(workflow): make cross-session mask assertion windows-portable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The drill's work step is `echo leaked=$CROSS_SESSION_TOKEN`. On POSIX the shell expands the variable, the secret enters the step output, and capture-redaction 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 output literally reads `leaked=$CROSS_SESSION_TOKEN`, so there is nothing to redact and the `***` assertion can never hold. On win32 assert the unexpanded variable instead; the redaction path stays covered by the POSIX lanes and the unit tests. The raw-secret absence scan already runs on all platforms. Nothing else is skipped: the remaining 24 assertions exercise real transport machinery on Windows. Pre-existing on Windows (old head 762e397 CI run 42400572978 failed the same assertion); not introduced by the rebase. --- tests/e2e-cross-session.mjs | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/tests/e2e-cross-session.mjs b/tests/e2e-cross-session.mjs index 2ccf529..d4b0bae 100644 --- a/tests/e2e-cross-session.mjs +++ b/tests/e2e-cross-session.mjs @@ -179,7 +179,24 @@ steps: scan(runDirB); check(`seeded secret absent from the restored run dir (${secretHits} hits)`, secretHits === 0); const maskText = readFileSync(join(runDirB, "state.json"), "utf-8"); - check("work-step output carries the mask", maskText.includes("***")); + // 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"]);