Skip to content

docs(rfc): quarantine keeps only unsaved work, not the whole clone - #22428

Merged
chenmingwei23 merged 1 commit into
mainfrom
docs/rfc-quarantine-unsaved-only
Oct 20, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
docs/rfc-quarantine-unsaved-only

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record a design, for maintainers to judge, that lets the scratch quarantine keep only a dead clone's unsaved work instead of the whole clone.

Since #19897, every dead, idle scratch tree holding a git repository is moved whole into .quarantine and kept 14 days. On one host that reached 28 GB over 24 trees in about a day, and the 80 GB disk hit 99%. A Kiro Crew clone is about 4.2 GB; the unsaved work in it is usually KB to a few MB.

Why it matters

The quarantine fills the disk long before anything expires. The fix cannot just ask the clone whether its work is pushed: #19897 showed the clone's refs and config are agent-controlled. So the design needs to be agreed before any code.

Not a goal

  • No code change. This PR adds a draft RFC and its index row only.
  • Removing regenerable directories (node_modules, .venv); a sibling change on branch fix/scratch-delete-clean-trees does that.
  • Changing the 14-day expiry or what counts as a repository.

What changed (motivation → approach → change)

A dead clone costs gigabytes in .quarantine to protect kilobytes of work.

The RFC asks a trusted source, never the clone, which commits are saved: a gateway-owned mirror, or the hosting provider by SHA. Everything else becomes a small rescue: a git bundle of unsaved commits plus changed and untracked files copied verbatim. Git runs inside the agent sandbox with no network and program-naming settings forced off. Any failure or doubt keeps today's whole-tree move; nothing falls back to deleting.

Added What
docs/request-for-change/rfc-quarantine-unsaved-work-only.md the RFC: threat model, trusted store, rescue layout, fallback, sizes, recovery, phases, alternatives, open questions
docs/request-for-change/README.md one draft index row

Backwards compatibility

Compatible: docs only; no behaviour changes.

Removes nothing: the diff adds one document and one index row.

Tests

N/A — docs only. python3 scripts/docs_lint.py exits 0.

Manual verification

N/A — docs only. The cited symbols (sweep_dead_scratch, holds_git_repository, _quarantine, _expire_quarantine, QUARANTINE_TTL_SECONDS, wrap_argv) were checked on main at 6432cad9e.

Related Issues

Part of #22423

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners October 20, 2026 06:19
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Oct 20, 2026
@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision c39e7f3f941d0b82e7becf41ce4d18230ed21374 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision c39e7f3f941d0b82e7becf41ce4d18230ed21374 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Advisory — does not block merge.

@iamwhatever
iamwhatever force-pushed the docs/rfc-quarantine-unsaved-only branch from 1f76723 to e18ba31 Compare October 20, 2026 06:20
@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of c39e7f3f941d0b82e7becf41ce4d18230ed21374 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Maintainers should first accept that default hosts gain nothing until open question 9 is answered. Until then the sibling PR is the only shrink for them.

[DESIGN-REVIEWED] c39e7f3

Description read

[DESCRIPTION-READ] 7a49b7f4d79772f539c7f5947deb2f2372e6616fd8f967d99d631205616ffacb

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 20, 2026
@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of c39e7f3f941d0b82e7becf41ce4d18230ed21374 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] c39e7f3

False positive or not applicable? A repository writer can comment:
/ai-review override gpt c39e7f3f941d0b82e7becf41ce4d18230ed21374: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed c39e7f3f941d0b82e7becf41ce4d18230ed21374 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] c39e7f3

Verdict parsed from the review's SHA-scoped output markers for commit c39e7f3f941d0b82e7becf41ce4d18230ed21374.

False positive or not applicable? A repository writer can comment:
/ai-review override fable c39e7f3f941d0b82e7becf41ce4d18230ed21374: <one-sentence reason>

@iamwhatever
iamwhatever force-pushed the docs/rfc-quarantine-unsaved-only branch from e18ba31 to cb57e88 Compare October 20, 2026 06:28
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • Punchline: with no trusted store configured, every clone falls back to the whole-tree move

fixed in cb57e88: correct, and the RFC now says so in a "With nothing configured" paragraph.
A host with no mirror and no provider credential gets no saving from this RFC; only the sibling regenerable-dir change helps it.
Phase 3 (default on) is now blocked on open question 9: how a host gets a trusted store without setup.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=2329f377ab6a line 145: a mirror outside the scratch root is still reachable by the sandbox

fixed in cb57e88: legitimate, the sandbox hides a fixed list of paths, not everything outside the scratch root.
The mirror dir git-mirrors is now a new top-level leaf in _CREW_HIDDEN_LEAVES (src/kiro_crew/sandbox_leaves.py), masked in every sandbox mode.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=2329f377ab6a line 148: a bare clone has no fetch refspec, so its branches freeze

fixed in cb57e88: legitimate. The gateway now sets remote.origin.fetch to +refs/heads/*:refs/heads/* and +refs/tags/*:refs/tags/* right after git clone --bare, then runs git fetch --prune.
Without it a plain fetch only writes FETCH_HEAD, as the finding says.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=2329f377ab6a line 330: recovery commands never apply deleted.txt

fixed in cb57e88: legitimate. The recovery block now removes the files listed in deleted.txt after copying changed/ and untracked/, matching the round-trip verify.

@iamwhatever
iamwhatever force-pushed the docs/rfc-quarantine-unsaved-only branch from cb57e88 to aa4512c Compare October 20, 2026 06:38
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • Punchline: open question 9 needs a decision before Phase 3

needs-a-decision: agreed, and the RFC already blocks Phase 3 on it. This is the maintainers' call, asked directly:
@kirodotdev maintainers - for hosts with nothing configured, should the gateway offer to create a mirror on the first fallback, or should Phase 3 wait for the provider kind?
Phases 1a, 1b and 2 do not depend on the answer.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=2329f377ab6a line 279: "as today" misdescribes the look under the sweep lock

fixed in aa4512c: legitimate. Today the look under _SWEEP_LOCK is only os.lstat of the tree's root.
The RFC now calls the pre-delete check new and stronger: owner marker re-read and a full-tree mtime walk, both under the lock.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=2329f377ab6a line 503: open question 1 compares the mirror with 1.8 GB per clone

fixed in aa4512c: legitimate. 1.8 GB is only .git; open question 1 now compares with ~4.2 GB per clone today, ~2.6 GB after the sibling PR.

@iamwhatever
iamwhatever force-pushed the docs/rfc-quarantine-unsaved-only branch 2 times, most recently from b5716b2 to f1eec53 Compare October 20, 2026 06:48
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • Punchline: sandbox mode "off" must route to the whole-tree fallback

fixed in f1eec53: new invariant in "Where git runs": the helper starts only when the wrapper confirms, for that launch, sandbox on (mode not off), network denied and tree read-only; otherwise whole-tree fallback.
The same check is in the step flow, the threat table, and the Phase 1a exit criteria.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=2329f377ab6a line 334: helper-written deleted.txt is piped to rm by the recovery steps

fixed in f1eec53: the recovery shell block is removed. New invariant: rescue contents are agent-influenced data; RESCUE.md is written from the gateway's own template and never tells the user to feed a rescue file to a command.
deleted.txt is a list to read and act on by hand. A threat-table row records this.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=2329f377ab6a line 243: round-trip verify is impossible for the provider kind

fixed in f1eec53: verify is now a requirement (evidence the rescue reproduces every unsaved tip and file byte for byte), with the mirror round trip as one way to meet it.
How the provider kind verifies is open question 3; Phase 2 is blocked on it, and until then the provider kind always falls back.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=2329f377ab6a line 166: rev-list stops with bad object on SHAs the mirror lacks

fixed in f1eec53: the command is removed. The rule is stated instead: saved only if reachable from a branch or tag of the store, and an id the store lacks is not saved. Commands are Phase 1b's to choose.
Retrospective (round 3, span 2329f377ab6a is path+lane coarse; 3 rounds): the RFC now states requirements and invariants, not git commands, for the mirror check, refspec, bundle naming, change detection and the -c list.

@iamwhatever
iamwhatever force-pushed the docs/rfc-quarantine-unsaved-only branch from f1eec53 to 8a6c58a Compare October 20, 2026 06:57
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=4b60ab6a1cbf: the final look under the lock costs more than the RFC says

fixed in 8a6c58a: the final look under _SWEEP_LOCK is removed. The sweep's step is unchanged (today's cheap look and whole-tree rename); a new shrink pass then works only on trees already in .quarantine and never takes _SWEEP_LOCK.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=6e3532c0ab35: a full lstat walk under the lock blocks every spawn handoff

fixed in 8a6c58a: no walk runs under any lock. The shrink pass's re-walk is lock-free, and a Phase 1b exit criterion asserts a spawn's scratch handoff is not delayed during a shrink.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • Punchline: a verify pass reported by the helper is still evidence the agent wrote

fixed in 2007949: new invariant, the verdict is the gateway's. A second sandboxed helper rebuilds the work in a fresh clone of the mirror (gateway config only, none of the agent's config, filters or hooks), using plain file copies.
The gateway then compares rebuilt and original trees itself, reading bytes with lstat and no git; any difference means the fallback.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=2329f377ab6a line 195: a staged version edited again is lost

fixed in 2007949: legitimate. A new staged/ part keeps, as raw bytes, every index entry that differs from both HEAD and the worktree, and verify now covers every staged entry.

@iamwhatever
iamwhatever force-pushed the docs/rfc-quarantine-unsaved-only branch from 2007949 to 24b7a0c Compare October 20, 2026 07:15
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=2307a950eaca: verification costs the most disk exactly when disk is short

fixed in 24b7a0c: verify checks out no working tree. A bare repository borrowing the mirror's objects fetches the bundle and lists each tip's tree; the gateway hashes the original files against that listing.
Extra disk per tree is about the rescue's size (KB to a few MB), freed before the next tree, so at 95%+ full the pass still makes progress; a new "Disk cost of verify" paragraph and test say so.
Trade-off recorded: staged/ (index state) is not proven and RESCUE.md marks it unverified; every worktree file is proven.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=8329887b344f: with nothing configured, the new machinery changes nothing

fixed in 24b7a0c: took the second clearing option. The RFC now states Phases 1a, 1b and 2 ship only for operators who opt in by configuring a mirror (or later a provider credential), and accepts that a default host gains nothing until open question 9 is answered.
Reason recorded: the hosts that fill their disk this way develop Kiro Crew itself, where one mirror is a one-line setup.

@iamwhatever
iamwhatever force-pushed the docs/rfc-quarantine-unsaved-only branch from 24b7a0c to 20c035c Compare October 20, 2026 07:22
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=66064cb5b1fd: the mirror is hidden from the helper that verify depends on

fixed in 20c035c: legitimate contradiction. The verify helper's launch names that one mirror in extra_visible_dirs, lifting the hidden-leaf mask for that one fixed-argv child only (the existing aws-control-staging pattern), mounted read-only via the Phase 1a mount.
Agents and every other helper still see it masked; a Phase 1a exit criterion now tests the lift and that a sibling launch stays masked.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=60978c83828c: a per-launch read-only exception to the hidden leaf

fixed in 20c035c: this is the option taken, as described in the span=66064cb5b1fd reply: one mirror, one fixed-argv child, read-only.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=f528cf40bb3d: give the verify helper a read-only copy of only the prerequisite objects

rebutted: a copy of the prerequisites needs their whole ancestry for the bundle fetch to connect, which for a Kiro Crew clone is most of the 1.8 GB object store, so it brings back the disk cost the previous round removed.
A read-only lift of the existing mirror costs no disk and exposes nothing writable.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=a2dc08d7afc9: the default host gets nothing

fixed in 20c035c: took the second clearing option. The RFC now states plainly that for default hosts the fix is the sibling PR (regenerable directories dropped with no setup, ~4.2 GB to ~2.6 GB per clone), and this RFC is opt-in until open question 9 is answered.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=2329f377ab6a line 322: verify helper borrows the mirror, but the mirror is a hidden leaf

fixed in 20c035c: legitimate. The verify helper's launch lifts the mask for that one mirror, read-only, through extra_visible_dirs, the same per-child lift aws-control-staging already uses; every other launch keeps it masked.

@iamwhatever
iamwhatever force-pushed the docs/rfc-quarantine-unsaved-only branch from 20c035c to cd20046 Compare October 20, 2026 07:31
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • Punchline: is an opt-in-only gain worth two new wrap_argv features?

needs-a-decision: this is the maintainers' call at review, and the RFC already states the trade ("This RFC accepts that trade") and open question 9.
@kirodotdev maintainers - the question is whether Phases 1a/1b are worth shipping for opted-in hosts before open question 9 has an answer, with the sibling PR as the fix for default hosts.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=2329f377ab6a line 395: recovery steps feed rescue files to git, against the data-not-instructions invariant

fixed in cd20046: legitimate contradiction. Recovery checks out each tip by a gateway-validated full SHA from RESCUE.md, not a name from refs.txt.
The invariant now says RESCUE.md never puts a helper-written name or path into a command; the only rescue file handed to git is commits.bundle, which verify has proven.
Retrospective (round 7, span recurs as path+lane): verify, crash safety and boundary pinning shrank to requirements; mechanisms moved to Phase 1b or open question 10; the doc went from 574 to 548 lines.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • Punchline: the shrink pass drops commits no ref or reflog reaches (e.g. dropped stashes)

needs-a-decision: correct, and it is the open trade in open question 5 (a git fsck pass for dangling commits, or "the agent hid it" as the line). Today's whole-tree quarantine keeps them; the RFC lists this under Non-goals.
@kirodotdev maintainers - please rule on open question 5 at review; no text change is made here.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Backend Tests (Windows) (3) is red on this head from main, not from this docs-only diff:
test/test_chat_follow_default_slot_kinds.py::TestSlotCreatorRegistry::test_no_stale_entry and ::test_every_creator_is_classified fail because #22079 moved _import_thread_to_slot from slack/interactions.py to slack/interactions_options.py.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 20, 2026
Propose replacing the whole-tree scratch quarantine with a small rescue:
commits a trusted object store does not have, as a git bundle, plus changed
and untracked files verbatim. Git runs inside the agent sandbox with no
network; any failure or doubt keeps today's whole-tree move. Adds the
index row in docs/request-for-change/README.md.
@iamwhatever
iamwhatever force-pushed the docs/rfc-quarantine-unsaved-only branch from cd20046 to c39e7f3 Compare October 20, 2026 08:39
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased onto main carrying #22433; CI re-running.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 20, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • Punchline: maintainers should accept that default hosts gain nothing until open question 9

needs-a-decision: already stated in the RFC ("For default hosts, the fix is the sibling PR"; "This RFC accepts that trade") and put to maintainers in the earlier disposition on open question 9. No text change.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 20, 2026

@mbriones98 mbriones98 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Checks green and readiness passed at c39e7f3; no behavior change.

@chenmingwei23
chenmingwei23 merged commit 1d5d777 into main Oct 20, 2026
104 checks passed
@chenmingwei23
chenmingwei23 deleted the docs/rfc-quarantine-unsaved-only branch October 20, 2026 13:54
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants