Skip to content

fix(crew-log): declare the subagent and background types the emitter already writes - #12550

Merged
iamwhatever merged 1 commit into
mainfrom
fix/declare-subagent-entry-types
Sep 21, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/declare-subagent-entry-types

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

A session that dispatches a sub-agent gets a work record it can never read again.

The session ledger is a fold of the session's crew log. One subagent/spawned
entry stops that fold, and because a crew log is append-only the entry never goes
away. So every later read answers with the empty record: the goal, phase, next
step and event tail the session wrote before it dispatched a child are gone for
the rest of that session's life, while the log itself sits intact on disk. One
background model call the gateway makes on the session's behalf does the same
thing.

The reader says so out loud, then the ledger swallows it:

CrewLogError: entry <N> has type 'subagent/spawned', which this reader does not
know and which is not marked ignorable; reconstruction stops here
ledger: folding this slot's crew logs failed

Why it matters

The session ledger exists so a long-running session can recover what it was doing
after context compaction. Dispatching a sub-agent is ordinary work for exactly
those sessions, so the record breaks in the case it was built for.

Nothing tells the caller. read_state is best-effort by contract and answers the
empty record, so a refused fold and a slot that genuinely recorded nothing look
identical from the outside.

What changed (motivation, approach, change)

Symptom one sub-agent dispatch makes a slot's session ledger unreadable forever
Root cause the emitter writes six entry types the registry never declared
Change declare them, and pin the set equality in both directions

A reader that folds state hands known=KNOWN_TYPES to iter_from, which refuses
an entry it does not know unless the writer marked it skippable. KNOWN_TYPES is
the declared vocabulary, and the emitter and the store append six types
entry_types.py never declared. They break in two different ways.

Five are written without the skippable mark: subagent/spawned,
subagent/steered, subagent/completed, subagent/failed and
background/completed. One such entry ends every later fold of that log,
permanently.

The sixth, plan/updated, is written skippable, and that is not safe either. It
is skipped, a skip is a discontinuity in the sequence the fold receives, and the
class fold reads a gap as damage, after which recorded_class refuses on it.
Declaring it removes the skip, so there is no gap and no damage. Its write stays
ignorable=True exactly as it is: the declaration is reader-side only, and the
spec's own ignorable flag is documentation, since the store reads the flag on
each entry rather than on the type.

So all six are declared, with the field specs their call sites actually produce.
docs/reference/crew-log/session-types.md has documented every one of them as
live since its writer landed, with the same fields; only the registry was out of
sync, so this brings it back in line rather than inventing a shape.
background/completed's tokens members are optional, unlike turn/completed's
required four, because its writer drops every zero dimension and requiring them
would refuse a call billed on one. subagent/failed has a second writer, the
crash-repair closer, which knows only the child's id and that nothing will report
for it, so every field of that type except agent_id stays optional. Declaring a
type turns validation on for it, and a refused write is dropped rather than
raised, so a spec narrower than its writer would lose entries silently.

The alternative was to mark the five non-ignorable writes skippable instead. It
was rejected twice over. The timeline projection reads subagent/spawned,
subagent/completed and subagent/failed, so skipping them trades a broken fold
for missing timeline rows. And skippable is not a fix in the first place, as
plan/updated shows: it is already skippable and still damages the class record.

The old guard could not catch any of this. It walks the declared set and reports
which members have a writer, so a type that is written and never declared is
invisible to it by construction. Its hand-written companion list went further and
asserted these six stay undeclared. Both are corrected, the declared-type count
moves 23 to 29 with the roles it names, and a new test measures the set equality
from the writers' side.

Backwards compatibility

Compatible: declaring a type is reader-side, so nothing that writes today changes
and no stored log is rewritten. A log already holding one of these entries folds
on its next attempt, so broken slots recover with no migration. The field specs
were read off the existing call sites and every optional field stays optional, and
a test drives the real emitters and asserts dropped_writes() == 0, so no write
that lands today starts being refused.

Tests

  • test_the_declared_vocabulary_is_exactly_what_the_writers_append parses the
    emitter's and the store's syntax trees for every type they append, keyed on the
    append primitive rather than on any type-shaped literal, and asserts the
    appended set and the declared set are equal in both directions. Appended and
    undeclared is what breaks readers; declared and never appended states a shape no
    site produces. It carries three controls: both sides non-empty, four
    hand-verified types that must come back on both sides, and the skippable flag
    read in both of its values. Mutation-verified in each direction: removing a
    declaration fails naming ['subagent/steered'], then ['background/completed'],
    and adding a declaration with no writer fails naming ['remote/lost']. The set
    really is derived from the writers rather than from a list kept by hand.
  • test_the_sampled_types_are_the_ignorable_ones pins the skippable marker to the
    two types that sample a stream, which is what keeps a future "just mark it
    ignorable" from passing the ratchet above.
  • test_a_subagent_entry_does_not_stop_the_fold drives the real session ledger
    read past a subagent/spawned entry end to end, ordered so the child entry
    follows the ledger entry and the fold has to walk past it. Mutation-verified: it
    fails on the goal assertion, and the refusal it reproduces is the same message
    the field reports.
  • The existing real-turn emitter test now also drives all six emitters, including
    every shape plan/updated produces (with and without a total, and clipped at
    the item bound), and asserts both that each type was appended and that
    dropped_writes() is still zero.
  • Canonical payloads for the six new types join the existing parametrized set,
    which validates each example, reduces it to its required fields, drops each
    required field, rejects an undeclared key and rejects a wrong JSON type per
    field.

Manual verification

N/A: unit coverage is sufficient. The defect is a refusal inside the fold, and the
regression test drives the real read_state path the field symptom comes from.

Related Issues

Fixes #12535

Pattern harvest

Rule candidate: review-prompt
Pattern: a registry guard that iterates the declared set can only ever report a
subset of it, so it cannot detect a written-but-undeclared member. A set equality
between a writer-derived set and a registry has to iterate the writer side, and it
has to assert both directions, since each direction fails in a different way.

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

@chenmingwei23
chenmingwei23 requested review from a team and dwu96 September 21, 2026 15:11
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Intent: Make a session's crew log foldable again after it dispatches a sub-agent or the gateway makes a background model call for it, by declaring the five entry types the emitter already writes non-ignorable, and pin the writer-to-registry direction so the next wired emitter cannot silently reintroduce the same fold-killer.

Not a goal: changing any writer, marking existing writes ignorable, adding new entry types, touching the crew-log reader or the fold implementation, or declaring plan/updated (it is written ignorable and its own gap is a different class).

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

github-actions Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] e6fe6d7

@github-actions

github-actions Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of e6fe6d7beff04b0fe970dcc16a4c7119933acfb0 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] e6fe6d7

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

@github-actions

github-actions Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of e6fe6d7beff04b0fe970dcc16a4c7119933acfb0 — 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

The AST ratchet only sees literal type names — its own docstring says a computed type name escapes both directions; verify no writer does that today.

What this change ships

Inventory (8 items) — 8 justified

Intent: FIX — a session that dispatched a sub-agent gets its recoverable work record back (issue #12535); writers verified present on base at emit.py:4250–4407 and store.py:2880, untouched by this diff, and KNOWN_TYPES = frozenset(SESSION_ENTRY_TYPES) (projection.py:141) makes the declaration the cause-level fix.

  1. A slot's ledger folds again past a dispatched child — justified
  2. Child steer, completion and failure entries no longer stop any fold — justified
  3. Background-call cost entries no longer stop any fold — justified
  4. A plan update no longer damages the session's class record; its write stays skippable — justified
  5. These six writes are now shape-validated on append, the registry's standing posture for every declared type — justified
  6. The old pin "these six stay undeclared / emitters not wired on this base" is reversed — justified
  7. New test derives the declared vocabulary from the writers' syntax trees, equality asserted both directions — justified
  8. The generated type-reference dump gains six sections; its ignorable-marker count is now derived — justified

The reversed pin (item 6) carries the evidence the contract demands: its comment claimed the "emitters are not wired on this base," yet all six writers exist in emit.py/store.py on base and this diff never touches them — the pin's stated reason was false, and the description says so. Sibling count: the crew kind has no writers at all (test line 638), so zero drift siblings remain. Not product shape: no default moves, and docs/reference/crew-log/session-types.md already pinned all six as live with these shapes.

[FIRST-PRINCIPLES-REVIEWED] e6fe6d7

@github-actions

github-actions Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] e6fe6d7

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

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

@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 21, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/declare-subagent-entry-types branch from 19f9351 to 473a461 Compare September 21, 2026 16:07
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Sep 21, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in src/kiro_crew/crew_log/entry_types.py, src/kiro_crew/crew_log/emit.py and test/test_crew_log_types.py.

New head 473a4616d06d3d7d76f6958da3f47b4caf192fcc, base 53fcaf6f212d6296f0e8cf884222587850b245d1.

This rebase was curative rather than routine. #12479 landed object/observed, which adds a member to both sides of this PR's set equality, a new declaration in the registry and a new writer in the emitter, and it edits the same count assertion this PR moves. Three conflicts in test/test_crew_log_types.py, all resolved as the union of both changes rather than by keeping either side:

  • the declared count moves 23 to 29 (main's 23 plus this PR's six), and the comment naming what moved travels with it;
  • the closed-enum set keeps both ("object/observed", "producer") and ("plan/updated", "state");
  • the sentence listing which vocabularies a producing site clamps names both.

entry_types.py auto-merged. Verified after the rebase: 29 declarations present with all seven type names (object/observed plus this PR's six), and the bidirectional ratchet still reports the declared and written sets equal, which is the property the sibling's arrival could have broken in either direction.

Re-run on the rebased tree, named files with -n0: 304 passed in test_crew_log_types.py and test_session_ledger_projection.py; 171 passed across the four other files that read the declared registry, including test_crew_log_object_observed.py, which arrived with #12479 and is newly relevant to this diff. check_black_formatting.py, flake8, isort, check_comment_history.py and ratchet_scope.py each exit 0 on the final clean tree.

Sequencing note for the two remaining siblings that also carry this count assertion (#12314, #12303): whichever lands after this one will hit the same one-line conflict on assert len(SESSION_ENTRY_TYPES) == 29, resolved the same way, taking the union and moving the count.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 21, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/declare-subagent-entry-types branch from 473a461 to 9a1d976 Compare September 21, 2026 16:20
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Rebased again: main moved in src/kiro_crew/context.py, src/kiro_crew/vector_memory.py and test/test_default_context_admission.py (#12497, #12400).

New head 9a1d97691f2ca786cdde72ed1a0bd49681b877ef, base 57aee4bd7d.

No conflict, and the diff is byte-identical to the previous head: the same three files, 546 insertions and 18 deletions. Unlike the #12479 rebase above, this drift touches neither the crew-log package, nor session_ledger.py, nor either of the test files in this diff, so it moves no side of the set equality. It is picked up only because the green on the previous head was not measured against these commits.

Re-run on this base, named files with -n0: 304 passed in test_crew_log_types.py and test_session_ledger_projection.py, and 84 passed in test_default_context_admission.py, the overlapping file. check_comment_history.py and ratchet_scope.py each exit 0 against the new base.

@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 Sep 21, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/declare-subagent-entry-types branch from 9a1d976 to 1430897 Compare September 21, 2026 16:43
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Sep 21, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Rebased onto current main and corrected a stale claim this PR had introduced into its own diff.

New head 14308970dec4d7f3b0bb175bf0de8dca7b9d17c8. No conflict this time: none of the commits since the last head touches src/kiro_crew/crew_log/, src/kiro_crew/session_ledger.py, or either test file in this diff.

The correction. The module docstring of entry_types.py still read that plan/updated "is written but deliberately undeclared". That was true of an earlier revision of this branch and false of the one it shipped in, since this change declares it. A file that declares a type while its own docstring says the type is deliberately undeclared is worse than one that is simply out of date: the next reader has to work out which half to trust. The sentence is struck rather than annotated, and replaced with the actual rule, that an ignorable write is not exempt because an undeclared ignorable entry is skipped, a skip is a sequence gap, and the class fold reads a gap as damage. Verified by asserting the old wording is absent rather than that the new wording is present, then swept both remaining phrasings across all three touched files.

Post-rebase mutation verification. The derived-set ratchet was previously mutation-verified before the rebase only, which says nothing about whether it still bites after a merge moved the registry. Re-verified on this tree: retargeting the background/completed declaration to a vocabulary member with no writer makes test_the_declared_vocabulary_is_exactly_what_the_writers_append fail at test/test_crew_log_types.py:439 with

AssertionError: the writers append these types and the registry does not declare
them, so a log holding one cannot be folded, or has a damaged class record:
['background/completed']

Reverted, and the file re-verified: 29 declarations, background/completed present, no probe text left behind, and the suite back to the same 304 passing it showed before the mutation.

Deletion accounting for the registry, since a rebase is the step that can silently revert someone else's lines: the diff against the new base is 238 insertions and 3 deletions in entry_types.py, and all three deleted lines are the superseded docstring sentence above. Nothing of main's is removed. test_session_ledger_projection.py deletes nothing at all.

Re-run on this base, named files with -n0: 304 passed. check_black_formatting.py, flake8, check_comment_history.py and ratchet_scope.py each exit 0 on a clean tree.

@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 21, 2026
@github-actions github-actions Bot added the readiness: passed Eligible automated validation passed for the current revision label Sep 21, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/declare-subagent-entry-types branch from 1430897 to bae04d9 Compare September 21, 2026 17:53
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Sep 21, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in conftest.py (#12425), plus seven other commits whose overlap with this PR is import-graph only.

New head bae04d991d8758b353124183b790b1d9f8e36178, base e4b00db9. No conflict, and the diff is byte-identical to the previous head: the same three files, 238/3, 264/15 and 46/0.

conftest.py is why this one was taken rather than deferred. The other seven commits touch nothing this diff reads, but a root conftest change can affect any test, and the previous head's CI round was testing a merge ref built from a base that predates it. A green measured there would not have been a green against the conftest this PR will actually merge into. That round was 40 of 43 jobs in with zero failures, and discarding it was the deliberate cost.

Verified against the new conftest, named files with -n0: 304 passed. check_black_formatting.py, flake8, check_comment_history.py and ratchet_scope.py each exit 0 on a clean tree.

Nothing in these eight commits touches src/kiro_crew/crew_log/, src/kiro_crew/session_ledger.py, or either test file here, so no side of this PR's set equality moved and the declared count stays 29.

@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 21, 2026
A reader that folds state passes known=KNOWN_TYPES to iter_from, which refuses an
entry whose type it does not know and which is not marked ignorable. The emitter
writes subagent/spawned, subagent/steered, subagent/completed, subagent/failed
and background/completed non-ignorable, and entry_types.py declared none of them.
So any session that dispatched a child, or that the gateway made one background
model call for, held a crew log that could never be folded again:
session_ledger.read_state caught the refusal and answered with the empty record
for the rest of that session's life.

plan/updated is the sixth. Its write stays ignorable=True and is left alone, so
it was never part of the refusal above -- but an undeclared ignorable type is
SKIPPED by a folding reader, and a skip leaves a gap in the seqs the class fold
receives, which marks that history damaged and makes the reader refuse on it.
Declaring it removes the skip, so there is no gap and no damage. Declaring it
also lets the new pin be a set equality rather than a one-way containment: a
declared type with no writer is now as loud as a written type with no
declaration.

The six types are declared with the field specs their emit call sites actually
produce, cross-checked against docs/reference/crew-log/session-types.md, which has
documented all six as live since their writers landed. Only the registry was out
of sync. background/completed's tokens members are optional, unlike
turn/completed's, because its writer drops every zero dimension. subagent/failed
has a second writer, the crash-repair closer in store._closer_entries, which
supplies only agent_id and outcome, so every other field of that type stays
optional. plan/updated's item state is the one closed enum added here: the writer
computes it as done-or-open from a single boolean, so no caller can produce a
third value.

Declaring rather than flipping the writes to ignorable: the timeline projection
consumes subagent/spawned, subagent/completed and subagent/failed, so skipping
them would trade a broken fold for missing timeline rows.

Three pins. A derived-set test parses BOTH writers' syntax trees -- the emitter
and the crash-repair closer -- for every type they append, and asserts that set
equals the declared set, so a new wired emitter and an orphaned declaration each
fail loudly and name the offending type. The old test could not catch the first
direction because it walked the declared set and so could never see a type
missing from it, and its hand-written companion list went further and asserted
these types stay undeclared. A regression test drives the real session_ledger
fold past a subagent/spawned entry end to end. The real-turn emitter test now
exercises all six types and asserts dropped_writes() == 0, which is what proves
the new declarations do not narrow what production already writes -- declaring a
type turns validation on for it, and a too-narrow spec drops writes silently
rather than raising. The declared-type count moves 22 -> 28 with the roles it
names, and the markdown dump's ignorable-marker count is now derived from the
registry instead of hardcoded.

No migration: declaring a type is reader-side, so an already-broken log recovers
on its next fold attempt.
@chenmingwei23
chenmingwei23 force-pushed the fix/declare-subagent-entry-types branch from bae04d9 to e6fe6d7 Compare September 21, 2026 18:24
@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ⚠️ review incomplete

GPT 5.6 did not produce a complete verdict for e6fe6d7beff04b0fe970dcc16a4c7119933acfb0; inspect the workflow logs and re-run it.

This comment is updated in place on each push.

See the GPT 5.6 Review job logs; this commit has no completed GPT verdict.

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

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Rebased to clear an inherited red: main moved in src/kiro_crew/docs/apps.md (#12580).

New head e6fe6d7beff04b0fe970dcc16a4c7119933acfb0. No conflict, and the diff is byte-identical to the previous head: the same three files, 238/3, 264/15 and 46/0.

The red was not this PR's. Three lanes failed on the previous head: Backend Tests (3.12, 8), Backend Tests (Windows) (8) and Coverage Gate. One test was responsible, test/test_apps_doc_catalogue.py::test_the_agents_bullet_names_every_app_and_its_count, asserting that the Agents bullet in src/kiro_crew/docs/apps.md states an agent count matching each app's app.json roster. It read Auto-Improvement as two where the roster says four. Coverage Gate is downstream of the two shards, so it is one defect, not three.

That test touches nothing in this diff, which is the crew-log type registry and two crew-log test files. Attribution measured rather than assumed:

After the rebase the fix is an ancestor, and the previously failing test passes here on its own: test_the_agents_bullet_names_every_app_and_its_count 1 passed. Nothing in this diff was changed to achieve that, and no foreign fix was folded in.

Also re-run on this base, named files with -n0: 304 passed in test_crew_log_types.py and test_session_ledger_projection.py. check_black_formatting.py, flake8, check_comment_history.py and ratchet_scope.py each exit 0 on a clean tree.

Note for the two remaining siblings that carry this count assertion (#12314, #12303): the declared count is still 29 here, and no commit in this window touched src/kiro_crew/crew_log/, src/kiro_crew/session_ledger.py or either test file, so no side of the set equality moved.

@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ⚠️ review incomplete

GPT 5.6 did not produce a complete verdict for e6fe6d7beff04b0fe970dcc16a4c7119933acfb0; inspect the workflow logs and re-run it.

This comment is updated in place on each push.

See the GPT 5.6 Review job logs; this commit has no completed GPT verdict.

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

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

The seven failures on head e6fe6d7beff04b0fe970dcc16a4c7119933acfb0 are one cause, and it is not in this diff.

At 18:25:43 UTC the Resolve desktop matrix job failed inside dorny/paths-filter with:

##[error]API rate limit exceeded for installation.

Everything else in that batch is the same exhaustion seen from a different angle. Each review lane failed at its shared Resolve human override preflight, whose own message says it could not read this PR's comments after three attempts and is failing closed rather than re-gating a verdict a human may have cleared. Publish readiness signal and PR Readiness are downstream of those. So it is one GitHub App installation quota exhaustion, not seven findings, and no lane reached the point of judging the code.

The workflow's own remedy is to re-run the job, and that works: UX Review passed on its second attempt with no change to the tree. Design Review, First Principles Review, GPT 5.6 Review and Opus 4.8 Review are on their third attempt now, having each drawn the same failure on the second.

Build still needs a re-run for the same reason. I am deliberately holding it until the four review lanes conclude, because an installation limit is shared repo-wide and a re-run fired now would compete for the quota those lanes are currently spending.

Nothing was pushed for this and the tree is untouched. The diff at this head remains the same three files, 238/3, 264/15 and 46/0, with 304 passing locally under -n0 and the repo's formatting, comment-history and ratchet-scope gates each exiting 0.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 21, 2026

@buluoray buluoray 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.

Verified at head e6fe6d7b. Approving. This one is worth more than its three-file diff suggests, and the PR description undersells it.

I checked the producer side rather than the enum, and the gap was real in one direction only. Six types are appended by live writers in crew_log/emit.py and were not declared: plan/updated, subagent/spawned, subagent/steered, subagent/completed, subagent/failed, background/completed -- each with a production call site (chat_runner.py:13230, admission/gate.py:1286, continuation.py:71, terminal.py:87 and :89, llm_helpers.py:1616). Nothing is declared-but-unproduced, and the PR's own test asserts that emptiness in both directions.

What made this severe rather than cosmetic is what an undeclared type does, and I confirmed it in source. Through a folding reader, store.py:2194 raises CODE_UNKNOWN_ENTRY_TYPE for an undeclared non-ignorable type and reconstruction stops there. session_ledger.py:685 folds with known=projection.KNOWN_TYPES, and :791 catches that and logs ledger: folding this slot's crew logs failed. So any session that spawned a subagent or made a background LLM call had an unreadable ledger fold, permanently, with the log itself intact -- and the only symptom was a warning. record() raises, because it folds to compute its return. The ignorable one, plan/updated, is skipped instead, which leaves a seq discontinuity that sets damaged=True on the class fold -- so a session whose agent touched its task list had a damaged class record.

That is the ledger whose whole purpose is to survive compaction, silently empty for exactly the sessions that delegate. Worth stating plainly in the PR body.

The behaviour change is contained: the ledger and class folds do not newly branch on the six types, they only stop refusing them. The one real consequence is correctly guarded -- declaring a type turns validation on for it, and a validation refusal is a dropped write rather than a raise, so test_every_entry_a_real_turn_produces_validates drives the real emitters and asserts dropped_writes() == 0, proving the specs are not narrower than production. The timeline projection already listed three of the subagent types and only now becomes reachable.

The test suite is not membership-only, which was my main worry with a "declare the types" PR. Undeclaring subagent/spawned reddens the vocabulary test at test_crew_log_types.py:439 and test_session_ledger_projection.py:500, where the second is behavioural: it writes a real subagent/spawned entry after a ledger entry and asserts read_state(SLOT)["goal"] reconstructs correctly with no fold-failure warning. That is the consumer doing the right thing, not a name sitting in a list. 304 passed at head.

GPT's state here needed care: three comments exist for this SHA, two "review incomplete" (18:26, 18:35) and one real "no blocking findings" at 18:40:46, which is the latest and therefore authoritative. Opus completed clean at 18:42. Worth noting for anyone reading the thread that the incomplete pair is superseded rather than outstanding.

@iamwhatever
iamwhatever enabled auto-merge (squash) September 21, 2026 21:31
@iamwhatever
iamwhatever merged commit 078d5e7 into main Sep 21, 2026
139 of 152 checks passed
@iamwhatever
iamwhatever deleted the fix/declare-subagent-entry-types branch September 21, 2026 21:31
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 21, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…kirodotdev#12550)

A reader that folds state passes known=KNOWN_TYPES to iter_from, which refuses an
entry whose type it does not know and which is not marked ignorable. The emitter
writes subagent/spawned, subagent/steered, subagent/completed, subagent/failed
and background/completed non-ignorable, and entry_types.py declared none of them.
So any session that dispatched a child, or that the gateway made one background
model call for, held a crew log that could never be folded again:
session_ledger.read_state caught the refusal and answered with the empty record
for the rest of that session's life.

plan/updated is the sixth. Its write stays ignorable=True and is left alone, so
it was never part of the refusal above -- but an undeclared ignorable type is
SKIPPED by a folding reader, and a skip leaves a gap in the seqs the class fold
receives, which marks that history damaged and makes the reader refuse on it.
Declaring it removes the skip, so there is no gap and no damage. Declaring it
also lets the new pin be a set equality rather than a one-way containment: a
declared type with no writer is now as loud as a written type with no
declaration.

The six types are declared with the field specs their emit call sites actually
produce, cross-checked against docs/reference/crew-log/session-types.md, which has
documented all six as live since their writers landed. Only the registry was out
of sync. background/completed's tokens members are optional, unlike
turn/completed's, because its writer drops every zero dimension. subagent/failed
has a second writer, the crash-repair closer in store._closer_entries, which
supplies only agent_id and outcome, so every other field of that type stays
optional. plan/updated's item state is the one closed enum added here: the writer
computes it as done-or-open from a single boolean, so no caller can produce a
third value.

Declaring rather than flipping the writes to ignorable: the timeline projection
consumes subagent/spawned, subagent/completed and subagent/failed, so skipping
them would trade a broken fold for missing timeline rows.

Three pins. A derived-set test parses BOTH writers' syntax trees -- the emitter
and the crash-repair closer -- for every type they append, and asserts that set
equals the declared set, so a new wired emitter and an orphaned declaration each
fail loudly and name the offending type. The old test could not catch the first
direction because it walked the declared set and so could never see a type
missing from it, and its hand-written companion list went further and asserted
these types stay undeclared. A regression test drives the real session_ledger
fold past a subagent/spawned entry end to end. The real-turn emitter test now
exercises all six types and asserts dropped_writes() == 0, which is what proves
the new declarations do not narrow what production already writes -- declaring a
type turns validation on for it, and a too-narrow spec drops writes silently
rather than raising. The declared-type count moves 22 -> 28 with the roles it
names, and the markdown dump's ignorable-marker count is now derived from the
registry instead of hardcoded.

No migration: declaring a type is reader-side, so an already-broken log recovers
on its next fold attempt.
wknight1 pushed a commit to wknight1/KiroCrew that referenced this pull request Oct 5, 2026
…kirodotdev#12550)

A reader that folds state passes known=KNOWN_TYPES to iter_from, which refuses an
entry whose type it does not know and which is not marked ignorable. The emitter
writes subagent/spawned, subagent/steered, subagent/completed, subagent/failed
and background/completed non-ignorable, and entry_types.py declared none of them.
So any session that dispatched a child, or that the gateway made one background
model call for, held a crew log that could never be folded again:
session_ledger.read_state caught the refusal and answered with the empty record
for the rest of that session's life.

plan/updated is the sixth. Its write stays ignorable=True and is left alone, so
it was never part of the refusal above -- but an undeclared ignorable type is
SKIPPED by a folding reader, and a skip leaves a gap in the seqs the class fold
receives, which marks that history damaged and makes the reader refuse on it.
Declaring it removes the skip, so there is no gap and no damage. Declaring it
also lets the new pin be a set equality rather than a one-way containment: a
declared type with no writer is now as loud as a written type with no
declaration.

The six types are declared with the field specs their emit call sites actually
produce, cross-checked against docs/reference/crew-log/session-types.md, which has
documented all six as live since their writers landed. Only the registry was out
of sync. background/completed's tokens members are optional, unlike
turn/completed's, because its writer drops every zero dimension. subagent/failed
has a second writer, the crash-repair closer in store._closer_entries, which
supplies only agent_id and outcome, so every other field of that type stays
optional. plan/updated's item state is the one closed enum added here: the writer
computes it as done-or-open from a single boolean, so no caller can produce a
third value.

Declaring rather than flipping the writes to ignorable: the timeline projection
consumes subagent/spawned, subagent/completed and subagent/failed, so skipping
them would trade a broken fold for missing timeline rows.

Three pins. A derived-set test parses BOTH writers' syntax trees -- the emitter
and the crash-repair closer -- for every type they append, and asserts that set
equals the declared set, so a new wired emitter and an orphaned declaration each
fail loudly and name the offending type. The old test could not catch the first
direction because it walked the declared set and so could never see a type
missing from it, and its hand-written companion list went further and asserted
these types stay undeclared. A regression test drives the real session_ledger
fold past a subagent/spawned entry end to end. The real-turn emitter test now
exercises all six types and asserts dropped_writes() == 0, which is what proves
the new declarations do not narrow what production already writes -- declaring a
type turns validation on for it, and a too-narrow spec drops writes silently
rather than raising. The declared-type count moves 22 -> 28 with the roles it
names, and the markdown dump's ignorable-marker count is now derived from the
registry instead of hardcoded.

No migration: declaring a type is reader-side, so an already-broken log recovers
on its next fold attempt.
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.

crew log: five entry types the emitter writes are undeclared, so one sub-agent dispatch makes a session ledger unfoldable forever

3 participants