Software factory change

[agent-relay-code]

fix: journal agent artifacts written under dot-directories (#512)

Summary

• The worker's artifact scan (packages/sdk/src/agent-artifacts.ts) skipped
  every directory entry whose name began with a dot. Nothing an agent wrote
  under .workflow-artifacts/ — the conventional artifact directory — ever
  reached the journaled output.artifacts, so an artifact_exists gate naming
  such a path could never pass. It failed as a bare retries_exhausted exit=1
  on a file sitting on disk, with nothing in the completion to say why.
• Replaced the blanket dot-prefix skip with an exact-name set — .git,
  .relayflowd, node_modules — matched at any depth and applied before the
  entry's type is consulted, so a linked worktree's regular .git file is
  skipped as surely as a .git directory, while .github, .relayflowd-notes
  and every other author-chosen name that merely starts the same way stays
  eligible.
• The gate is unchanged: it still reads the journal and never the disk. The fix
  is that the journal now describes what the agent actually wrote.

Commit: 6990e55, on relayflow/flows-software-garden-f1a04253.

Scope

Followed reviewed-plan.md, which selected the inclusion route of the
ticket's "either / or" acceptance. Deliberately not done, per that review:

• No flows check / gate_path_excluded refusal. namedGateErrors sees no
  worker transport or output provenance, an author-supplied JSON output can
  legally contain any path, and checkTypeScriptFlow does not execute an
  authored body — a global path prohibition would be a new producer-aware
  contract, not one cheap branch.
• No artifacts.include opt-in, no .gitignore handling, no kernel change,
  no change to the subprocess_gate stdio loss (A failing subprocess_gate journals empty stdout/stderr: the lowering uses stdio:'inherit' and the daemon's stdio is captured nowhere #511).

Known limitations left standing and still documented: a content diff proves a
change during the interval, not authorship; a JSON-shaped final message still
journals no artifacts; the relay transport journals none.

Files

File	Change
packages/sdk/src/agent-artifacts.ts	SKIPPED_DIR_NAMES → SKIPPED_ENTRY_NAMES (.git, .relayflowd, node_modules); blanket dot-prefix skip removed; scan semantics documented beside the code
packages/sdk/tests/agent-artifacts.test.ts	4 new scan cases (dot-directory artifact, eligible dotfiles/lookalike names, exact exclusions at root + nested, regular .git file) replacing the old blanket-exclusion test
packages/sdk/tests/artifact-gates.test.ts	worker test now expects .workflow-artifacts/x/y.md and excludes .git; new lowered-gate test pinning journal-only judgement on a dot path; namedGateErrors accepts the dot path
packages/sdk/tests/agent-artifacts-live.test.ts	added agent-2 writing and gating .workflow-artifacts/x/y.md, asserted from the real step.completed
docs/SURFACE.md	artifact section rewritten: exact-name exclusions, dot-directories are artifacts, regular-file/symlink/new-or-changed semantics; obsolete ownEvidencePaths prose corrected to the subtree exclusion worker-cli.ts actually implements

Test plan / evidence

All commands run from the repo root unless noted. Captures are in /tmp/flows-512/.

Full SDK suite

npm run test --prefix packages/sdk

 Test Files  6 failed | 148 passed | 3 skipped (157)
      Tests  18 failed | 2379 passed | 25 skipped (2422)
     Errors  1 error
   Duration  209.19s
EXIT=1

The three affected suites pass:

 ✓ tests/artifact-gates.test.ts (7 tests) 179ms
 ✓ tests/agent-artifacts-live.test.ts (5 tests) 39404ms
 ✓ tests/agent-artifacts.test.ts (9 tests) 18ms
 ✓ tests/wrapper-artifacts-cwd.test.ts (2 tests) 70ms

The 18 failures are pre-existing and environmental

Baseline: git stash push -u, rebuild, run only the six failing files at
e21caad (HEAD before this change):

npx vitest run tests/authored-node-runtime.test.ts tests/mcp.test.ts \
  tests/communication-mixed-resume.test.ts tests/live-kernel.test.ts \
  tests/provider-trigger-executor.test.ts tests/webhook-live.test.ts

 Test Files  6 failed (6)
      Tests  18 failed | 50 passed | 18 skipped (86)

The failing set is byte-identical to the one in the changed tree:

diff baseline-fails.txt change-fails.txt && echo "IDENTICAL FAILURE SET"

IDENTICAL FAILURE SET

Their causes are all sandbox environment, not code:

• spawnSync …/kernel/target/debug/relayflowd ENOENT — ops/cargo.sh puts the
  build output outside the repo on purpose; these tests hard-code the in-repo
  path (provider-trigger-executor, live-kernel, webhook-live, mcp).
• expected '1.3.6' to be '1.4.0' — the sandbox's bun is older than
  authored-node-runtime.test.ts requires.
• bad_request: unknown field 'required_streams' — the prebuilt relayflowd on
  PATH predates the current protocol (communication-mixed-resume).

I did not attempt to fix these; they are unrelated to this change.

Mutation verification

Meaning per AGENTS.md: the specific change reverted, the specific tests run
and failing captured, the change restored byte-for-byte, re-run and passing
captured. Both executions and the exact restoration actually happened.

1. Reverted — line 58 of agent-artifacts.ts put back to
if (entry.name.startsWith('.') || SKIPPED_ENTRY_NAMES.has(entry.name)) continue;,
rebuilt, then:

npx vitest run tests/agent-artifacts.test.ts tests/artifact-gates.test.ts tests/agent-artifacts-live.test.ts

   × snapshotWorkspaceFiles / diffWorkspaceFiles > reports a file the agent wrote under a dot-directory 6ms
   × snapshotWorkspaceFiles / diffWorkspaceFiles > keeps ordinary dotfiles and author dot-directories eligible, including names that merely resemble exclusions 2ms
   × worker-side artifacts > journals the files the CLI created or changed in its cwd, content-hashed, including dot-directories, with .git and node_modules excluded 25ms
   × agent artifacts and gates through the built CLI, a real daemon and the local agent > journals the files the agent wrote, including under a dot-directory, and every artifact gate passes on that journal 15212ms
 Test Files  3 failed (3)
      Tests  4 failed | 17 passed (21)

The live failure reproduces the reported shape exactly — a gate that cannot
pass, with nothing to inspect:

FAILED [step_failed] Run "01M2ZWKTCY4612ZV4S33GV3QQ8" failed with completionReason: step_failed.
Step "agent-2.gate" (deterministic) completionReason: retries_exhausted attempt=1/1 exit=1.

and the unit failure names the dropped paths:

AssertionError: expected [] to deeply equal [ …(2) ]
- Array [
-   ".workflow-artifacts/reviews/edited.md",
-   ".workflow-artifacts/x/y.md",
- ]
+ Array []

2. Restored byte-for-byte — the file was copied back from a pre-mutation
snapshot and the digest checked:

sha256sum packages/sdk/src/agent-artifacts.ts

3fbad9d4ea9e671df23d4f74e7f99b5180f29ddf5be238a95729c815ab7d24a6  packages/sdk/src/agent-artifacts.ts

(identical to the digest taken before the mutation)

3. Re-run, same three files:

 ✓ tests/agent-artifacts.test.ts (9 tests) 19ms
 ✓ tests/artifact-gates.test.ts (7 tests) 243ms
 ✓ tests/agent-artifacts-live.test.ts (5 tests) 45941ms
 Test Files  3 passed (3)
      Tests  21 passed (21)

Acceptance mapping

Ticket requirement	Evidence
An agent writing .workflow-artifacts/x/y.md has that path in its journaled artifacts	agent-artifacts-live.test.ts: real built CLI + real daemon + local agent; step.completed.output.artifacts for agent-2 equals ['.workflow-artifacts/x/y.md'] and agent-2.gate completes success
A test pins a dot-directory artifact path	Three levels: scan diff (agent-artifacts.test.ts), worker output (artifact-gates.test.ts), journal + gate (agent-artifacts-live.test.ts)
Gate stays journal-honest	New lowered-command test: passes on journaled input with no such file on disk, fails when absent from input with the file on disk
Exclusions are inspectable	Exact names documented beside the scanner and in docs/SURFACE.md, pinned by tests at root and nested depth

Notes

• Environment setup needed before the suite would run at all: npm ci for
  packages/surface and packages/sdk, npm run build in packages/surface,
  then npm install ./packages/surface --prefix packages/sdk --no-save --ignore-scripts and a root node_modules/@relayflows/surface link — the
  same sequence .github/workflows/cloud-runtime-artifact.yml uses. No
  committed file was changed for this.
• plan.md and reviewed-plan.md are left untracked and uncommitted.
• Not merged; leaving that to a human per AGENTS.md.

---

Note

Medium Risk
Changes which files are journaled as agent artifacts and can affect artifact_exists gates and any flow asserting on AgentResult.artifacts; behavior is intentional but broadens inclusion of dot-path writes.

Overview
Fixes artifact journaling so paths under dot-directories (especially .workflow-artifacts/) appear in output.artifacts and artifact_exists gates can pass.

The workspace scanner in agent-artifacts.ts no longer skips every name starting with .. It only skips exact entry names at any depth: .git, .relayflowd, and node_modules (including a worktree .git file). Dotfiles and paths like .github/ or .relayflowd-notes/ are scanned and diffed like any other regular file.

docs/SURFACE.md is updated to match: content-based diff rules, dot-directories as artifacts, and that the worker excludes the whole configured data-dir subtree (not a per-file ownEvidencePaths list). Tests cover unit scan/diff, mocked worker output, live CLI + daemon flows, and journal-only gate behavior for dot paths.

^{Reviewed by Cursor Bugbot for commit 6990e55. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

Summary by cubic

Fixes the worker artifact scanner so files agents write under dot-directories like .workflow-artifacts/ are journaled, which lets artifact_exists gates on those paths pass instead of failing with a bare retries_exhausted on a file sitting on disk.

• The old scan skipped every name starting with a dot; the new one excludes only .git, .relayflowd, and node_modules, matched exactly at any depth, so a worktree's regular .git file is skipped while .github and .relayflowd-notes stay journaled.
• The gate still reads the journal and never the disk — the fix is that the journal now describes what the agent actually wrote.
• The 18 failures in the full SDK suite are pre-existing and environmental; the affected suites pass.

^{Written for commit 6990e55. Summary will update on new commits.}

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: ff629800-14b3-43b0-92bd-020cba4ffde2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}