Repository navigation
v7.204.10
Unclaimed .swarm/ directories get a lifecycle
What
The retention sweep only ever reclaimed the .swarm/ families it hardcoded,
and blocked every other delete under .swarm/ — so any directory a subagent
wrote outside that closed set had no lifecycle at all and no supported command
could reclaim it. One production project had 140 MB of its 166 MB .swarm/
sitting in .swarm/review-sandbox and .swarm/review-mut, written by reviewer
subagents and reclaimable by nothing.
Directories immediately under .swarm/ now have three tiers of ownership:
- Tier 1 — hardcoded preserve allowlist. Swarm's own state (database and
sidecars, memory, evidence, plan store, knowledge, session/summary state,
every retention family root, skill stores, locks, quarantine, …) is never
pruned by the catch-all, whatever its age. - Tier 2 — owner manifests.
.swarm/retention.d/<owner>.json:
{ "owner": "reviewer", "preserve": ["review-sandbox"], "maxAgeDays": 90 }.
One file per owner and one writer each, so there is no shared file to merge
and no cross-agent edit surface — a single shared config key would turn
every new scratch owner into a conflict in one file. A claim is a lease, not
a permanent exemption: the claim SETS the directory's horizon to its
maxAgeDays(longer or shorter than the 30-day default), and past it the
directory becomes reclaimable again, because a claim that never expires
would recreate the very defect this fixes. A malformed, ambiguous, or unreadable manifest
refuses the whole sweep (fail closed) and names the file and the reason. - Tier 3 — catch-all. An unclaimed directory is pruned only when it is a
real directory (never a symlink), has no.preservemarker, contains no
future-dated entries, and all of its content is older than its horizon
(30 days by default, or the owning manifest'smaxAgeDays). The pass
refuses to run when.swarm/retention.logis a link, is not a regular file,
or cannot be inspected, so a prune is not started against a log it cannot
record to (a permission failure on a regular log still surfaces only after
the deletes, inresult.errors); after the deletes, every pruned path is appended to the
log as<ISO-8601> pruned <path> age=<days> size=<bytes>(control characters
in a name are escaped), and the log itself is compacted to its newest
256 KiB.
retention.dry_run (runRetentionSweep({ dryRun: true })) keeps its existing
count-and-report behaviour and now also populates result.explained with every
planned prune (path, age, size, owning manifest) and writes that list to the
debug log (visible only with OPENCODE_SWARM_DEBUG=1), which is how an operator previews what the catch-all would remove
before enabling it. It deletes nothing: no family file and no directory.
Containment has three layers. The catch-all refuses to run at all when .swarm
is itself a link (a .swarm linked to the project root would otherwise make
.git and src look like unclaimed children). Each candidate must be a real
directory, not a link. And each candidate is realpath-ed and required to be an
immediate child of the realpath-ed .swarm root immediately before deletion;
this narrows, but cannot close, the window in which a parent could be swapped
for a link, and that window needs write access to .swarm.
Why
An unbounded, unreclaimable directory family is a disk-exhaustion defect with
no operator remedy: the shell guardrails refuse an unsanctioned recursive
delete, and the sweep refused every path it had not been taught. The three
tiers restore the missing lifecycle without weakening either safety property
that caused the refusal — swarm's own state stays untouchable, and an
ownership claim that cannot be parsed stops the sweep rather than being
treated as permission to delete.
Migration
No config key and no API removal, but this release deletes data on upgrade:
- The first sweep after upgrade deletes unrecognised
.swarm/directories
whose newest file is older than 30 days. The sweep runs at every session
start and before/swarm close, withretention.enableddefaulting to on.
The tier-1 allowlist covers the directories swarm itself writes (a unit test
checks it against the retention registry), but anything else under.swarm/
that you or a tool put there — scratch trees, hand-made backups, exported
reports — is reclaimable. - To keep a directory: put a
.preservefile in it (permanent), or declare it
in.swarm/retention.d/<owner>.json(a lease with its ownmaxAgeDays). - To preview first: set
retention.dry_run: trueand run with
OPENCODE_SWARM_DEBUG=1; the planned prunes are then written to the debug
log (without that variable the log is silent) and nothing is deleted. To opt out entirely:
retention.enabled: false(this also disables every other retention
family; there is no catch-all-only switch). - A malformed
retention.dmanifest refuses the whole sweep, family prunes
included; the reason is in the debug log. RetentionSweepResultgains an optionalexplainedfield (populated under
dryRun); it is additive.
Caveats
- The catch-all runs last in the sweep, so a sweep cancelled by its budget
leaves unclaimed directories for the next pass (retention is idempotent and
runs at every session start and before/swarm close). - Claim expiry is measured from the newest file in the claimed subtree, so an
owner that keeps writing into a claimed directory keeps its lease. - A directory whose content cannot be enumerated within the bounded subtree
scan (2000 entries, counting files, directories and links) is treated as in
use and kept, and the sweep reports it (result.errors['.swarm/<name>'], in
the debug log) so an operator can tell why a large stale tree is never
reclaimed. Large source-tree-like sandboxes exceed this budget: mark them
with.preserveor remove them by hand. - Age is the newest regular-file mtime in the tree. Copies that preserve
mtimes (cp -a, tar, WindowscopyFile) look old on the day they are made,
so put a.preservemarker in a freshly copied scratch tree you want to
keep. - The scan cost is per candidate directory and synchronous; a
.swarm/with
thousands of large unclaimed directories makes the first sweep slow.
Verification-surface, dispatch-resilience, and redaction residuals from the 3718/3719/3720 rounds
Collated fixes for #3716, #3723, and #3724 — the residuals filed from the
three most recent merged PRs:
- The config-schema drift gate can now fail (#3724 item 1): the drift
job'sbun installno longer runs package lifecycle scripts
(--ignore-scripts), so a committedopencode-swarm.schema.jsonthat
drifted from the locked-toolchain generator is no longer silently
regenerated to green before the check reads it. ThelocalWorkflowHashes
evidence entry fordrift-check.ymlis refreshed for the workflow edit. - A deterministic HTTP 403 no longer burns the epic fallback chain
(#3724 item 2): the epic phase-review rethrow preserves the
provider-message carrier (providerMessageErrorToError), so the
model-fallback chain classifies from the carrier snapshot — a 403 whose
text carries rate-limit wording no longer classifies transient; genuine
429s still fail over and carrier-less errors keep the raw-text arm. - A Lean Turbo lane that produced real output is no longer stranded
(#3724 item 3): a reply with non-empty text parts plus a provider error now
settles under the same real-output contract asdispatch-lanes(lane
completes, worktree merged back); provider errors with no text still fail
closed. - Duplicate context owner records are rejected (#3716 item 1): the
required-check contract validator failsCONTRACT_MALFORMEDon owner
records sharing a context name instead of silently first-match-resolving. - The captured success set is producer-bound (#3716 item 2): the
mergeGroup.contextsderivation and the completeness loop share ONE
producer-binding rule (all-success + unambiguous agreeing app slug for
duplicates + repo-producer ownership for explicit slugs) — the name-only
trust surface is gone. - A null sandbox executor no longer pins for the process lifetime
(#3716 item 3): the executor cache keeps healthy executors permanent but
re-probes a null or rejected creation after a bounded TTL (60 s default,
SWARM_SANDBOX_EXECUTOR_FAILURE_TTL_MSoverride, finite-positive values
only) — the macOSPROBE_FAILURE_TTL_MSpattern applied to the executor
seam, with a construction DI seam for hermetic testing. - Long-header JWS tokens are fully redacted (#3723): both redaction sites
(shell audit + failure-evidence display) use a single-pass, linear-time
JWS span scan coveringx5ccertificate-chain headers of any length — on
the display sweep it runs on BOTH the raw and the zero-width-condensed
views; the payload and signature of a bare-placement token no longer
survive in clear text, and the #3710 disclosed over-long-header residual
is closed (its pin flipped to assert coverage).
Quarantine debt reaches zero — last four ledger entries retired
What changed
- All four quarantine ledgers now hold 0 active entries (windows 3 → 0,
macos 1 → 0; general and integration already 0). The Check 7 census prints
total active: 0/first hard-fail date: noneand the next-wall warning
is gone — the 2027-01-04 hard-fail wall is eliminated. Retired per
issues #2973 + #3218 with per-entry retirement bases recorded in the
ledger headers. tests/unit/hooks/pr-feedback-scope-controller.test.ts(macos entry,
#2973): the 2026-09-12 passed-on-retry flake's attempt-1 evidence was
recovered from the run's repository-validation artifact — the race test
expected exactly one fulfilled Task call and received zero. The race test
is now determinism-hardened: a bounded attempt-counted re-race (≤3) that
retries ONLY the two environmental shapes (shared pre-consumption
transient; winner-consumed-then-post-consume failure) with a disjoint
outcome classifier, fails immediately on any atomicity violation (two
fulfilled, two typed losers, foreign consumption), and pins the
designed-loser rejection reason — a discrimination the old assertion
lacked.- New spec
tests/unit/hooks/pr-feedback-scope-race-transient-2973.test.ts
pins the production semantics behind the flake: an injected pre-consume
transient makes BOTH racing calls fail closed non-destructively (the
declaration stays unconsumed), and the clean re-race reserves exactly once
with the typed loser on the other call. tests/unit/tools/dispatch-lanes-pr-review-resilience-followups.test.ts
(windows entry, #2973): the rawawait fs.rmteardown (zero EBUSY/EPERM
retry budget over a live WAL SQLite DB + git-init tree — the exact class
sibling retirements cured) is converted to the repo's guarded
safeRmRecursivewith the sibling's 30s hook budget. The un-stubbed
real-git preflight latency is a disclosed watch item: a re-flake
re-quarantines with fresh merge-group evidence per the #1782 convention,
and the per-attempt validation-report artifact carries attempt-1 stderr.- Four quarantine pin suites converted to retired-absence shapes
(ci-yml-quarantine-2730/3248-windows/3263/3264) with orphaned metadata
helpers removed; the windows ledger keeps a# STATUS: 0 active entries
header (the five relative-count suites pin declared == actual, whatever
it is). - The archive pair (#3218) needed no new code: PR #3672's determinism
hardening already landed; the entries' own skip behavior was the only
thing blocking the "2 consecutive green windows-latest merge-group runs"
criterion, which now accumulates from this PR's own queue run onward.
Why
The four remaining entries could not retire while active — the ledger skip
prevented the very home-platform executions their criteria required. Two of
them (#3251's probe race and the archive pair) were already root-fixed in
#3672; the macos race-test flake turned out to be a test over-specification
(the atomicity guarantee holds under the transient), and the windows
dispatch-lanes teardown carried a known-class deterministic hazard.
fix(tools): refuse planted links on the commit-message temp directory (#3486)
What changed
prepare_pr_feedback_commit_message wrote its authored message file into a
FIXED, predictable directory under the OS temp root
(<tmp>/swarm-pr-feedback-commit-msg). A symlink or NTFS junction planted at
that name redirected both the 24 h TTL prune (deleting stale .txt files in
the link target) and the authored write into an attacker-chosen directory: the
shipped "re-proof" was tautological (a path.join of a basename can never
escape the joined directory) and the only real check merely refused
repo-internal targets. Reachable on macOS after PR #3465 made the per-user
$TMPDIR writable inside sandboxed commands; bounded consequence (no code
execution, attacker controls neither filename nor content, only *.txt older
than 24 h were removed).
The tool now ACQUIRES the directory with a real proof before any use:
lstatrefusal for a planted symlink/junction or non-directory at the fixed
name; creation at mode0700with a post-create re-lstat(recursive
mkdirsucceeds over an existing junction on Windows, so the re-stat is the
actual create-race proof);- current-user ownership required and the exact
0700permission bits (the
nine owner/group/other bits,mode & 0o777) enforced/healed on POSIX (any
deviation in those bits — a legacy0755or a restrictive0500/0600
that would break the owner write — is healed to0700; POSIX special bits
such as setuid/setgid/sticky are outside this directory-ownership contract;
on Windows the per-user%TEMP%ACL is the ownership boundary and mode bits
are not a security boundary); - the TTL prune and the write use only the proven-real directory, and the
write carries a same-tickvalidateTargetre-proof at the atomic writer's
boundary, so a directory swapped for a link between acquisition and write is
refused too; - the realpath ancestor check (temp root resolving inside the repository) is
retained — it runs before the atomic writer yields and is not repeated at
the write boundary, so the same-tick re-proof guarantees the leaf directory
only; swapping an ancestor to point into the checkout during the yield would
require an unsandboxed same-user process with write access to the temp root's
parent, which is outside this issue's threat model.
The TTL prune is best-effort hygiene with its OWN same-tick lstat re-proof at
entry, and the write carries the same-tick validateTarget re-proof the atomic
writer already documents (FB-001): after each re-proof there is no awaitable
boundary before the synchronous filesystem operations, so an in-process task
that swaps the directory for a link during a yield is caught rather than
written/pruned through. As with every path-based check on a portable Node
runtime, a separate PROCESS racing the syscall boundary itself is outside this
guarantee — the threat closed here is the planted-persistent-link and
in-process-swap classes (the issue's model), not cross-process TOCTOU. New suite:
tests/unit/tools/prepare-pr-feedback-commit-message-symlink.test.ts.