feat: promote a local Claude Code workflow into the serverless harness

[pdettori]

What this does

Lets you build an agent workflow locally in Claude Code — skills, the CLAUDE.md chain, a slash
command, project memory — and run it unchanged in the serverless harness.

sh promote canonicalises that configuration into a USTAR tar, content-addresses it by sha256,
stores it in Redis, and writes a committable .claude/promoted.lock.json. A leaf then runs it by
adding one field:

{ "sessionId": "run-1/item-1", "kind": "prompt", "prompt": "…", "configRef": "sha256:…" }

Re-promoting unchanged configuration uploads nothing. Design:
docs/specs/2026-09-02-claude-code-workflow-promotion-design.md,
plus ADR-0030 (bundle + transport) and
ADR-0031 (memory travels read-only). Both ADRs are
deliberately left Proposed — accepting them is a maintainer call, and Rule 1 makes them immutable
once accepted.

MCP servers and subagents are explicitly out of scope (spec §2, §9).

Shape

New package @sh/config-bundle holds all pure bundle logic (tar, resolve, classify, secret scan,
lockfile, preflight, build). The harness side adds the CAS store, the resolver that materialises into
the pod's emptyDir, the sandbox overlay, and the promote CLI. Only 7 existing files are modified;
everything else is additive.

The fs-free split (ADR-0020) drives the design: skill prose must reach the harness pod, while
readable content must reach the separate sandbox pod. The overlay pushes a digest-keyed cache under
flock and binds per-leaf paths into it.

Preflight blocks on facts, warns on heuristics

This is the design decision most worth reviewing (spec §6, D10). Three checks were written as
blocking, then demoted after being measured against a real ~/.claude: the secret scan produced 11
false blocks, the binary check 32, the sibling-path check 182. Only unknown_entry blocks, plus a
structural secret match. A preflight that cries wolf gets ignored, and one that lies is worse than
none.

The secret scan is two-tier as a result: five structural rules (AWS/GitHub/OpenAI/Slack tokens,
PEM private-key blocks) refuse the upload and exit 3; two prose heuristics only warn. The README
states this distinction precisely, because promising a guarantee about credentials that the code
does not provide would be the worst error here.

Verification

Against upstream/main @ 6066dc4, with a local Redis:

gate	result
make lint	pass — all 9 pre-commit hooks
make typecheck	pass
make test-deploy	pass
pnpm -r test	912 passed / 17 skipped / 0 failed across 9 packages

The full pipeline was also exercised end to end outside the test suite: an 8.60 MiB bundle from a
live ~/.claude (55 skills) through putBundle → getBundle → unpackBundle → a real
DefaultResourceLoader, with the harness's own CLAUDE.md confirmed absent from the result. The
overlay scripts were executed against a real container.

Cold-path cost, measured locally (N=10, fresh output dir per run): getBundle 52.6 ms median,
unpackBundle 62.1 ms → 113.7 ms added. Loopback Redis and APFS, so indicative of the added
work only.

Not done — please read before approving

• The end-to-end in-cluster cold-start comparison is owed, not taken. The spec status says
  Implemented (cold-start measurement owed) rather than a bare "Implemented", and §8 carries the
  reproduction commands. Taking it needs an image build, kind load, and a forced new Revision.
• The live smoke has never run in a cluster. It is env-gated (SH_PROMOTE_LIVE_SMOKE) like the
  existing live gates. I verified its fixture is well-formed — the skill, the entry prompt, and the
  sibling file it must read all travel, with zero preflight errors — but a gate that has never fired
  is not evidence that the promoted path works in a cluster.
• Two commit messages are stale relative to later decisions: cc89243 says the secret scan
  "refuses the upload rather than warning" (true only of the structural tier now), and the fix-round
  commit's subject reads as adding the $SH_SKILLS_DIR env vars when it removed them. Both are
  moot under a squash merge; happy to reword if you prefer to preserve history.

Where to look first

• packages/config-bundle/src/preflight.ts — the blocking-vs-warning boundary (D10).
• harness/src/config-overlay.ts — generated shell run under flock; the shared cache is made
  read-only with chmod -R a-w so ADR-0031's guarantee is enforced by the filesystem rather than by
  convention.
• harness/src/promote.ts — projectRoot bounds the context-file walk at a .git entry using
  existsSync deliberately, not a directory test, because in a linked worktree .git is a file.
  Without that bound the walk swept ancestor CLAUDE.md files, including a personal ~/CLAUDE.md,
  into a bundle destined for a shared store.
• harness/src/run-leaf.ts — the configRef wiring, and why the overlay must not be guarded on
  selected.transport (undefined for pods, which is the default deployment).

🤖 Generated with Claude Code

[pdettori]

Verdict: approve-equivalent — no must-fix findings. Posted as a comment review because GitHub will not let an author approve their own PR.

Findings are all non-blocking. Nothing breaks existing behavior — an absent configRef leaves loader options byte-identical, and resourceLoaderOptionsFor makes that assertable rather than merely intended.

The one I'd address before this runs against real ~/.claude directories is the first comment below: the unbounded directory-symlink walk reproduces the ancestor-CLAUDE.md leak your .git bound already fixes, through a different vector, with the five structural secret rules as the only backstop.

Two things I checked specifically and found correct: the sandbox receives gzipSync(canonicalTar(promotedConfig.entries)), not the raw stored bytes — so non-regular tar entries (symlink/device types that untar drops but the sandbox's tar -x would honor) cannot survive a Redis round-trip into extraction; that digest-verification-vs-extraction gap is genuinely closed. And there are no new external dependencies — @sh/config-bundle adds only devDeps already pinned at identical versions elsewhere.

Author: pdettori (MEMBER — maintainer)
Areas reviewed: TypeScript (config-bundle, harness), Shell (deploy), CI, Docs, Tests
Agent/IDE config (.claude/.vscode): none
Commits: 41, all signed off (DCO green), all conventional prefixes; 13 subjects exceed 72 chars (moot under squash)
CI status: passing (12/12)

Not covered by this review, per your own disclosure: the in-cluster cold-start comparison and the never-fired SH_PROMOTE_LIVE_SMOKE gate. I read the smoke fixture — its assertion is meaningful, since the secret word is only reachable by resolving a sibling path in the sandbox — but a gate that has never fired isn't evidence.

One item that has no inline anchor: the PR body footer reads "Generated with Claude Code". CLAUDE.md:89 requires Assisted-By for AI attribution.

Assisted-By: Claude Code

[pdettori]

suggestion — Directory symlinks are followed with no containment check. statSync (not lstatSync) resolves the link, so st.isDirectory() is true for something like refs/linked -> ~/Documents; realpathSync then returns the target, and walk() enumerates that tree at arbitrary depth. build.ts:50 reads each result back through the link, so the whole target tree's content lands in a bundle destined for shared Redis.

This is the same failure class as the ancestor-CLAUDE.md sweep that the .git bound at promote.ts:152 exists to stop — just reached by a different vector. Cycle-breaking via canonical paths prevents a hang, but nothing bounds where the walk goes, and the five structural secret rules are the only backstop (they won't match most private content).

Suggest bounding to the skill directory: after realpathSync(p), require the canonical path to be inside realpathSync(dir) before recursing, and skip with a warn finding otherwise. Aliased skill dirs keep working, but a link out of the tree can no longer sweep. The 8be16bd → 3afe725 history shows following symlinks was a deliberate reversal — this preserves that while bounding it.

[pdettori]

suggestion — digest here is env.configRef straight off the leaf envelope, never shape-checked. digestDirName only substitutes characters, so a value like sha256:../../../evil yields root = /evil, and renameSync(staging, root) at line 68 then moves the staged tree there. config-overlay.ts:11 has the mirror problem inside the sandbox, where rm -rf "$TMP" runs on the derived path.

To be precise about reachability: this is not reachable through the shipped write path. getBundle runs first and throws BundleNotFoundError, and putBundle can only ever mint sha256:<64 hex> keys, so an exploit needs out-of-band Redis write access. But putBundle's own comment scopes key poisoning in as a threat, and this read path is exactly where a poisoned key would be spent.

A one-line guard closes it: reject anything not matching /^sha256:[0-9a-f]{64}$/ before the digest becomes a filesystem path — ideally in a shared helper that both this and configCacheDir call, so the two halves can't drift.

[pdettori]

nit — replace(':', '-') substitutes only the first occurrence. Harmless for a well-formed sha256:<hex>, but it is what turns an unvalidated configRef (see the config-resolver.ts:46 comment) into a path traversal rather than a mangled-but-contained directory name. replaceAll would make this function safe independent of its callers.

[pdettori]

suggestion — Dedupe leak when the two maps desync. If the same canonical path arrives twice under different names and the second has higher scope precedence, best.set(skill.name, skill) adds the new key but prevCanonical.name is never removed — so one physical skill is emitted twice and its files travel under two separate skills/<name>/ prefixes.

Reachable when SKILL.md has no name: frontmatter (so load falls back to the link directory's basename at line 117) and the same directory is aliased across two scopes. Narrow, but deduping is precisely what this function exists to do.

best.delete(prevCanonical.name) before the set fixes it.

[pdettori]

suggestion — sh promote isn't runnable. There's no sh bin in the repo (harness/src/cli.ts takes a prompt, not subcommands), and the wiring added in this PR is harness/package.json's "promote": "tsx src/promote-cli.ts".

The section at line 186 correctly says cd harness && pnpm promote, so the README names the command two different ways about 80 lines apart — and the copyable one in this feature bullet is the one that fails with command not found.

The same string appears in deploy/knative/sandbox-inventory/README.md:3, the design spec (lines 96, 160, 198, 331), and docs/adrs/0030-claude-code-workflow-promotion.md:38. Either add the sh promote subcommand the spec describes, or make the docs say pnpm promote.

[pdettori]

suggestion — markdownFiles reads only .md files directly in the directory, so namespaced commands never travel: ~/.claude/commands/ns/cmd.md, which Claude Code exposes as /ns:cmd, is invisible here.

If the entry is the namespaced one, checkEntry catches it as unknown_entry and promotion fails legibly. Any other namespaced command a promoted workflow invokes silently doesn't make it into the bundle and fails remotely with no local signal — which is the class of remote failure the preflight exists to prevent.

Worth either recursing here, or naming this limit in the spec's out-of-scope list next to MCP servers and subagents.

[pdettori]

nit — A third silent-pass path, alongside the two the header documents. Process substitution failure doesn't trip set -e, so malformed JSON or a missing .binaries key leaves declared empty: the container then checks nothing, still prints the sentinel, missing is empty, and the script reports PASS: inventory matches $IMAGE (0 binaries verified in-image).

The shape test's non-empty-array check covers every committed file, so the realistic CI path is protected — this is about the script being self-contained when run standalone, as its own usage line invites.

[ "${#declared[@]}" -gt 0 ] || { echo "ERROR: no binaries parsed from $FILE"; exit 1; }

[pdettori]

All seven addressed. Commits c46eacc (A), fa0a64e (D), 37728d2 (C), eb3005d (B), 0639223 (F), 97e5c30 (E), b7b9845 (G).

Symlink containment (resolve.ts:44) — you were right, and this one mattered most. Bounded to the skill directory's canonical root with a segment-aware relative() check, skipping escapes with a new skill_symlink_escaped warn finding so files aren't lost silently. Following symlinks stays deliberate; aliased dirs inside the tree still work. Verified live rather than only by unit test: a mine/escape-link -> /tmp/.../secret link is skipped and warns, and with the check stubbed out the same probe emits escape-link/private.md. Your skillsX prefix trap has its own test, and both fail if the containment check is reverted.

Digest validation (config-resolver.ts:46) — reproduced exactly as you described: digestDirName('sha256:../../../evil') → 'sha256-../../../evil', and join('/tmp/sh-config', …) → /tmp/evil. Added one shared validator in tar.ts (/^sha256:[0-9a-f]{64}$/), called by both unpackBundle and configCacheDir so the halves can't drift, per your suggestion. All six malformed shapes (traversal, wrong length, uppercase, no prefix, empty, multi-colon) now throw in both; nothing is created outside the base dir. The comment scopes it as defence in depth against the key poisoning putBundle already names, not a live exploit.

replaceAll — done, kept alongside the validator rather than instead of it. Your 'sha256:..:..:evil' case confirmed the old behaviour retained later colons.

Dedupe (resolve.ts:167) — applied, with a caveat worth recording: the guarding branch is currently unreachable. SCOPE_RANK is project:0, user:1, plugin:2 and found is built in exactly that order, so SCOPE_RANK[skill.scope] < SCOPE_RANK[prevCanonical.scope] can never hold, which also means the double-emit can't occur today. The delete is kept as dormant defence — it activates the moment anyone reorders those pushes or adds a scope — and the new test is explicit that it exercises the dedupe-by-canonical-path guarantee but does not fail if the delete alone is reverted. Flagging that rather than claiming coverage it doesn't have.

sh promote — fixed in the docs, not by adding a bin: README.md (both sites), deploy/knative/sandbox-inventory/README.md, the spec (4 places) and ADR-0030 (Status untouched). grep -rn "sh promote" --include=*.md now returns nothing.

Namespaced commands — took the document-and-warn option rather than recursing. A promoted leaf receives exactly one prompt, so non-entry commands aren't invocable mid-session, and a namespaced entry already fails legibly via unknown_entry; the harm you named is the silence. There's now a namespaced_prompt_skipped warn plus the limit listed in the spec's out-of-scope section next to MCP and subagents. Recursing would change prompt naming to ns:cmd and ripple through checkEntry and the lockfile — happy to do it as a follow-up if multi-prompt bundles are wanted.

declared guard — taken verbatim. Worth noting it's the third silent-pass in that one script, after the || true swallowing the runtime's failure and the missing sentinel. Malformed inventory now exits 1.

Gates: make lint 0, make typecheck 0, make test-deploy 0, pnpm -r test 929 passed / 17 skipped / 0 failed (+17 tests). Promote dry-run unchanged at context 2 file(s), 11 memory file(s), with neither new warning triggered on a real ~/.claude.

Also: thanks for independently confirming the gzipSync(canonicalTar(entries)) path — that the sandbox never sees raw stored bytes is the reason the digest-verify-vs-extract gap is closed, and it's worth having that on the record.