Skip to content

feat(workflow): factory board — pane of glass v1 over local runs + remote refs - #85

Merged
kanfil merged 10 commits into
mainfrom
factory/mission/adlc-cli-phase3
Nov 8, 2026
Merged

kanfil merged 10 commits into
mainfrom
factory/mission/adlc-cli-phase3

Conversation

@kanfil

@kanfil kanfil commented Nov 7, 2026

Copy link
Copy Markdown
Member

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 remote refs/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

  • Derived, disposable index — computed fresh on every invocation, nothing persisted (ADR-325 stateless aggregation; ADR-490 keeps refs authoritative).
  • Namespaced remote fetch — +refs/factory-runs/*:refs/remotes/<remote>/factory-runs/* --prune --depth 1; never overwrites the local refs/factory-runs/* a live machine is pushing (AC-B4).
  • Local wins detail, remote adds reach — runs in both places are marked both with local detail + remote sha; remote-only runs (parked from another clone) carry status read from the ref.
  • Graceful degradation per source (ADR-325) — unreachable remote → warning + local-only board, exit 0; unreadable/garbage refs are skipped and counted, never fatal.
  • --format json — emits {runs, remoteError, skippedRemote} as the machine contract for the future ADR-325 SPA dashboard service (explicit non-goal here).
  • No new dependencies.

Verification

  • node --test tests/workflow-board.test.mjs — 7/7 contract tests (AC-B1..B4) green.
  • Full 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.

…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 kanfil left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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-ref output) but are only ever embedded after the refs/remotes/... prefix in argv (never parseable as a git option); git refname rules exclude :, space and control characters; spawnSync array 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, local refs/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 json mode stdout carries only the JSON.stringify document; warnings/errors go to stderr (warn/error → err()); git subprocess output is captured by spawnSync, 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 for board.
  • 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.

@kanfil kanfil added the validation Passed automated factory-review validation; awaiting human approval label Nov 7, 2026
factory-review-fix added 9 commits November 7, 2026 21:29
…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.
@kanfil
kanfil force-pushed the factory/mission/adlc-cli-phase3 branch from aabef8e to 00318d2 Compare November 7, 2026 21:19
@kanfil

kanfil commented Nov 7, 2026

Copy link
Copy Markdown
Member Author

Fix Agent — iteration 1 (Important finding 1)

Rebase: branch rebased onto the healed phase-2 head b857f8d0 — clean, no conflicts (phase-1/2 commits already in the new base; only the phase-3 board commit re-applied as ac967d6). Full npm test on the rebased stack: 942/942 pass, 0 fail, exit 0.

Injection fix (I-1):

  • src/workflow/refs.mjs:356 — checkRemote() exported (behavior unchanged; park/restore keep using it).
  • src/workflow/board.mjs:132-138 — buildBoardIndex calls checkRemote(remote) at entry, before any git call. Validating at the single entry point covers both flag forms (--remote x and --remote=x), including the inline form that bypassed extractFlagValue's leading-dash guard. The board CLI surfaces the throw as a usage error (exit 1, matching park/restore conventions) instead of executing the payload.

TDD evidence:

  • RED: 4 new security tests in tests/workflow-board.test.mjs — 3 failed against the unfixed code (no throw / CLI exit 0), reproducing the vector.
  • GREEN: 11/11 board tests pass; full suite 946/946 pass, 0 fail, exit 0 (942 + 4 security tests), both e2e drills green.
  • Manual repro of the reviewer's exact attack: adlc-cli workflow board '--remote=--upload-pack=touch /tmp/opencode/board-poc/PWNED2' → Error: invalid remote "--upload-pack=touch ..." exit 1, marker file not created.

Nits 2–5 (silent for-each-ref failure, O(3N) spawns, prefix hoisting, rowFrom comment) skipped — not trivially adjacent to the fix.

New head: 00318d2c30f7676de802f7aac280cd43d1f8b315 (force-pushed with lease against aabef8e0).

@kanfil

kanfil commented Nov 8, 2026

Copy link
Copy Markdown
Member Author

Converge Agent — iteration 1 (independent verification)

Independently verified I-1 resolved — own attack repro at head 00318d2c (fresh temp git repo, detached worktree checkout):

Case Result
workflow board '--remote=--upload-pack=touch <marker>' (inline form) exit 1, Error: invalid remote "--upload-pack=touch …" on stderr, stdout 0 bytes, no marker file created
workflow board --remote '--upload-pack=touch <marker>' (space form) extractFlagValue drops the leading-dash value → falls back to origin, unreachable-remote fail-soft, exit 0, no marker file created
--remote=no-such-remote-xyz (benign-invalid) fail-soft warning, local-only board, exit 0 (AC-B3 intact)
--remote='--upload-pack=…' --format json exit 1, stdout 0 bytes — the checkRemote throw happens before JSON emission, so stdout is never corrupted; error on stderr only

Regression check (checkRemote export): git diff b857f8d0..00318d2c -- src/workflow/refs.mjs is export-only (function → export function, zero behavior change); parkRun/restoreRun still validate through the same checkRemote (refs.mjs:271/296). buildBoardIndex is the only new call site.

Rebase integrity: b857f8d0..00318d2c touches exactly the six expected files (board.mjs, workflow.mjs board command, dispatch.mjs, help.mjs, tests/workflow-board.test.mjs, refs.mjs export). The re-applied phase-3 commit ac967d6 is patch-identical to the originally reviewed aabef8e0 phase-3 commit. node --test tests/workflow-board.test.mjs → 11/11 pass (7 contract + 4 security; the security tests pin the vector — attack payload present, non-execution asserted via marker-file existence).

REVIEW.md passes (bugs / security / spec-compliance / quality) over b857f8d0..00318d2c: no new findings. The 4 previous nits (silent for-each-ref failure, O(3N) spawns, triple prefix construction, rowFrom asymmetry) are unchanged and remain advisory-only — none worsened. ADR-476/325/490 contracts intact (index still derived fresh, JSON shape {runs, remoteError, skippedRemote} unchanged, namespaced fetch unchanged, exit-1 on invalid remote matches park/restore conventions).

Test evidence: full npm test at head → 946/946 pass, 0 fail (36 suites), both e2e drills green, exit 0. CI at head: 10/10 checks pass (incl. windows-latest 18/20/22).

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 kanfil left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 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.

@kanfil
kanfil marked this pull request as ready for review November 8, 2026 21:57
@kanfil
kanfil merged commit 6c343a2 into main Nov 8, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

validation Passed automated factory-review validation; awaiting human approval

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant