Repository navigation
refactor(crew-log): rename the append-only ledger to crew log (phase 1) - #11549
Conversation
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Retired [DESIGN-REVIEWED] 0882725 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS The PEP-562 lazy Not justified as shipped
What this change shipsInventory (8 items) — 7 justifiedIntent: rename the pre-release append-only per-unit ledger to "crew log" so it stops colliding with the work ledger and the repo's other ledgers — a FIX of a naming defect, agreed with a maintainer.
[FIRST-PRINCIPLES-REVIEWED] 0882725 |
Opus 4.8 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
Security Scope Review -- 🟡 CONCERNSWhich legitimate operations does Verdict basis: the reviewer's own judgement; no confirmed regression. Security scope review -- adjudicated candidates
No candidate flipped from allowed to refused. Scope-Verdict: CONCERNS TIGHTENING: The file-tool path fence ( ADJUDICATED: 15 candidates, 0 confirmed newly-refused PLATFORM COVERAGE: posix (9 rows) and windows (6 rows); no UNADJUDICATED: Two guards in this tightening never reach the shell-command classifier, so no verdict exists for them and this review does not claim one:
[SCOPE-REVIEWED] 0882725 |
b8a9553 to
8404a83
Compare
4aff8fb to
4aa561e
Compare
|
Three red shards on
Both fail the same four tests, which are the ones #11563 tracks: Windows shard 7 reports
Eleven failures, in seven files this PR's diff does not touch at all: macOS shard 3 also carries two more of the same non-UTF8-path kind I am not claiming these are main-owned, because I have not proved it: they are macOS-only and I cannot The No new head is being pushed for any of this: the four review lanes (GPT 5.6, Opus 4.8, Design, First |
|
Correcting my comment above, and adding the fourth red.
That pair is NOT macOS-only, so my "cannot reproduce on Linux" above was wrong for it. Its appearance
So it is main-owned, and I have recorded it on #11563 with the reproduction. Candidate cause there is The rest of my earlier comment stands. The non-UTF8-path failures and the six Current tally of red shards on
Still no new head: GPT 5.6, Opus 4.8, Design Review and First Principles are all green on |
The append-only per-unit log mechanism is named crew log. Every other thing
in the repo called a ledger keeps its name, including the work ledger, the
session_ledger_read/record tools, ledger-sweep, and the app ledgers.
The package src/kiro_crew/ledger/ becomes src/kiro_crew/crew_log/, and
session_ledger_emit.py moves in as crew_log/emit.py. Moving the emitter into
the package would make importing it execute the package __init__ and pull in
store, schema and lease, so __init__ re-exports lazily (PEP 562) and the
flag-off boot path still imports no storage.
On disk the leaf is <data home>/crew-log/{crews,sessions}/<unit>/log.jsonl.
The security/paths.py fence leaf moves in the same commit as the store leaf,
because that fence is what keeps agent file tools out of the store. The env
flag is KIROCREW_CREW_LOG. No shim, no dual-read, no migration: the flag is
default-off and no user data exists on disk.
The reference pages, the two module specs and the renamed test files follow
the same name. rfc-append-only-ledger.md keeps its file name and title for
external links and gains one paragraph recording the name.
A stray-file test regained its teeth: it wrote ledger.backup.jsonl, which no
longer shares the segment prefix, so segment_paths never saw it and the
assertion held vacuously. It now writes log.backup.jsonl.
The test-writer fixes from #11445 land on files this rename moved, and its
new helper import names the pre-rename module, so the retention test reads
it from crew_log_type_helpers instead.
4aa561e to
0882725
Compare
|
Every assertion is a worker-count number the host is expected to yield: Not this PR's, on three independent grounds. The file has zero lines in this diff, it contains no It is macOS-specific, and the mocking is what makes that interesting: the tests monkeypatch One thing this run does settle: #11566 and #11491 worked. The non-UTF-8-path group and No new head for any of this. GPT 5.6, Opus 4.8, Design Review and First Principles are all green on |
The crew log is fenced from the agent so a session cannot alter its own audit trail. That stays. What it also did was make the log unverifiable by anyone but the operator with a shell, because reading was fenced along with writing. This adds a standalone, assignable, read-only MCP server of three tools over the gateway's own routes: list the session logs, page one, read a fold. No write tool exists and the set is ratcheted so none can be added. Authorization lives in the endpoints: the caller's own unit needs a strict session identity, and any wider read needs the owner at a dashboard tab. Refs #11549
Phase 1 (#11549) renamed the package, the paths and the user-facing text. The identifiers stayed, so the code still said ledger for a mechanism the docs and the disk now call the crew log -- while three other live mechanisms are also called a ledger. Renames, behaviour unchanged: LedgerError -> CrewLogError, class Ledger -> CrewLog, ledger_root/ledger_dir/ledger_path -> crew_log_*, and the caller-side helpers and locals that name this store. The work ledger, the accounting ledgers and every frozen wire value keep their names.
The crew log is fenced from the agent so a session cannot alter its own audit trail. That stays. What it also did was make the log unverifiable by anyone but the operator with a shell, because reading was fenced along with writing. This adds a standalone, assignable, read-only MCP server of three tools over the gateway's own routes: list the session logs, page one, read a fold. No write tool exists and the set is ratcheted so none can be added. Authorization lives in the endpoints: the caller's own unit needs a strict session identity, and any wider read needs the owner at a dashboard tab. Refs #11549
The crew log is fenced from the agent so a session cannot alter its own audit trail. That stays. What it also did was make the log unverifiable by anyone but the operator with a shell, because reading was fenced along with writing. This adds a standalone, assignable, read-only MCP server of three tools over the gateway's own routes: list the session logs, page one, read a fold. No write tool exists and the set is ratcheted so none can be added. Authorization lives in the endpoints: the caller's own unit needs a strict session identity, and any wider read needs the owner at a dashboard tab. Refs #11549
The crew log is fenced from the agent so a session cannot alter its own audit trail. That stays. What it also did was make the log unverifiable by anyone but the operator with a shell, because reading was fenced along with writing. This adds a standalone, assignable, read-only MCP server of three tools over the gateway's own routes: list the session logs, page one, read a fold. No write tool exists and the set is ratcheted so none can be added. Authorization lives in the endpoints: the caller's own unit needs a strict session identity, and any wider read needs the owner at a dashboard tab. Refs #11549
The crew log is fenced from the agent so a session cannot alter its own audit trail. That stays. What it also did was make the log unverifiable by anyone but the operator with a shell, because reading was fenced along with writing. This adds a standalone, assignable, read-only MCP server of three tools over the gateway's own routes: list the session logs, page one, read a fold. No write tool exists and the set is ratcheted so none can be added. Authorization lives in the endpoints: the caller's own unit needs a strict session identity, and any wider read needs the owner at a dashboard tab. Refs #11549
…#11907) Phase 1 (#11549) renamed the package, the paths and the user-facing text. The identifiers stayed, so the code still said ledger for a mechanism the docs and the disk now call the crew log -- while three other live mechanisms are also called a ledger. Renames, behaviour unchanged: LedgerError -> CrewLogError, class Ledger -> CrewLog, ledger_root/ledger_dir/ledger_path -> crew_log_*, and the caller-side helpers and locals that name this store. The work ledger, the accounting ledgers and every frozen wire value keep their names.
The crew log is fenced from the agent so a session cannot alter its own audit trail. That stays. What it also did was make the log unverifiable by anyone but the operator with a shell, because reading was fenced along with writing. This adds a standalone, assignable, read-only MCP server of three tools over the gateway's own routes: list the session logs, page one, read a fold. No write tool exists and the set is ratcheted so none can be added. Authorization lives in the endpoints: the caller's own unit needs a strict session identity, and any wider read needs the owner at a dashboard tab. Refs #11549
…log (#11909) The crew log is fenced from the agent so a session cannot alter its own audit trail. That stays. What it also did was make the log unverifiable by anyone but the operator with a shell, because reading was fenced along with writing. This adds a standalone, assignable, read-only MCP server of three tools over the gateway's own routes: list the session logs, page one, read a fold. No write tool exists and the set is ratcheted so none can be added. Authorization lives in the endpoints: the caller's own unit needs a strict session identity, and any wider read needs the owner at a dashboard tab. Refs #11549
…tdev#11549) The append-only per-unit log mechanism is named crew log. Every other thing in the repo called a ledger keeps its name, including the work ledger, the session_ledger_read/record tools, ledger-sweep, and the app ledgers. The package src/kiro_crew/ledger/ becomes src/kiro_crew/crew_log/, and session_ledger_emit.py moves in as crew_log/emit.py. Moving the emitter into the package would make importing it execute the package __init__ and pull in store, schema and lease, so __init__ re-exports lazily (PEP 562) and the flag-off boot path still imports no storage. On disk the leaf is <data home>/crew-log/{crews,sessions}/<unit>/log.jsonl. The security/paths.py fence leaf moves in the same commit as the store leaf, because that fence is what keeps agent file tools out of the store. The env flag is KIROCREW_CREW_LOG. No shim, no dual-read, no migration: the flag is default-off and no user data exists on disk. The reference pages, the two module specs and the renamed test files follow the same name. rfc-append-only-ledger.md keeps its file name and title for external links and gains one paragraph recording the name. A stray-file test regained its teeth: it wrote ledger.backup.jsonl, which no longer shares the segment prefix, so segment_paths never saw it and the assertion held vacuously. It now writes log.backup.jsonl. The test-writer fixes from kirodotdev#11445 land on files this rename moved, and its new helper import names the pre-rename module, so the retention test reads it from crew_log_type_helpers instead.
…kirodotdev#11907) Phase 1 (kirodotdev#11549) renamed the package, the paths and the user-facing text. The identifiers stayed, so the code still said ledger for a mechanism the docs and the disk now call the crew log -- while three other live mechanisms are also called a ledger. Renames, behaviour unchanged: LedgerError -> CrewLogError, class Ledger -> CrewLog, ledger_root/ledger_dir/ledger_path -> crew_log_*, and the caller-side helpers and locals that name this store. The work ledger, the accounting ledgers and every frozen wire value keep their names.
…log (kirodotdev#11909) The crew log is fenced from the agent so a session cannot alter its own audit trail. That stays. What it also did was make the log unverifiable by anyone but the operator with a shell, because reading was fenced along with writing. This adds a standalone, assignable, read-only MCP server of three tools over the gateway's own routes: list the session logs, page one, read a fold. No write tool exists and the set is ratcheted so none can be added. Authorization lives in the endpoints: the caller's own unit needs a strict session identity, and any wider read needs the owner at a dashboard tab. Refs kirodotdev#11549
Problem / Motivation
The append-only per-unit log added by RFC #10090 was called "the ledger", and so is a great deal
else in this repo: the conductor work ledger and its
session_ledger_read/session_ledger_recordtools, the
ledger-sweepcommand, the ops-mission-control, auto-improvement and issue-radarledgers, and
dependency_ledger.py. One word covered two unrelated mechanisms with different keys,different lifetimes and opposite retention rules.
Reading
session_ledger.pynext toledger/store.pygave no clue which was which, and a specsentence saying "the ledger" could not be resolved without checking the imports.
Why it matters
The cost lands on whoever reads this next. Grepping
ledgerreturns both mechanisms and leaves youto sort them by hand, and a reviewer cannot tell whether "the ledger is the authority a conductor
reads" is about the work ledger -- which is exactly the sentence a conductor acts on.
The two also invite real mistakes. The work ledger is keyed by SLOT KEY, which is recycled; this one
is keyed by the ACP session id, which is not. Their deletion rules are deliberately opposite: the
permanent-delete funnel removes this log and PRESERVES the work ledger. Naming them the same thing
makes that distinction something you have to remember rather than something you can read.
This is also the cheapest possible moment. The format is pre-release,
KIROCREW_CREW_LOGisdefault-off, and no user data exists on disk, so no shim, dual-read or migration is needed. After
the first release none of that is true.
What changed
The mechanism is named crew log, agreed with Joe Guo. Everything else called a ledger keeps its
name, and the old work ledger is untouched.
src/kiro_crew/ledger/->src/kiro_crew/crew_log/, andsession_ledger_emit.py->crew_log/emit.py.crew_log/__init__.pyre-exports its public names LAZILY (PEP 562). This is required by the moverather than a separate improvement: with the emitter inside the package, importing it would execute
the package
__init__and pull instore,schemaandlease, breaking the invariant that aflag-off launch imports no storage -- an invariant this suite asserts.
<data home>/crew-log/{crews,sessions}/<unit>/log.jsonl. Thesecurity/paths.pyfenceleaf moves in the SAME commit as the store leaf, because that fence is what keeps the agent's own
file tools out of the store; splitting them would publish an unfenced store.
ledgersleaf STAYS in both fence sets (security/paths.py::_CREW_SECRET_LEAVESand
sandbox.py::_CREW_HIDDEN_LEAVES). This rename ships no migration, so a machine that ranthe old build with the flag on still has entries under
<data home>/ledgers, and dropping theleaf would un-fence them from the agent's file tools and from a sandboxed
open()on upgrade.It is deliberately NOT added to
_CREW_PRECREATE_HIDDEN_DIR_LEAVES: that set exists for a rootthe store creates LAZILY, and nothing creates this one any more, so there is no writer to race
and precreating it would only re-materialise the retired name on every machine.
KIROCREW_CREW_LOG.ledger-core.md->crew-log-core.md,session-ledger-emitter.md->crew-log-emitter.md,docs/reference/ledger/->docs/reference/crew-log/.rfc-append-only-ledger.mdkeeps its file name and title, because external links point at them,and gains one paragraph recording the name.
test_ledger_*->test_crew_log_*, with every dotted monkeypatch path moved.Unchanged on purpose: the header
typevocabulary, every entry type name, all error codes includingno_ledger,LedgerError,SCHEMA_VERSION, the JSON field names, and the.lease/.lockfilenames.
One behaviour was repaired rather than renamed.
test_a_neighbour_file_sharing_the_prefix_is_ignored_not_refusedwrote a stray file namedledger.backup.jsonl, but the segment prefix is nowlog., so the file no longer shared the prefixthe test is named for:
segment_pathsnever saw it and the assertion held vacuously. It now writeslog.backup.jsonl.Phase 2, to follow
Deliberately NOT in this PR, because three PRs are in flight over the same files
(#11185, #11310, and a projection change adding
projection.pyto the package):Ledger->CrewLog,LedgerError->CrewLogError,ledger_dir/ledger_root->crew_log_dir/crew_log_root.ledger_diralone has 63 callsites, which is why it is separated from the structural move.
session_ledger_resolve.pyand
projection.py.The error-code VALUE
no_ledgerstays frozen even when its class is renamed, and the work ledgeris never renamed -- not in this PR and not in Phase 2.
Tests
flake8,black --checkandisort --check-onlyclean on every changed Python file;scripts/check_black_formatting.py,scripts/docs_lint.pyandscripts/docs-lint.shpass;mypy --follow-imports=silentclean overcrew_logplus the touched src files.pytest -n 2over every renamed test file plustest_acp_client.py,test_session_control.py,test_steer_requeue.py,test_remove_slot_for_history_key.pyandtest_sandbox_absent_ceiling_seal.py: green, with no excluded failures.The repaired test was mutation-checked in both directions. With
_segment_first_seqmutated toaccept a non-digit middle, the OLD filename still PASSED while the new one FAILED -- which is the
evidence that the fix restores the claim rather than just renaming a string. 1 killed / 1 total.
45 tests in the retention and types files failed earlier from #11193 and #11317 merging without ever
running CI together; #11445 fixed them and this branch is rebased onto it. Absorbing it needed one
adaptation worth knowing: #11445 adds
from ledger_type_helpers import minimal_data, and this branchrenamed that helper, so the import named a module that no longer exists. The rebase itself was
conflict-free and every hunk landed, so nothing flagged it -- the module simply failed at collection.
The import now reads
crew_log_type_helpers.Pattern harvest
A rename that changes a filename constant can hollow out a test without failing it.
ledger.backup.jsonlstopped matching thelog.*.jsonlglob, so the assertion passed for the wrongreason: green, and testing nothing. A renamed test deserves the same question as a new one -- mutate
the code it guards and check it still goes red.
When a rename absorbs an in-flight change to the files it moved, a clean rebase proves less than it
appears to. Git paired the renames and every hunk arrived, yet the change was still broken, because
what it imported named the pre-rename module. A conflict check cannot see that and neither can
reading the diff; only running the tests catches it.
Substituting a phrase that carries its own article (
"session ledger" -> "the session's log")produces
a the session's logwherever a determiner already stood. Prefer an article-freereplacement, then grep the result for doubled articles and doubled nouns before pushing.