Skip to content

fix(snapshot): scope the size estimate and skip entries the process cannot read - #11418

Merged
chenmingwei23 merged 1 commit into
mainfrom
fix/snapshot-unreadable-entries
Sep 19, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
fix/snapshot-unreadable-entries

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

kirocrew snapshot dies with a traceback on a data home that holds a protected file
the process cannot stat. No bundle is written, and --components config,memory
fails exactly the same way, so nothing can be backed up at all.

File ".../kiro_crew/snapshot.py", line 2070, in <genexpr>
    f.stat().st_size for f in mc.rglob("*") if f.is_file() and not f.is_symlink()
File ".../pathlib.py", line 892, in is_file
    return S_ISREG(self.stat().st_mode)
PermissionError: [Errno 1] Operation not permitted: '.../token_signing.key'

Why it matters

Snapshot is the sanctioned backup path. The docs tell people to take one before a
risky step, so this breaks the tool at the exact moment it is needed. Data homes
holding a platform-protected path are ordinary, not exotic, and there is no way to
work around it from the command line.

What changed (motivation → approach → change)

The size estimate measures the snapshot you asked for, staging no longer stops over an
entry it may not read, and a bundle that omits anything does not prune older backups.

Entry in the data home Before After
Anything outside the selected components 🟥 walked and stat-ed 🟩 never looked at
A protected file no component wants 🟥 kills the command 🟩 never looked at
A refused file the estimate meets 🟥 kills the command 🟨 counted, one stderr line
A refused file inside a staged tree 🟥 kills the snapshot 🟨 skipped, named in MANIFEST.json
A refused directory inside a staged tree 🟥 kills the snapshot 🟨 skipped, named in MANIFEST.json
A tree's own root, refused at the listing 🟥 kills the snapshot 🟨 skipped, named in MANIFEST.json
A tree's own root, refused at the stat 🟥 dropped, unrecorded 🟨 skipped, named in MANIFEST.json
A directory that opens but refuses to be LISTED 🟥 kills the snapshot 🟨 skipped, named in MANIFEST.json
A Windows junction nested inside a selected tree 🟥 estimate walks into it 🟩 pruned before descent
A tree's own root that is simply absent 🟦 dropped silently 🟦 dropped silently
A tree's own root on a failing disk (EIO) 🟥 dropped, unrecorded 🟦 stops
--keep after a run that omitted anything it was asked to carry 🟥 prunes anyway 🟩 does not prune
--keep after a run that only screened a symlink 🟦 prunes 🟦 prunes
A regular file swapped for a link or FIFO mid-copy 🟥 reported as a screen, prunes 🟨 identity_changed, does not prune
A file a component DECLARES 🟦 stops 🟦 stops
A refusal to WRITE the staged copy 🟦 stops 🟦 stops
A failing disk (EIO) 🟦 stops 🟦 stops
Restore or merge meeting a refused entry 🟦 stops 🟦 stops

🟩 added · 🟨 changed · 🟥 removed · 🟦 unchanged

The estimate exists for one "this may be large and slow" warning, and it walked the whole data
home before --components narrowed anything — so a protected file no component wants killed the
command, and narrowing could not work around it. It now measures the selection, counts a refused
entry instead of raising, and says how many it could not read.

Staging a component TREE reads arbitrary user content, so a refusal there is a file the bundle
wanted and cannot have: skipped, printed, and recorded in MANIFEST.json's existing skipped
list as unreadable_entry, the same treatment a symlink already gets. Files, directories and a
tree's own root are covered on both traversals — the descriptor-pinned walk in
src/kiro_crew/pinned_fs.py and the by-name walk a platform without directory descriptors takes.
Every entry, and the loop's own tree root, is classified by an explicit stat FIRST, because
os.path.isdir, os.path.islink and Path.is_dir() all answer False for a path they cannot
stat — which reads a refusal as an ordinary absence. Only ENOENT is absence; EIO, ESTALE
and ENOTDIR propagate.

Retention is what makes tolerating an omission safe. --keep ranks bundles by mtime alone,
so an incomplete bundle displaced a complete one and reported success. A run that omitted
anything it was asked to carry now skips pruning and names the reasons. The guard asks a CLASS,
never a reason code: pinned_fs.omits_wanted_data() is the one public question, backed by a
private split kept next to the codes; a code the split does not know counts as incomplete, because a surplus bundle costs disk where a
wrong prune costs the last complete backup; and a test asserts the split covers every code, so
one added later cannot silently start pruning. Suppressing the prune on ANY recorded skip was
simpler and wrong — symlink is screened on every run, so any data home holding one would stop
pruning forever. For the split to hold, symlink and not_regular have to mean a FIRST look:
the pinned walk now hands the copy the inode it judged, and a link or FIFO found at that name
afterwards — the same-UID swap the module is built to refuse — is reported as
identity_changed, on the omission side, instead of under a screen code.

Four places still fail hard, because failing is safer: a file a component declares, the
database re-copy pass at both ends, restore and merge, and any refusal to WRITE.
docs/system-specs/modules/cli.md documents the tolerance and its scope.

Tests

test/test_snapshot_unreadable_entries.py, 66 cases. They deny stat, open, scandir or
listdir for one named entry, which is deterministic on Linux, macOS and Windows where
chmod 000 is not — and the platform-protected class of file cannot be created by a test at
all. Both traversals are exercised everywhere, including on a host that supports only one.

They lock in: a full and a --components-scoped snapshot both succeed with an unreadable file
at the data-home root, which the estimate never looks at; the stderr count line, its wording
and its count when the selection overlaps; a refused file, a refused directory, a directory
whose stat is refused too, and a tree root refused at either its listing or its stat, each
skipped and recorded — while a tree root that is merely ABSENT is recorded as nothing and
still prunes normally, and a root on a failing disk raises instead of being skipped; a file whose
metadata reads but whose bytes are refused, reaching the refusal at a different syscall on each
traversal; an unreadable database never reaching the restage pass; an EIO raised rather than
counted; a destination-side refusal propagating rather than being recorded as an unreadable
source; a prior complete archive surviving --keep 1 against a bundle with omissions, and an
ordinary run still pruning; and — the other half of the switch — that a default-argument walk
still RAISES and records nothing, so restore cannot silently become skip-and-drop.

Every guard was mutation-checked: reverting any one of thirty-one turns at least one test red,
with nothing skipped. The four for the root probe include both plausible WRONG fixes —
recording an absent tree as an omission, which passes the refusal tests and breaks
retention for every fresh data home, and widening the absent branch back to every
OSError, which hides a failing disk.

Manual verification

N/A — unit coverage sufficient. The refusal is a platform behaviour that cannot be produced on
the CI hosts, so the tests deny the syscalls directly, which exercises both staging branches
instead of only the one the host supports.

Residual, filed not fixed. restore --mode replace clears a component tree and installs
the bundle's copy, so a file this change omitted is DELETED on restore — the manifest records
the omission and nothing on the restore path reads it. That is a change to what --mode replace
promises rather than a repair to this fix, and restore is an explicit non-goal here, so it is
tracked as #11499 with the reproduction and three candidate fixes.

A second residual, pre-existing and unchanged: a narrowed --components bundle also rotates in
the ordinary lane, so at --keep 1 a component-only bundle can displace a full one. The
selective path has always used the ordinary tarball name; closing it means deciding whether an
operator's own narrowing counts as incomplete.

Four pre-existing failures, none from this change. The related backend set is 41558
passed / 4 failed. One is
test_dev_fleet_app.py::test_trusted_bin_pins_the_resolved_target_not_the_symlink, which
reproduces on a pristine origin/main worktree. The other three are
test_pod_seed_scenarios.py::TestUpRefusesAnUnknownScenario, which cannot reach the
systemd user bus on this development host. None of the four touch snapshot.py or
pinned_fs.py.

Related Issues

no linked issue: reported directly, no public issue filed for the crash itself

Pattern harvest

Rule candidate: review-prompt
Pattern: a size or count walk over a whole store, run before the filter that would have
excluded the entry it dies on

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|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 cixuuz September 17, 2026 01:25
@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ human override accepted

Human judgment by @iamwhatever overrides the GPT 5.6 finding for 2c0a3cedc537886163b039d6f31734e6e00d088a; the recorded reason is authoritative for this commit.

This comment is updated in place on each push.

The model was not re-run because an authorized human decision supersedes it.

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

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 17, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Intent: Make kirocrew snapshot produce a backup on a data home that contains an entry the process cannot read, instead of ending with a traceback and writing nothing — and make the pre-flight size estimate describe the snapshot that was actually asked for.
Not a goal: Redesigning the snapshot format or its component set, making restore tolerant of an unreadable entry, or excluding anything new from a bundle.

@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — 🟡 CONCERNS

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

Design-Verdict: CONCERNS

A permanently protected in-tree file disables --keep forever: every bundle is equally incomplete, so the guard preserves nothing while snapshots accumulate unboundedly.

Watch

  • The retention guard's rationale ("the older complete bundle is the only complete one the operator will ever have") fails in the steady state the PR itself calls ordinary: a persistently unreadable file inside a selected tree means no complete bundle ever exists, every run prints the same warning and skips pruning, and a scheduled snapshot fills the disk with identical incomplete bundles — the diff's own comment concedes "A refusal that is NOT transient … holds the surplus."
    Clears when: pruning is permitted when the retained bundles record the same omission set (read from their MANIFEST.json), or a surplus cap bounds accumulation.
  • This PR makes omission-carrying bundles producible for the first time, and the acknowledged residual (restore --mode replace with a bundle that has recorded omissions deletes the live files it omitted #11499) means restore --mode replace then deletes the operator's ACL-unreadable-but-deletable file — the tolerance's "bundle with a named gap beats no bundle" premise inverts into data loss on the sanctioned restore path. A human should decide whether restore --mode replace with a bundle that has recorded omissions deletes the live files it omitted #11499 (or a restore-time warning when skipped is non-empty) must land first.
    Clears when: #11499 lands, or restore warns/refuses --mode replace when the bundle's manifest records omitted entries.

[DESIGN-REVIEWED] 2c0a3ce

@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 2c0a3cedc537886163b039d6f31734e6e00d088a — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify on a live data home that mid-walk vanished churn stays rare — it now holds the prune, and routine churn would idle --keep retention.

What this change ships

Inventory (10 items) — 10 justified

Intent: Make kirocrew snapshot produce an honest backup on a data home holding entries the process cannot read, without an incomplete bundle displacing a complete one — FIX.

  1. Snapshot no longer dies on a protected entry; each one is skipped, printed, and recorded in MANIFEST.json — justified
  2. The size estimate measures only the selected components, so a protected file outside them is never touched — justified
  3. A stderr line counts entries the estimate could not read — justified
  4. The estimate no longer follows a symlinked root or a Windows junction inside a selected tree — justified
  5. --keep skips pruning after a run that omitted wanted data, and names the reasons — justified
  6. An entry swapped after the walk's stat reports identity_changed instead of a screen code — justified
  7. The database re-copy pass no longer aborts the snapshot on a refused live .db — justified
  8. A refused selected-tree root is recorded; a failing disk there now aborts instead of silently dropping the tree — justified
  9. New pinned_fs surface: unreadable_entry, omits_wanted_data(), opt-in skip_unreadable (off for restore/merge) — justified
  10. cli.md documents the tolerance's scope and the retention class — justified

[FIRST-PRINCIPLES-REVIEWED] 2c0a3ce

@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

No findings.

Both candidates hinge on the new retention guard (omitted = [s for s in omissions if pinned_fs.omits_wanted_data(s["reason"])]) permanently disabling pruning via a persistent omission, and neither persistent path holds up:

  • db_unpinned_source (candidate 1) reaches _restage_databases's on_skip only when a destination byte copy already exists and _chain_is_link_free returns False. A persistent link in the chain (or a hardlinked/symlinked .db) is refused by the pinned tree walk itself (SKIP_NOT_REGULAR/SKIP_SYMLINK, both screens) and never gets a destination copy, so the destination-first dst.lstat() check ends the iteration before db_unpinned_source is ever recorded. It is only reachable via a walk↔restage TOCTOU race — transient, self-correcting on the next clean run, and it retains more backups (never data loss). The claimed "unbounded accumulation" outcome does not occur.

  • vanished (candidate 2) is deliberately placed in _OMITS_WANTED_DATA and its "effectively disables --keep on a busy home" outcome is stated as "can", requiring an unproven assumption that some non-_staging_ignored file inside a selected tree vanishes on every run. That is speculative, not an observable wrong outcome, and the behavior is an explicit, tested design choice.

[OPUS-REVIEWED] 2c0a3ce

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

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

@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 Sep 17, 2026
@iamwhatever
iamwhatever force-pushed the fix/snapshot-unreadable-entries branch from c4008f4 to 833a6b7 Compare September 17, 2026 02:19
@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 Sep 17, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: copy_file_pinned gains skip_unreadable; the source open alone reports SKIP_UNREADABLE_ENTRY.

  • span=37759b2ca7b9 — fixed in 833a6b7

Legitimate. The handler wrapped the whole copy_file_pinned call, so it could not tell
which end was refused. A destination-side EACCES was therefore recorded as an
unreadable SOURCE, omitting a file from the bundle, blaming the operator's data for it,
and reporting success — after which --keep can prune a bundle that was complete.
Rarity does not save it: the outcome is unbounded and irreversible.

Fixed as the finding asks, at the only place that can know which end failed. The
tolerance moved INTO copy_file_pinned as skip_unreadable, applied to the single
open that reads the operator's file; every write below it is untouched, so a
destination refusal propagates. Both call sites now hand the flag down instead of
wrapping the call: stage_tree_pinned's file branch and snapshot._copy_screened.

Pinned by three tests. A destination-denied copy_file_pinned with skip_unreadable=True
raises and records nothing; a source-denied one returns False, records
unreadable_entry, and leaves no destination file; a source-denied one with default
arguments still raises. Mutation-checked: removing the source-open branch, or dropping
the flag at either call site, each turns tests red.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: _ignore_unsafe classifies each entry with an explicit lstat before asking what kind of entry it is.

  • span=ee5aa1d6ec78 — fixed in 833a6b7

Legitimate, and reachable by the exact class this change exists for. Correcting the
mechanism: a readable-but-not-searchable directory (mode 0400) is not the trigger —
os.stat needs search permission on the PARENT, not on the directory itself, so
os.path.isdir answers True there. The trigger is a directory whose own stat is
REFUSED, which is the reported platform-protected class. os.path.isdir swallows the
OSError and answers False, the screen short-circuits, and copytree descends on the
directory ENTRY's d_type (no stat needed), meets the refusal at its own scandir,
collects it, and raises shutil.Error only after staging everything else. The
conclusion stands either way: no snapshot is produced.

Fixed as the finding asks. _ignore_unsafe now takes an explicit os.lstat per entry
FIRST and records a permission refusal there, before anything asks whether the entry is
a directory or a link — both of those predicates answer False for a path they cannot
stat, so neither can screen one. is_reparse_point and the listing probe run only on an
entry that classified.

Pinned by two new tests driving a stat-denied directory through each traversal, plus the
existing listing-denied pair. Mutation-checked: downgrading the new except PermissionError to st = None reddens the by-name case.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 17, 2026
@iamwhatever
iamwhatever force-pushed the fix/snapshot-unreadable-entries branch from 833a6b7 to 503a469 Compare September 17, 2026 03:15
@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 Sep 17, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: the estimate's stat and its os.walk onerror both absorb PermissionError only; every other errno is raised.

  • span=31b713b9db38 — fixed in 503a469

Legitimate, and it was an inconsistency with this change's own stated contract rather
than a disagreement. Both staging traversals had been narrowed to the permission class
on the argument that a backup which quietly omits files because the disk is dying is
the worst possible artefact. The estimate was left broad, so the one place that
SUMMARISES omissions as a bare count was the one place that would fold an EIO into
that count — and a number cannot say "the storage is failing", so the operator would
read it as a handful of protected paths.

Fixed as the finding asks. _count now catches PermissionError, not OSError. The
os.walk onerror sibling had the same shape and got the same treatment: absent
(FileNotFoundError/NotADirectoryError) still returns, because a component naming a
tree this home does not have is the normal case, PermissionError is counted, and every
other errno is re-raised.

Pinned by two tests, one per site: an EIO from the entry stat and an EIO from the
directory listing each propagate out of _estimate_selected_bytes with errno == EIO
rather than incrementing the tally. Mutation-checked: widening either back to OSError
reddens its own test.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: the estimate drops a tree covered by an ancestor in the same selection, the collapse staging already makes.

  • span=fbada6abcbb3 — fixed in 503a469

Legitimate, and precise about which half was wrong. Bytes were already safe: _count
keys a visited set on the path, so a file under the overlap could not be added twice —
and a test pinned exactly that. The REFUSALS were not deduped. With
--components memory,workspace the shared workspace/memory subtree was walked twice,
so one refused directory inside it incremented the tally twice and the stderr line said
two entries where there was one. Wrong number in the one sentence whose entire job is to
report a number.

Fixed by giving the estimate the same ancestor collapse _build_snapshot already makes
for its staged trees: a tree relative to another tree in the same selection is dropped
before the walk. That also stops the shared subtree being walked twice at all, which on
a real workspace is the larger cost.

Pinned by two tests: _estimate_selected_bytes(home, ["memory", "workspace"]) reports
exactly one refusal, and the end-to-end stderr line says skipped 1 unreadable entry.
Mutation-checked: removing the collapse reddens both.

@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 Sep 17, 2026
@iamwhatever
iamwhatever force-pushed the fix/snapshot-unreadable-entries branch from 503a469 to d78c73e Compare September 17, 2026 04:06
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Sep 17, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: the symlinked-root test builds its reparse point with conftest.make_dir_link, a junction on Windows and a symlink elsewhere, so the screen stays exercised instead of skipped.

  • span=26852c26554b — fixed in HEAD

Legitimate. test/test_snapshot_unreadable_entries.py:575 called
symlink_to(..., target_is_directory=True) and skipped on OSError, so on an unelevated
Windows runner the test announced a pass while asserting nothing — a directory symlink
needs SeCreateSymbolicLinkPrivilege there (WinError 1314). The one assertion that the
estimate does not follow a reparse-point component root was therefore unproven on the
platform whose reparse points behave least like a POSIX symlink.

Fixed with conftest.make_dir_link, which the repo already provides for exactly this: a
junction on Windows, a symlink elsewhere. Both are reparse points, and rglob, resolve
and GetFinalPathNameByHandleW traverse both identically, so is_reparse_point — the
screen under test — meets the same thing either way. No entry in
test/requires-real-symlinks.txt, because that inventory is for tests whose contract
needs a REAL symbolic link, and this one's does not.

Worth naming as a repeat: this is the second skip-guard in this PR that quietly dropped
Windows coverage, and the pattern is the same both times — a try/except around link
creation reads as defensive and is actually a hole. Grepped the file for the shape; this
was the only remaining one.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: the interim window is explicitly accepted with #11499 open; the retention guard bounds it, and the manifest record is the input the restore-side guard reads.

Correct, and the quoted sentence is from my own description. Taking the lane's second
exit — a human explicitly accepting the interim window — rather than arguing the first.

Before this PR After this PR
snapshot on a home with a refused file 🟥 no bundle at all 🟩 bundle, gap recorded
Restore of a complete bundle 🟦 unchanged 🟦 unchanged
restore --mode replace of an incomplete bundle did not exist 🟨 deletes the omitted file
--keep after an incomplete run would prune 🟩 does not prune

Three things bound the window. Today the command dies, so the operator has no bundle and
no record at all — an incomplete restore that is written down is the smaller loss.
This PR's own retention guard keeps the last complete bundle alive rather than letting an
incomplete one displace it, so a copy that restores whole survives. And the
unreadable_entry record is precisely the input the restore-side guard consumes: landing
it first is what makes #11499 a read rather than a redesign.

Not claimed: this does not make replace-mode safe on an incomplete bundle. It stays
destructive until #11499 lands, which carries the reproduction and three candidate fixes
(warn, refuse without --force, preserve the omitted paths). The residual is stated in
the PR description rather than left for a reader to infer.

@iamwhatever
iamwhatever force-pushed the fix/snapshot-unreadable-entries branch from b05d36f to 5b0274f Compare September 17, 2026 21:03
@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 readiness: checking Automated validation is still running labels Sep 17, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: pinned_fs splits every reason code once into NEVER_ARCHIVED and OMITS_WANTED_DATA; the retention guard calls omits_wanted_data(), which answers True for any code the split does not know.

  • span=ee5aa1d6ec78 — fixed in HEAD, as a restructure rather than a fifth instance

Legitimate, and this is the fifth round this span has been raised. Different line each
time, one shape every time: something is left out of the bundle without the retention guard
noticing, and --keep deletes the last complete backup. pr_findings.py names three
recurrences as the stall trigger — stop patching instances and open a restructure round —
so this round changes the mechanism instead of adding a sixth name to a list.

The mechanism was the defect. The guard enumerated a reason CODE, so it was stale the moment
the next code was added and went on answering the old way silently. too_large, vanished
and identity_changed walked past it exactly as described.

Every reason is now classified ONCE, next to where the codes are declared:

Reason Class Prunes?
symlink NEVER_ARCHIVED yes
not_regular NEVER_ARCHIVED yes
unreadable_entry OMITS_WANTED_DATA no
too_large OMITS_WANTED_DATA no
vanished OMITS_WANTED_DATA no
identity_changed OMITS_WANTED_DATA no
anything added later unknown no

omits_wanted_data() returns reason not in NEVER_ARCHIVED, so the default for an
unclassified code is incomplete. That direction is deliberate and is the part that ends the
recurrence: the two wrong answers are not symmetric — a surplus bundle costs disk, a wrong
prune costs the operator's last complete backup — so a code nobody has thought about yet is
safe before anyone thinks about it. A test asserts SKIP_REASONS covers every SKIP_*
constant in the module, so a new code cannot be added without choosing a side.

Not taken: the stated remedy of "suppress pruning whenever omissions is non-empty". It
fixes this instance and creates a worse one — symlink and not_regular are screened on
every run by design, so any data home containing a symlink would stop pruning permanently and
grow without bound. The classification gives the same protection without that cost. The
message is generalized as asked, and now names which reasons applied.

Twelve tests, and the mutation set is 22/22 caught with nothing skipped. Four are specific
to this change: reverting the guard to naming one code, flipping the unknown default to
complete, emptying NEVER_ARCHIVED, and misfiling vanished as a screen — plus dropping a
code from the split, which the completeness test alone catches.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: the interim window is explicitly accepted with #11499 open; the retention guard bounds it, and the manifest record is the input the restore-side guard reads.

Correct, and the quoted sentence is from my own description. Taking the lane's second exit —
a human explicitly accepting the interim window — rather than arguing the first.

Before this PR After this PR
snapshot on a home with a refused file 🟥 no bundle at all 🟩 bundle, gap recorded
Restore of a complete bundle 🟦 unchanged 🟦 unchanged
restore --mode replace of an incomplete bundle did not exist 🟨 deletes the omitted file
--keep after a run that omitted anything would prune 🟩 does not prune

Three things bound the window. Today the command dies, so the operator has no bundle and no
record at all — an incomplete restore that is written down is the smaller loss. The retention
guard keeps the last complete bundle alive rather than letting an incomplete one displace it,
and as of this round it does so for EVERY omission class rather than one reason code, so the
complete copy survives more cases than when this lane first raised the watch. And the
unreadable_entry record is precisely the input the restore-side guard consumes: landing it
first is what makes #11499 a read rather than a redesign.

Worth adding for the "no consumer acts on it" point: as of this round the skipped list has
two consumers on the create side — the manifest and retention — and retention now acts on the
whole vocabulary. Restore is still not one of them, which is what #11499 is for.

Not claimed: this does not make replace-mode safe on an incomplete bundle. It stays
destructive until #11499 lands, which carries the reproduction and three candidate fixes
(warn, refuse without --force, preserve the omitted paths).

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: the three sets are module-private and out of __all__; omits_wanted_data() is the one public surface, and the completeness test reads the private names directly.

  • span=a7e9250c7633 — fixed in HEAD, by subtraction

Correct count, and I take the subtraction. NEVER_ARCHIVED, OMITS_WANTED_DATA and
SKIP_REASONS had exactly one runtime consumer between them, omits_wanted_data() in the
same module, and exporting them invited the thing the predicate exists to prevent — a caller
building its own partial enumeration from the sets instead of asking the one question.

Name Before After
NEVER_ARCHIVED exported _NEVER_ARCHIVED, private
OMITS_WANTED_DATA exported _OMITS_WANTED_DATA, private
SKIP_REASONS exported removed; the test computes the union
omits_wanted_data() exported exported, the one surface

The completeness test still asserts the two private sets together cover every SKIP_*
string in the module, by introspection, so a new code cannot be added without choosing a
side — that guarantee needed the sets to exist, not to be public. cli.md now names the
predicate rather than the sets.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: the interim window is explicitly accepted with #11499 open; retention bounds it for every omission class, and the manifest record is the input the restore-side guard reads.

Same watch as the prior rounds, same answer, taking the lane's second exit. Today the command
dies and the operator has no bundle and no record; after this PR an incomplete bundle exists,
written down, and the last complete bundle is kept rather than displaced — now for every
omission class, not one code. The unreadable_entry record is exactly what the restore-side
guard in #11499 reads, so landing it first makes that a read rather than a redesign. Not
claimed: replace-mode is safe on an incomplete bundle. It is not, until #11499 lands.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: not taken in this PR; the manifest is the machine-readable signal today, and a distinct exit code is a CLI contract change that belongs in its own review.

  • span=81d876b533d0 — deferred, with a reason

Good suggestion, and correct that an unattended caller cannot read stderr. Not folded in
here because a new exit code for a SUCCESSFUL-but-incomplete snapshot changes the command's
contract: every existing cron that treats non-zero as failure would start alerting on a
bundle that was written and is restorable. That is a decision about what kirocrew snapshot
promises, not a repair to this fix, and this PR has already been asked to stay narrow. The
machine-readable signal that exists today is MANIFEST.json's skipped list, which this PR
makes complete. Filed as #11700 rather than left in a comment.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: the pinned walk hands copy_file_pinned the inode it judged; a link or non-regular inode found at that name afterwards is reported SKIP_IDENTITY_CHANGED, and _open_child_dir does the same for a directory that became a link. The screen codes are reserved for a first look.

  • span=37759b2ca7b9 — fixed in HEAD

Legitimate, and a consequence of my own split: I classified symlink and not_regular as
"never archived" without checking that every site emitting them was a FIRST look. Two were
not. copy_file_pinned reported SKIP_SYMLINK on ELOOP and SKIP_NOT_REGULAR on a
non-regular fstat even when the walk had just judged the entry regular — so a same-UID
swap between the walk's stat and the copy's open, the threat this module names in its own
docstring, landed on the "complete" side of the retention split and pruned.

Site Before After
copy_file_pinned, ELOOP on open, caller supplied an inode symlink identity_changed
copy_file_pinned, fstat inode differs from the caller's not_regular if also non-regular identity_changed (identity asked first)
_open_child_dir, source side, ELOOP/ENOTDIR after the walk's stat symlink identity_changed
Any of the above on a FIRST look (no prior stat) screen code screen code, unchanged
Hardlink alias (same inode, nlink > 1) not_regular not_regular, unchanged

The walk did not previously pass expected_src_ident at all, so the copy could not tell
the two apart. It now hands over (st_dev, st_ino) from the stat it just did, and the copy
asks identity BEFORE type — a swap to a FIFO is still a swap, and asking type first reported
it as a screen. The by-name fallback walk is unchanged: it has no descriptor and cannot
observe a swap, which is the declared weakness of that mode.

Six tests: file → link, file → other regular inode, file → FIFO (the discriminating one, which
a type-before-identity ordering fails), directory → link, a link on first look still the
screen, and the end-to-end prune held. Four mutations — each site reverted to the screen code,
plus the walk withholding the inode — all caught, none skipped. Existing coverage of the
hardlink-alias screen and the FIFO-on-first-look screen is untouched and still green.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: the interim window is explicitly accepted with #11499 open; retention bounds it for every omission class, and the manifest record is the input the restore-side guard reads.

Same watch as the prior rounds, same answer, taking the lane's second exit. Today the command
dies and the operator has no bundle and no record; after this PR an incomplete bundle exists,
written down, and the last complete bundle is kept rather than displaced — for every omission
class, including as of this round a mid-copy swap. The unreadable_entry record is exactly
what the restore-side guard in #11499 reads. Not claimed: replace-mode is safe on an
incomplete bundle. It is not, until #11499 lands.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: recorded decision — the surplus is accepted as bounded by the operator's own --keep cadence, and a cap is filed as its own change rather than folded in.

Correct that vanished is ordinary on a live data home, and correct that a scheduled snapshot
of an active home can therefore hold the prune run after run. Taking the lane's second exit
— a recorded decision — with the reasoning on the record:

The surplus is bounded by frequency, not by count: each held run adds one bundle, and the
operator chose the cadence. It is also visible — every held run prints the reason and the
count. And the failure mode of the alternative is worse: a cap that prunes "beyond keep+N"
deletes complete bundles on the strength of an incomplete one exactly when incompleteness is
persistent, which is the case the guard exists for. Which cap, and whether a persistent
vanished should be treated differently from a persistent unreadable_entry, is a policy
decision about what --keep promises. It is filed alongside the exit-code question in
#11700, which already asks how an unattended caller learns the bundle was incomplete — the
same caller is the one a cap would protect.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: SKIP_TOO_LARGE and SKIP_IDENTITY_CHANGED are in __all__ because both are reason codes a consumer of MANIFEST.json's skipped list can now receive from the retention path, and the description names them.

  • span=b32f7338c2ba — declared, kept

Fair: two names entered __all__ without a sentence in the description. They stay, and the
description now says why. SKIP_TOO_LARGE and SKIP_IDENTITY_CHANGED were already emitted by
copy_file_pinned and already landed in MANIFEST.json; what changed is that the retention
guard now acts on them, and as of this round SKIP_IDENTITY_CHANGED is the code a mid-copy
swap reports. A consumer that reads the manifest and wants to compare against the module's own
constants rather than string literals needs them exported, the same as the four that already
were. Harm-free rider, as noted; now a declared one.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: _walk catches PermissionError around os.listdir(src_fd); with skip_unreadable it reports SKIP_UNREADABLE_ENTRY for the directory and returns, otherwise it re-raises. Every other errno still propagates.

  • span=37759b2ca7b9 — fixed in HEAD, and the adjudicator's rarity record confirmed empirically

Taken as a fix rather than an override, though the FLAG rationale is correct and I checked it
before deciding. As a non-root uid on a local filesystem, no static mode produces "open ok,
listdir EACCES": 0o100 and 0o000 refuse at the open (already handled at both open sites),
0o400 opens and lists and refuses at the per-entry stat (already handled). The residual is a
grant revoked between the open and the read on a filesystem that re-validates each call.

Fixed anyway, for two reasons. The tolerance's contract is stated as a CLASS — "an entry whose
metadata or bytes this process may not read is reported as unreadable_entry" — and a
PermissionError at the listing is in that class whatever produced it; a caller reading
cli.md would expect it covered. And the cost of covering it is the same four-line shape every
other tolerated site already has, so an override would have been defending an inconsistency.

listdir(src_fd) raises skip_unreadable=True default
PermissionError recorded, subtree omitted, walk continues raises
EIO / any other OSError raises raises

Five tests. The refusal is injected at exactly that call, matched by the descriptor's inode so
only the victim directory is affected: nested directory recorded and siblings staged; the tree
root itself recorded; default still raises; EIO at the listing not absorbed; end-to-end
snapshot completes, manifest carries the record, --keep 1 holds. Four mutations — pre-fix
code, tolerating without opt-in, widening to OSError, skipping without recording — all caught,
none skipped. Stated plainly: these tests prove the handler's branches, not that any particular
filesystem produces the errno.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: SKIP_TOO_LARGE and SKIP_IDENTITY_CHANGED are removed from __all__; the module's own callers reach them unqualified and no external caller compares against either.

  • span=a0d512691987 — fixed by subtraction

Correct, and the symmetry argument I gave last round was not evidence. Grep confirms zero
consumers outside pinned_fs.py. The two lines are deleted. The four codes that were already
exported stay as they were; nothing in this PR needed to widen the public surface.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: decision recorded — SKIP_VANISHED stays on the omission side; a keep+N ceiling is tracked as its own change.

The lane's proposal — classify vanished as a race screen because a concurrently deleted file
is not recovered by keeping yesterday's bundle either — is the strongest argument yet and I
considered taking it. Not taken, for one reason: vanished is reported when the name is gone
between the listing and the stat, and the walk cannot tell "the operator deleted it" from "an
agent moved it out of the way while the backup ran". The second is the same-UID threat this
module is built around, and a bundle that lacks such a file is one the operator would want
yesterday's copy of. The asymmetry that decides every other reason applies here too: a surplus
bundle costs disk, a wrong prune costs the copy.

The surplus concern is real and bounded by cadence, not count — one bundle per held run, each
announced with its reasons. A keep+N ceiling is the right shape for it and is a --keep
contract change; #11700 carries it with the exit-code question, since both are about what an
unattended caller is promised.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: same subject as the WATCH above; the decision is recorded there and the ceiling tracked in #11700.

Same question as 178845432bd4, phrased as a suggestion. The reason vanished stays on the
omission side is given there: the walk cannot tell a concurrent delete from a same-UID move,
and the second is the threat the module names. The keep+N floor is the part worth doing and
is tracked.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: the estimate walk prunes reparse-point directories from dirnames before descent (junction fix, in HEAD); the replace-restore instance is cleared by a repository writer's override, on the adjudicator's verified rationale.

  • span=ee5aa1d6ec78 — two instances on this head: :1533 fixed, :2291 human-overridden

snapshot.py:1533, junctions — legitimate, fixed. The comment said "deeper links need no
check: os.walk does not follow them by default". True for a symlink, false for a Windows
junction: os.walk declines a directory whose is_symlink() is true, and a junction's is
not, so on Windows the estimate descended into whatever the junction named. The adjudicator's
FLAG rationale is also correct — only a size leaves the function, and the staging pass
refuses the same entry — but a walk of a tree the operator did not select is wrong whatever
it returns, and the fix is the standard os.walk prune. dirnames[:] is now filtered by
pinned_fs.is_reparse_point before descent.

Nested entry Before After
symlink directory not followed (os.walk default) not followed
Windows junction followed not followed

Two tests via make_dir_link (junction on Windows, symlink elsewhere). The outcome test
passes on POSIX with no code at all, so a second test pins the MECHANISM — that
is_reparse_point is asked about the nested link — and that one goes red on every platform
when the prune is removed. Mutation caught, 0 skipped.

snapshot.py:2291, replace-restore — override, not fix. Third round this instance has
been raised; FLAGGED each time with the same rationale, which I verified line by line in
round 11: _backup_tree_or_refuse runs in phase one before any mutation, is fatal on any
skipped entry, and a non-empty rollback dir survives with its path printed. The loss the
finding describes is either refused before it can happen or preserved in a named directory.
The restore-side read of skipped is tracked as #11499 and is a decision about what
--mode replace promises, not a repair to this fix. The GPT lane does not accept a deferral
on a data-loss finding, so a repository writer is posting the override with that rationale.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: not changed; the estimate over-counts ignored sidecars and backups, and over-counting is the conservative direction for a "may be large and slow" warning.

  • span=31b713b9db38 — accepted, not fixed

Correct that the estimate counts entries _staging_ignore later excludes — database sidecars
and backup directories — so the number can be larger than the bundle. Not fixed here: the
estimate exists for one advisory line, over-counting makes that line fire early rather than
late, and wiring the staging ignore into the size walk couples two passes that are otherwise
independent for a warning whose only cost is a sentence. If the number is ever shown
somewhere it has to be right, that is the change to make; this PR keeps the estimate's scope
to the selection and its behaviour on a refusal, which is what it was opened for.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: accepted and deferred to #11499; the restore-side read of skipped is a contract change to --mode replace, decided out of this PR.

Same watch as every prior round, same answer, and now a recorded human decision on the GPT
lane's version of it. What bounds the window has not changed: today the command dies and there
is no bundle; after this PR the incomplete bundle is written down, the last complete one is kept
for every omission class, and replace's phase-one backup refuses or preserves before any
mutation. The unreadable_entry record is the input #11499 reads. Not claimed: replace-mode
is safe on an incomplete bundle without #11499.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: the ~10-line restore guard is not folded in; it is one of #11499's three candidates and choosing it here would pre-empt that decision.

  • span=fd70bd80ab79 — not folded in, with a reason

The suggestion is fair and the size estimate is right. Not taken because "warn / require
confirmation" is one of three candidate shapes #11499 already lists (warn, refuse without
--force, preserve the omitted paths), and they differ in what --mode replace promises an
unattended caller. Landing one of them as an interim in a PR about snapshot creation decides
that question by default. This PR has been asked twice to stay narrow; the record and the
retention guard land here, the restore-side behaviour is decided in #11499.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

/ai-review override gpt 2c0a3ce: Replace restore's phase-one rollback (_backup_tree_or_refuse) is fatal on any skipped entry and runs before all mutation, so an omitted-but-live file is either preserved in the retained rollback directory or the replace refuses outright; the loss is prevented or recoverable rather than silent, and the proposed pre-mutation guard is redundant with it.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@iamwhatever marked the gpt AI finding as false positive, not applicable, or explicitly accepted for 2c0a3cedc537886163b039d6f31734e6e00d088a.

Replace restore's phase-one rollback (_backup_tree_or_refuse) is fatal on any skipped entry and runs before all mutation, so an omitted-but-live file is either preserved in the retained rollback directory or the replace refuses outright; the loss is prevented or recoverable rather than silent, and the proposed pre-mutation guard is redundant with it.

This decision applies only to this commit. A new push requires a new judgment.

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.

2 participants