[roodboi]

Linear: HACK-1157 (WU26-CATALOG). Stacked on #346 (wf/f17-ax-contracts-b16, WU31 target contract); review that first.

Final behavior

• New read-only commands hack project task list and hack project task inspect <task>, plus MCP tools hack.project.task.list and hack.project.task.inspect. Names and schemas are provisional; see docs/reference/ax-task-catalog.md.
• Source of truth is a checked-in .hack/tasks.json (hack.tasks.v0), kept separate from hack.config.json so the published config schema and the WU31 generation do not change. Each recipe names a Compose service and exact argv, workdir, env scope (overlay plus key names only), required capabilities, effects, prerequisites, checks, cleanup, and provenance pins: SHA-256 of whole files, of one JSON value (RFC 6901 pointer, for example one package.json script), and of the canonical Compose service definition.
• Every result embeds the full hack.target.v0 target. Target refusals pass through unchanged, and a config generation change during the read is refused.
• Nothing is executed. Results say authority: "none" and execution: "unavailable". There is no shell endpoint and no execution path. Refused recipes are reported by index, id and reason only; their argv, text and any smuggled env values are never echoed.
• Closed per-recipe refusals: recipe_invalid, ambiguous_task, untrusted_provenance, inline_command, unapproved_host_profile, missing_capability, env_scope_mismatch, service_not_found, input_path_invalid, input_missing, stale_recipe (with observed digests). Whole-catalog refusals: invalid_task_id, task_not_found, catalog_parse_failed, catalog_invalid, catalog_too_large, catalog_changed_during_read.
• Inline-command detection (reworked, fail-closed). Every argv position is checked, because an entrypoint may exec any word (this repo's toolchain run.sh does). An inline-code or stdin flag anywhere after a shell or interpreter refuses the recipe, even after an option value or a script path. So bash -o pipefail -c, sh -O extglob -c, bash --rcfile x -c, python3 -W ignore -c, node -r ./x.js -e, perl -I lib -e and the GitHub Actions form exec bash --noprofile --norc -e -o pipefail -c … are all inline_command. env (including env -S), eval, xargs, su, ssh, awk and sed are refused at any position; watch <cmd>, Rscript -e, R -e, flock -c, bun repl, deno eval|repl, sh -s, -i, - and a shell or interpreter with no script operand (code from stdin) are refused too. Reviewed script argv still passes, for example bash -o pipefail scripts/check.sh, python3 -m pytest and bun run check.
• Pin paths (reworked). Pins may not enter any .git segment, any .hack directory's machine-local entries (.internal, .branch, .env, .env.state.json, hack.env.local.yaml, hack.env.*.local.yaml, tickets), or name a secret or key file (.hack.secret.key, legacy Hack secrets files, .env/.env.*, *.key, *.pem, *.p8, *.p12, *.pfx). A stale refusal reports the observed digest, so these exclusions keep value-derived digests out of output. Names are compared NFC-normalized and lowercased for case-insensitive APFS (.GIT/config, .hack/.Internal/x).
• Resolved-path check (reworked). readPinnedDigest re-runs the same path rules on the checkout-relative path with directory symlinks resolved. This replaces the old prefix containment check: a symlinked directory can neither leave the checkout nor alias excluded state such as .hack/tickets.
• Capabilities a Compose-service runner may grant: checkout_read, checkout_write, named_volumes, network_egress, managed_env. Never granted: host ports/network, Docker socket, home mount, privileged, SSH agent, credential store. No host profile is approved, so host recipes are refused rather than run unconfined.
• This repository's catalog has three reviewed recipes for existing toolchain scripts: models, check and rust-check. They are unaffected by the stricter rules and are still reviewed.

Validation (local, macOS, Bun 1.4.3)

Rework head 267f62be:

• bun test tests/project-task-catalog.test.ts tests/integration-ownership.test.ts tests/cli-spawn-env-isolation.test.ts tests/mcp.test.ts: 44 pass, 0 fail. The catalog file alone: 17 pass, including the repo-catalog check.
• bun run --cwd packages/cli typecheck: 0 errors. bun run --cwd packages/cli check: 0 errors (34 existing warnings). Biome on the changed files: clean.
• bun run docs:cli-reference: no diff (the CLI surface did not change). No agent guidance or plugin render changed.

From the original head ee3704fd (not rerun on the rework head): tests/mcp-inspect-tools.test.ts, tests/project-target-inspect.test.ts, tests/cli-reference-docs.test.ts, tests/agent-instruction-source.test.ts, cli-help, doctor-generated-files, project-target-argument-redaction-cli and pattern-examples passed; bun run typecheck and bun run check had 0 errors.

Negative controls (each proved by a mutation that makes its test fail)

Rework mutations (all killed):

• Inline flags matched only in leading options (the old behavior): 2 tests fail (grammar table and the paired log-actions fixture).
• env/eval/xargs/awk/sed refused only at argv[0]; stdin flags ignored; missing script operand ignored; - operand ignored; REPL/eval subcommands ignored; watch <cmd> ignored: each fails the grammar test.
• Path segments compared case-sensitively; .git refused only as the first segment; secret basenames accepted; .hack local entries cut back to .internal/.branch: each fails the path test.
• Resolved-path guard in readPinnedDigest disabled: the discovery fixture fails (escape-dir through linked -> ../outside, and alias-local through hack-link -> .hack reaching .hack/tickets/notes.md, become stale_recipe instead of input_path_invalid). This closes the verifier's surviving mutation.

Original controls (unchanged):

• Registration runs nothing: under the spawn recorder, listing, inspecting a reviewed touch <canary> recipe and inspecting a refused sh -c recipe run only git; the canary file is never created.
• Stale recipe: an edited script or service definition is refused with its observed digest. Editing .hack/toolchain/run.sh fails the repo-catalog check.
• Log-injected command: provenance.source: "log" is untrusted_provenance; sh -c … and the Actions-style line with repository provenance are inline_command. No argv or canary text appears in CLI stdout or stderr.
• Wrong env scope: a staging recipe is refused under base and passes with --env staging; a base recipe is refused under staging.
• Missing capability: docker_socket plus an unknown token is refused with missing_capabilities: ["docker_socket"] and unknown_capabilities: 1.
• Other closed refusals: ambiguous ids, host runner, unknown service, missing input, file symlink escaping the checkout, invalid id, malformed/foreign/oversized/symlinked catalogs, catalog or config edits during the read, forged or drifted envelopes (dropped by MCP re-validation), and a malformed task id (refused by the CLI; the MCP tool refuses it without spawning).

Remaining gaps (host-bound or owned elsewhere)

• No execution. Running a reviewed recipe, managed env injection, mount/network/resource enforcement, timeouts, cleanup and output policy remain WU26 gates. No container was started for this PR.
• Inline-code detection is a denylist of known shells, interpreters and string-to-shell wrappers. A program it does not know, or a reviewed script, can still evaluate an argument; the reviewer must check argv, and WU26 must not treat this check as a sandbox. Being fail-closed, it can also refuse a script argument that looks like an inline flag (script.sh -c).
• reviewed means the pins match. It does not prove who reviewed the recipe, so execution must not treat it as authorization.
• Pins cover only the named files and JSON values. Nested scripts, dependencies, lockfiles and base images are not covered. The service definition is pinned but not analyzed for policy.
• Env-scope checks compare only the overlay selection. Whether the overlay exists and supplies the scoped keys is not checked.
• No host profile is approved, so host-side scripts cannot be catalogued yet.
• Pinned inputs are read once. The catalog file and the config generation are re-read and compared.
• The full bun run test suite and hosted CI were not run locally.

Rework 2

Addresses the independent verifier's round-1 findings. Commits on top of 267f62be: 356f6e3b (fix), aab02f85 (gitleaks allowlist for the existing synthetic canary), 2dd831e1 (docs/env.md rows), and merges of the current base wf/f17-ax-contracts-b16 (a3eb34e9, then 5352415d).

• Legacy .dev project directory (blocking). Machine-local entries are now excluded after either project directory name, .hack or the legacy .dev (from HACK_PROJECT_DIR_PRIMARY/HACK_PROJECT_DIR_LEGACY). .dev/.internal/state.json, .dev/hack.env.local.yaml, .dev/hack.env.prod.local.yaml, .dev/tickets/x.md and apps/web/.dev/.internal/x are recipe_invalid in any letter case; .dev/docker-compose.yml and .dev/tasks.json stay accepted.
• Secret files the name rules cannot list (medium). Every pin must now be a Git-tracked file. One read-only git --literal-pathspecs -C <root> -c core.fsmonitor=false ls-files -z --cached -- <pins> runs per pinned recipe, after the lexical and symlink checks and before any pinned byte is read. An untracked or gitignored file (.npmrc, .netrc, secrets.json, ...), a file removed from the index, or a checkout without Git gives input_path_invalid with no digest. The docs no longer claim the denylist alone keeps value-derived digests out of output. Known gap, documented: the digest is of the working-tree bytes, so an uncommitted local edit to a tracked file can still appear as a digest in a stale refusal.
• Inline-command forms (non-blocking). Added npx -c/--call, npm exec -c, pnpm -c/--shell-mode, yarn exec, bun exec, nodemon --exec, tsx/ts-node (-e, -p, -i, no operand), sudo -s|-i, doas -s, git -c/--config-env/--exec/-x/--extcmd/submodule foreach, nix --expr/eval/repl/develop/shell, make --eval/-E/-f -, deno run -, elixir/mix -e, erl -eval, entr -s, parallel/sg with a command, and runuser, nix-shell, concurrently, watchexec, tmux, iex, vi/Vim/Neovim and Emacs at any position. Every repro in the verifier's list is now inline_command. The docs now call the check a denylist of known programs that is fail-closed only for the programs it knows.
• Vacuous registration test (minor). The spawn-recorder test now requires at least one recorded git call and a recorded ls-files, so a recorder that fails to load cannot pass.
• Not changed here: the base branch wf/f17-ax-contracts-b16 is still based on 3b530068, behind current next; that belongs to feat(agents): shared AX target and result contract with a read-only inspector #346.

Rework 2 validation (local, macOS, Bun 1.4.3; package.json pins 1.4.2)

Head 6400eec4:

• bun test tests/project-task-catalog.test.ts tests/project-target-inspect.test.ts: 40 pass, 0 fail.
• Full bun run test: 7253 pass, 126 skip, 8 fail, 7387 tests across 524 files (1h16m, host load average 12-18). Every failure is in code this stack does not touch. Rerun serially with --timeout 60000: agent-onboard-command, init-assistant, native-compose-file-command and native-env-values pass. Three native census tests still fail on deadline errors ("Native process census expired", "live-session observation refused (unknown)"): one in native-authored-process-incarnation and two in native-authored-project-recovery. I treat these as load-only and have not masked them; hosted CI is the clean signal.
• bun run --cwd packages/cli typecheck: 0 errors. bun run --cwd packages/cli check: 0 errors (34 existing warnings). Root bun run typecheck and bun run check: pass. Biome on the changed files: clean.
• gitleaks git --config .gitleaks.toml --redact --log-opts='origin/next..HEAD' (8.30.1): no leaks.

Mutations, each killed by the named test:

• Skip the tracked-file check: 3 tests fail (paired discovery fixture untracked-secret, registration ls-files assertion, domain tracking test).
• Exclude local entries only after .hack: the path grammar test fails.
• Remove npx, git foreach, sudo, ts-node or runuser from the tables: the inline grammar test fails for each.
• Do not load the spawn recorder: the registration test fails (it passed vacuously before).

Hosted CI: CI run 39441252597 (pull_request) was queued at 2026-10-20T14:39Z for head 6400eec4. Earlier runs on this branch took 3 to 4 hours, so the result was not available when this section was written.

Rework 2, round 2 (head 14676d5a)

Re-checked the verifier's round-1 findings against the remote head 6400eec4. All four in-scope items were already fixed there by 356f6e3b; each was re-proved by a mutation on the new head:

• Legacy .dev local state (blocking): fixed. isSafeInputPath excludes machine-local entries after .hack or .dev. Mutation: drop HACK_PROJECT_DIR_LEGACY from the project-dir set → the path grammar test fails.
• Untracked secret files (medium): fixed. Pins must be Git-tracked (one read-only git ls-files before any byte is read). Mutation: make the tracked check always true → 3 tests fail (paired untracked-secret fixture, registration ls-files assertion, domain tracking test).
• Inline-command forms (non-blocking): fixed for every listed repro. Re-ran the verifier's 14 repros through the real classifier: all are inline_command.
• Vacuous registration test (minor): fixed. The test requires a recorded git call and ls-files.
• Base behind next (informational): resolved. feat(agents): shared AX target and result contract with a read-only inspector #346 was squash-merged into next (8c790004) and this PR showed CONFLICTING. Merged origin/next (c7336989). Every conflict was additive (the task command, the MCP tools, and the docs, CLI reference and env-matrix rows); the merged tree differs from next only in the 14 F18 files.

New commits:

• 125e2127 (from an earlier unpushed rework pass, reviewed and kept): refuses data: URL modules for Node, Bun, Deno and tsx, git bisect/filter-branch, and julia -e/--print/no operand. Mutation of those rules → the grammar test fails.
• 14676d5a: refuses git fetch/clone/ls-remote --upload-pack and git push --receive-pack, because git runs both values as shell commands. Also maps a dash version suffix (node-22 -e) to the same interpreter as node22. git push -u origin main, git fetch origin and node-22 script.js still pass. Each rule has its own mutation, and each mutation makes the grammar test fail.

Validation (local macOS, Bun 1.4.3; package.json pins 1.4.2):

• bun test tests/project-task-catalog.test.ts: 18 pass, 0 fail.
• bun run --cwd packages/cli typecheck / check: 0 errors (34 warnings that were already there). Root bun run typecheck / bun run check: pass.
• gitleaks git --config .gitleaks.toml --redact --log-opts='origin/next..HEAD' (8.30.1): 11 commits, no leaks.
• Full bun run test: 7124 pass, 149 skip, 255 fail across 533 files (1h31m, load average 14-28). Every failing file was rerun serially with --timeout 60000. These pass: mcp, mcp-prompts, agent-plugin-generation, env-selection-parity, e2e-shard, mcp-publication-readiness, env-command-matrix, the task catalog and target inspector suites, and 38 other files. Nine native files still fail: native-authored-project-start, native-authored-process-incarnation, native-authored-project-recovery, native-compose-adoption-generation, native-compose-file-command, native-compose-proxy-probe, native-compose-retained-storage-command, native-compose-storage-activation-command and native-compose-storage-fence-cost. Run serially on a plain export of origin/next on the same host, these same files also fail with the same errors: census expiry, engine:false, and "Completed-job worktree acceptance refused". native-authored-project-start passed once on next and failed on the next run. These failures come from the host and its load, not from F18. They are not masked. Hosted CI is the clean signal; 6400eec4 passed every hosted check.

Not fixed here (needs a product decision): SQL clients that take a statement string (psql -c, sqlite3 db "…") and python -m code still pass. psql's \! and sqlite3's .shell can reach a shell. Refusing every psql -c would also refuse common reviewed database tasks.

🤖 Generated with Claude Code

[linear-code]

HACK-1157