Repository navigation
feat(workflow): factory board — pane of glass v1 over local runs + remote refs - #85
Conversation
…ct at park - syncRunRef force-pushes refs/factory-runs/<id> 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
kanfil
left a comment
There was a problem hiding this comment.
Review — PR #85 phase 3: workflow board (pane of glass v1)
Reviewed revision: head aabef8e0880533f3ef9a3e5ff7c2700a9aa91a7c (detached worktree, exact head verified against headRefOid), base main, merge-base 762e39742ee1b39cd7a3d6f604d5e3378d076b1d. Focus range = the single phase-3 commit (5 files, +523); lower stack commits (#82/#83/#84) reviewed by their own agents.
Design documents: no PRD/AD exists in the repo — spec-compliance was assessed against the governing workspace ADRs (read-only, outside the repo): ADR-476 (factory pane of glass), ADR-325 (stateless aggregation; SPA service is a non-goal), ADR-490 (trace corpus / disposable index).
Test evidence (run at exact head)
node --test tests/workflow-board.test.mjs— 7/7 pass, 0 fail, exit 0 (AC-B1..B4 contract tests).npm test— 935/935 pass (36 suites), 0 fail, both e2e drills (node-gate, cross-session) green, exit 0.
Findings
Important
1. [security] Arbitrary command execution via unvalidated --remote reaching git fetch argv — src/workflow/board.mjs:77-82 (fetchRemoteRefs), fed from src/commands/workflow.mjs:521 (extractFlagValue(rawArgv, "remote")).
The --remote value flows unvalidated into spawnSync("git", ["fetch", "--quiet", "--prune", "--depth", "1", remote, refspec]). A value beginning with - is parsed by git as an option, not a positional remote. Empirically confirmed at this head:
$ adlc-cli workflow board '--remote=--upload-pack=touch /tmp/opencode/PWNED2'
→ git runs "--upload-pack=touch /tmp/opencode/PWNED2" through the shell
(file /tmp/opencode/PWNED2 created; git then fails remote resolution),
and the CLI masks the execution as a "remote unreachable" warning, exit 0.
Reachability is trivial because the inline --remote=<value> form bypasses even the leading-dash guard in extractFlagValue (src/commands/workflow.mjs:120 guards only the space-separated form). The codebase already defends this exact vector for park/restore via checkRemote() (src/workflow/refs.mjs:239-249 — its comment names git fetch --upload-pack=<cmd> specifically), but that guard is module-private and board.mjs does not apply it. Fix: export checkRemote from refs.mjs and validate remote at buildBoardIndex entry (before any git call); alternatively reject values starting with - in the command layer. Blocks merge per REVIEW.md severity weights.
Nit
2. [quality] Silent for-each-ref failure in remoteRunIds — src/workflow/board.mjs:91-93: gitText returning null degrades to [] without setting remoteError or incrementing skippedRemote — a failed listing produces a local-only board with no signal, against ADR-325's "observable failure modes" spirit. Practically rare (local refs after a successful fetch), but the other degradation paths all report themselves.
3. [quality] O(3N) process spawns over remote refs — remoteRunRow (src/workflow/board.mjs:107-110) runs rev-parse + show state.json + show manifest.json per ref, serialized. With hundreds of parked refs the board will crawl. git cat-file --batch (or a single for-each-ref with object fields) would collapse this to a constant number of processes.
4. [quality] Remote-namespace prefix built three times — refs/remotes/${remote}/factory-runs/ is constructed in remoteRunIds twice (board.mjs:96, 103) and again in remoteRunRow (board.mjs:106). Hoist to a small helper next to RUN_REF_PREFIX.
5. [quality] Mirror-asymmetric fallbacks in rowFrom — src/workflow/board.mjs:136-137: status: state.status ?? manifest?.outcome vs outcome: manifest?.outcome ?? state.status. Intentional per the tests, but a one-line comment would prevent a future "fix" from normalizing them.
Verified clean (no finding)
- Untrusted ref names / run ids are injection-safe: run ids originate from remote refs (
for-each-refoutput) but are only ever embedded after therefs/remotes/...prefix in argv (never parseable as a git option); git refname rules exclude:, space and control characters;spawnSyncarray form precludes shell interpretation. - Namespaced-fetch guarantee (AC-B4): refspec is exactly
+refs/factory-runs/*:refs/remotes/<remote>/factory-runs/*with--prune --depth 1; destination is the remote-tracking namespace, localrefs/factory-runs/*untouched — proven by the AC-B4 test at this head. - Fail-soft (AC-B3): unreachable remote → stderr warning + local-only board, exit 0; garbage/unreadable refs skipped and counted, never fatal — both tested and reproduced manually.
- JSON purity: in
--format jsonmode stdout carries only theJSON.stringifydocument; warnings/errors go to stderr (warn/error→err()); git subprocess output is captured byspawnSync, never inherited. - Spec contracts: index derived fresh each call, nothing persisted (ADR-325/490); JSON shape exactly
{runs, remoteError, skippedRemote}; no new dependencies; help + dispatch wired forboard. - Format-flag detection (
hasFlag+extractFlagValue) matches the pre-existing CLI-wide pattern — not a new inconsistency.
Verdict
not-merge-ready — 1 Important (confirmed command-execution vector through --remote; the repo's own checkRemote hardening exists but is not applied to the new fetch path). All 4 passes run per REVIEW.md; skip lists respected. Fix finding 1 (one-line guard reusing checkRemote) and this is merge-ready — the rest of the implementation is clean and spec-faithful.
…symlinks 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.
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.
…run dir raw
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.
…ifacts 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)
…step head_sha 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.
… remote
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/<id>
- 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).
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.
…mote refs
ADR-476 pane of glass, scoped to the CLI (ADR-325's SPA service stays a
separate deployable consuming --format json):
- adlc-cli workflow board: one derived, disposable index of every
factory run — local .adlc/workflows/runs/* plus remote
refs/factory-runs/* fetched namespaced
- remote fetch: +refs/factory-runs/*:refs/remotes/<remote>/factory-runs/*
--prune --depth 1 — never touches the local refs/factory-runs/* a
live machine is pushing (AC-B4)
- rows: run id, source (local/remote/both), status, current step,
trace outcome + retention class (ADR-490 manifest), issue ref,
remote sha, updated — local wins detail, remote adds reach
- graceful degradation per source (ADR-325): unreachable remote →
warning + local-only board, exit 0; unreadable refs skipped+counted
- --format json emits {runs, remoteError, skippedRemote} as the
machine contract for the future dashboard service
7 contract tests (AC-B1..B4); suite 935/935 + both e2e drills green.
…njection)
The board passed the user-controlled --remote straight into
spawnSync("git", ["fetch", ..., remote, refspec]). A value beginning
with "-" is parsed by git as an option, not a positional remote:
"--remote=--upload-pack=<cmd>" made git run <cmd> through the shell,
and the fail-soft board masked the execution as a 'remote unreachable'
warning (exit 0). The inline "--remote=<value>" form also bypasses
extractFlagValue's leading-dash guard in the command layer.
The repo already had the exact guard for this vector — checkRemote()
in src/workflow/refs.mjs, whose comment names
"git fetch --upload-pack=<cmd>" — but it was module-private and not
applied in board.mjs (park/restore already use it).
Fix: export checkRemote from refs.mjs and call it at buildBoardIndex
entry, before any git call. Validating at the single entry point covers
both flag forms (--remote x and --remote=x). The CLI now reports a
usage error (exit 1, matching park/restore conventions) instead of
executing the payload.
Tests: 4 new security tests pin the vector — buildBoardIndex throws on
option-shaped and leading-dash remotes, the inline CLI form exits 1
without executing, and the space-separated form stays safe.
aabef8e to
00318d2
Compare
|
Fix Agent — iteration 1 (Important finding 1) Rebase: branch rebased onto the healed phase-2 head Injection fix (I-1):
TDD evidence:
Nits 2–5 (silent for-each-ref failure, O(3N) spawns, prefix hoisting, rowFrom comment) skipped — not trivially adjacent to the fix. New head: |
|
Converge Agent — iteration 1 (independent verification) Independently verified I-1 resolved — own attack repro at head
Regression check (checkRemote export): Rebase integrity: REVIEW.md passes (bugs / security / spec-compliance / quality) over Test evidence: full Verdict: DONE — I-1 verified resolved by independent repro, no new Important issues, suite green. Merge-ready review comment follows; human code-owner approval still required. |
kanfil
left a comment
There was a problem hiding this comment.
🟢 PASS — Ready for human review
Reviewed revision: head 00318d2c30f7676de802f7aac280cd43d1f8b315 (detached worktree at exact head, verified against headRefOid), base main (tip 1ac800a4), merge-base 51e8c1d. Focus range = phase-3 layer (b857f8d0..00318d2c: the re-applied board commit ac967d6, patch-identical to the originally reviewed aabef8e0, plus the injection fix 00318d2c). Lower stack commits (#82/#83/#84) verdicted merge-ready by their own agents.
Independent attack-repro evidence (converge agent, own repro — not the fix agent's tests): fresh temp git repo; --remote=--upload-pack=touch <marker> in both flag forms plus benign-invalid and --format json variants. All four: no marker file ever created; inline form exits 1 with Error: invalid remote … on stderr and 0 bytes on stdout (JSON path never corrupted — the throw precedes JSON emission); space form safely falls back to origin; benign-invalid degrades fail-soft per AC-B3.
Test + CI evidence: node --test tests/workflow-board.test.mjs → 11/11. Full npm test → 946/946 pass, 0 fail, exit 0 (36 suites, both e2e drills green). CI at head → 10/10 checks pass including windows-latest 18/20/22.
Finding set: previous Important I-1 (command injection via --remote into git fetch argv) — resolved and pinned by 4 security tests. New Important findings: 0. Remaining nits (4, advisory-only, do not block): silent for-each-ref failure in remoteRunIds, O(3N) process spawns over remote refs, remote-namespace prefix built three times, mirror-asymmetric fallbacks in rowFrom.
Human approval still required: this verdict is the automated gate's output only — the code owner's explicit approval is required before merge.
Summary
Phase 3 of the ADR trace-pipeline work:
adlc-cli workflow board— ADR-476's pane of glass scoped to the CLI. One view over every factory run: local.adlc/workflows/runs/*plus remoterefs/factory-runs/*, with status, current step, trace outcome and retention (ADR-490 manifests), and issue ref.Stacked on #84 (← #83 ← #82) — only the top commit is new.
What it does
+refs/factory-runs/*:refs/remotes/<remote>/factory-runs/* --prune --depth 1; never overwrites the localrefs/factory-runs/*a live machine is pushing (AC-B4).bothwith local detail + remote sha; remote-only runs (parked from another clone) carry status read from the ref.--format json— emits{runs, remoteError, skippedRemote}as the machine contract for the future ADR-325 SPA dashboard service (explicit non-goal here).Verification
node --test tests/workflow-board.test.mjs— 7/7 contract tests (AC-B1..B4) green.npm test— 935/935 unit + both e2e drills (node-gate, cross-session) green, exit 0.Non-goals
ADR-325 SPA war-board service; tracker label ingestion (ADR-476's label half); SQLite/JSONL caching.