Skip to content

Repair flows run/resume lifecycle and supersede PRs #9 and #11 - #12

Merged
khaliqgant merged 17 commits into
mainfrom
flow/drive-de5f378-08280313
Aug 28, 2026
Merged

Repair flows run/resume lifecycle and supersede PRs #9 and #11#12
khaliqgant merged 17 commits into
mainfrom
flow/drive-de5f378-08280313

Conversation

@khaliqgant

Copy link
Copy Markdown
Member

WP-12

Supersedes #9 and #11. This branch contains both histories and repairs every finding from PR #9's failed review swarm.

Ten-finding triage

  • F1 fixed: typed needs_human snapshots return exit 3 with a human-recovery diagnostic. A live daemon/worker regression reaches the real kernel state by disconnecting a dispatched manual-recovery agent.
  • F2 fixed: RunSnapshot.steps carries typed RFC step types, stable snake_case states, and a running lease deadline; Rust Debug text is no longer a wire format.
  • F3 fixed: snapshot step types replace the sequence-1 run.spawned read; readRunSpec is deleted.
  • F4 fixed: a typed hello refusal is protocol_error, not daemon_unreachable.
  • F5 fixed: worker waits print what they are waiting for, accept cancellation, and stop at the heartbeat-renewed lease deadline.
  • F6 fixed: LADDER names hello-deterministic, hello-llm, and hello-agent; CLI-specific induced faults apply only to agentic rungs.
  • F7 fixed: run.resume asks the rebuildable run registry instead of inferring runs/<id>.sqlite3.
  • F8 fixed: npm test builds once before Vitest workers start; bin.test.ts no longer races the live suite by rebuilding in beforeAll.
  • H1 fixed: the gate-1 scoreboard now cites only this tick's measured 74 kernel / 150 SDK totals, including 7/7 built-binary and 7/7 live-kernel cases.
  • H2 fixed: ops/NEXT.md is the WP-12 assessment; neither superseded assessment lands.

Evidence

  • Kernel: 74 passed, 0 failed; clippy with -D warnings passed; rustfmt output empty.
  • SDK: 150 passed across 9 files, including all 7 live-kernel tests.
  • Clean-artifact SDK acceptance: dist and node_modules moved aside recoverably, then npm ci && npm test passed all 150 and rebuilt executable dist/cli.js.
  • F1/F2/F4/F5/F7/F8 have captured red mutations, matching restoration hashes, and restored green runs in ops/DRIVE-LOG.md.
  • Adversarial transcript: ops/reviews/20260828-0349-wp12-adversarial.md ends REVIEW_PASSED and names reviewed SHA 53cc5075d5a5eaade404607622d4fc256e54ccc2.
  • workflows/review-swarm.yaml adds transcript persistence only; lens prompts, verdict grep, and aggregate pass/fail logic are unchanged.

Merging is intentionally not part of WP-12 completion. Keep this PR open until the live RUN-CONTRACT §3 merge bar is satisfied.

khaliqgant and others added 16 commits August 28, 2026 02:26
The tick's own product was the WP-11 assessment and its adversarial
gate, not the repair; the repair ran on PR #9's branch and its evidence
stays there. Verify re-executed on this head (72 kernel / 131 SDK, all
nine test-result lines unfiltered) proves this head clean and nothing
about PR #9's 73/147 claim.

Recorded against this tick: the review landed 15 minutes after the
implementation it was meant to steer. Recorded against PR #9: its
transcript names c83a367, not head 3616c0a; the branch is one commit
behind main; and the live suite has not run on a merge candidate.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…o flow/drive-de5f378-08280313

# Conflicts:
#	ops/NEXT.md
…o flow/drive-de5f378-08280313

# Conflicts:
#	ops/DRIVE-LOG.md
#	ops/NEXT.md
@coderabbitai

coderabbitai Bot commented Aug 28, 2026

Copy link
Copy Markdown

Review Change Stack

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: b8fa98da-72c2-4f2a-97c1-c3bc46d57f31

📥 Commits

Reviewing files that changed from the base of the PR and between de5f378 and f552cce.

📒 Files selected for processing (30)
  • docs/SURFACE.md
  • kernel/relayflowd-core/tests/spec_parity.rs
  • kernel/relayflowd/src/engine.rs
  • kernel/relayflowd/src/engine/model.rs
  • kernel/relayflowd/src/lib.rs
  • kernel/relayflowd/src/server.rs
  • kernel/relayflowd/src/server/tests.rs
  • ops/DRIVE-LOG.md
  • ops/NEXT.md
  • ops/SCOREBOARD.md
  • ops/reviews/20260828-0244-pr9-adversarial.md
  • ops/reviews/20260828-0258-review.md
  • ops/reviews/20260828-0349-wp12-adversarial.md
  • sdk/package.json
  • sdk/src/cli.ts
  • sdk/src/cli/check.ts
  • sdk/src/cli/run.ts
  • sdk/src/failure-kinds.ts
  • sdk/src/journal-client.ts
  • sdk/src/protocol.ts
  • sdk/tests/bin.test.ts
  • sdk/tests/cli.test.ts
  • sdk/tests/journal-client-loopback.ts
  • sdk/tests/journal-client.test.ts
  • sdk/tests/live-kernel.test.ts
  • sdk/tests/spec-parity.test.ts
  • testdata/hello-deterministic.flow.yaml
  • testdata/hello-deterministic.spec.canonical.json
  • testdata/hello-deterministic.spec.sha256
  • workflows/review-swarm.yaml

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.


📝 Walkthrough

Walkthrough

The change adds Gate 1 check, run, and resume CLI flows, structured step snapshots, lease-aware worker handling, registry-backed resume validation, deterministic parity fixtures, live integration tests, and operational review evidence.

Changes

Gate 1 CLI and lifecycle

Layer / File(s) Summary
CLI contracts and preflight
docs/SURFACE.md, sdk/src/cli.ts, sdk/src/cli/check.ts, sdk/src/failure-kinds.ts, sdk/package.json, sdk/tests/cli.test.ts, sdk/tests/bin.test.ts
The CLI supports asynchronous check, run, and resume commands with typed exit codes, JSON output, data-directory handling, configuration validation, executable probing, and structured diagnostics.
Typed snapshots and journal protocol
kernel/relayflowd/src/engine/*, kernel/relayflowd/src/lib.rs, sdk/src/protocol.ts, sdk/src/journal-client.ts, sdk/tests/journal-client*.ts
Run snapshots now expose structured step types, normalized states, and lease deadlines. Lifecycle requests can bypass bounded request timeouts. Protocol failures use JournalProtocolError.
Run and resume orchestration
sdk/src/cli/run.ts, sdk/tests/cli.test.ts, sdk/tests/live-kernel.test.ts
Run execution classifies success, failure, parked, unavailable, and protocol outcomes. Parked worker steps support polling, lease expiry, cancellation, recovery, and progress reporting.
Registry-backed resume validation
kernel/relayflowd/src/server.rs, kernel/relayflowd/src/server/tests.rs
run.resume checks the journal registry before resumption and returns run_not_found for orphan database files.
Parity fixtures and review evidence
testdata/*hello-deterministic*, kernel/relayflowd-core/tests/spec_parity.rs, sdk/tests/spec-parity.test.ts, ops/*, workflows/review-swarm.yaml
The deterministic fixture receives canonical JSON and SHA-256 parity checks. Operational records and review transcripts document verification results and persistence before aggregation.

Estimated code review effort: 5 (Critical) | ~90 minutes

Merge Risk: ⚪ Minimal · up to f552c

The PR repairs run and resume lifecycle behavior and documents the updated contracts; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant flowsCLI
  participant relayflowd
  participant RunRegistry
  participant Worker
  User->>flowsCLI: run or resume flow
  flowsCLI->>relayflowd: submit lifecycle request
  relayflowd->>RunRegistry: create or locate run
  RunRegistry-->>relayflowd: return run state
  relayflowd-->>flowsCLI: return snapshot or completion
  flowsCLI->>Worker: poll active worker step
  Worker-->>flowsCLI: report completion or lease state
  flowsCLI-->>User: emit report and exit code
Loading

Poem

A rabbit checks the flow at dawn
Then starts a run and hops along
Leases tick softly, workers wake
Resumes find the paths they take
Typed states guide each careful leap
While journals guard the trail we keep

Warning

Some tools did not complete. Review the errors below.

🔧 Clippy (1.97.1)

Clippy execution failed


Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/settings/billing.

Comment @coderabbitai help to get the list of available commands.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5ebdf71b07

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +170 to +173
if registry
.lookup(&params.run_id)
.map_err(|error| internal_error(error.into()))?
.is_none()

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Preserve resume when the rebuildable registry is absent

When relayflowd.sqlite3 is lost or rebuilt while a valid per-run journal remains, this check returns run_not_found before Engine::resume_filtered can execute its existing “repair missing run registry entry” path. That makes an authoritative journal impossible to resume solely because its documented non-authoritative index is missing; validate the run journal and rebuild the registry row instead of treating an absent index entry as proof that the run does not exist.

AGENTS.md reference: AGENTS.md:L3-L5

Useful? React with 👍 / 👎.

Comment on lines +127 to +128
if ! git diff --cached --quiet -- ops/reviews/; then
git commit -m "ops(review): persist PR #${PR} swarm transcripts" -- ops/reviews/

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Commit transcripts only from a review branch

When review-pr runs in the documented primary checkout, the fetch step only downloads the target PR's metadata and diff; it never checks out that PR's branch. This unconditional git commit therefore commits to whatever branch launched the workflow, which is normally main, bypassing the required branch/PR/human-merge path. Create or require a dedicated review branch/worktree before committing.

AGENTS.md reference: AGENTS.md:L27-L30

Useful? React with 👍 / 👎.

Comment on lines +118 to 120
- name: persist-transcripts
type: deterministic
dependsOn: [lens-maintainability, lens-history, lens-structure]

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Move the gate change out of the work it judges

This commit adds behavior to review-swarm.yaml while that same review gate is part of the evidence used to certify this work, so the change edits its own judge. Persistence-only intent does not remove the gate-integrity problem; land this workflow modification through an independently authored and reviewed change instead.

AGENTS.md reference: AGENTS.md:L29-L30

Useful? React with 👍 / 👎.

@khaliqgant

Copy link
Copy Markdown
Member Author

BLOCKED — two blocking findings at this head (ops/reviews/20260828-0512-review.md, whose reviewer re-ran the gates itself with literal output rather than trusting the tick's numbers):

  • B1flows run abandons a live run and blames a worker that is attached. Same family as the F1 this PR set out to fix: a healthy state reported as a failure, on the command a user types.
  • B2 — this head makes a crashed run permanently unresumable — an F7 regression. The fix for one finding broke resumability, which is the kernel's central promise.

B2 is the priority. A crashed run that can never resume is worse than the reporting defect this PR was opened to repair.

Supersedes #9 and #11 (both closed). Next tick takes B1/B2.

@khaliqgant
khaliqgant merged commit e48631d into main Aug 28, 2026
2 checks passed
khaliqgant pushed a commit that referenced this pull request Aug 28, 2026
… ground truth

Run 54ebd998 failed at assess-1 after three retries. The Lead had done the
right thing all three times: it hit a genuine contradiction, wrote a precise
ops/NEEDS_HUMAN.md, and ended with BLOCKED_NEEDS_HUMAN exactly as its task
instructed. But the gate is output_contains: ASSESS_DONE, so the designed
escape hatch was unreachable and correct behavior scored as a crash. Same
class as the review gate that once scored an honest rejection as a crash.

Fixed by separating the report from the verdict, the way review/verdict
already are: assess ALWAYS ends ASSESS_DONE, and a new deterministic
assess-gate step reads ops/NEEDS_HUMAN.md and parks with a typed exit 75.

ops/STATE.md is new: a cloud sandbox has no .git and no gh, so an assessor
there cannot reconstruct state from history. It now reads gate and open-PR
truth from the repo instead, plus the known sandbox faults that are not
reasons to block. It must be kept current — a stale STATE.md misleads a
reader that cannot check it.

ops/NEXT.md described WP-12 (repair PR #9) long after PR #12 merged. That
stale package is what the assessor tripped over. Replaced, with the answer to
its question: gate 1 closed, gate 6 next.

Third independent sighting of the exec-bit fault, this one from inside the
sandbox: the Lead reported ops/cargo.sh as Permission denied.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
khaliqgant pushed a commit that referenced this pull request Aug 28, 2026
…exactly as warned

Run da6d7aa0's Lead escalated correctly and the assess-gate parked it:
ops/TARGET.md said PR #14 was already on main, ops/STATE.md said gate 2 was
'RED, not started' with merged PRs ending at #12, and the code TARGET.md
described was sitting in the working tree. The Lead refused to guess which
source was lying and asked.

It was right, and the fault is mine. STATE.md carries this warning in its own
text — 'a stale STATE.md is worse than none: it does not merely fail to help,
it actively misleads an assessor that cannot check it' — and I then merged #13
and #14 without updating it. An assessor in a sandbox has no git history; this
file IS its history.

Gate 2 is now AMBER with what landed and what is still missing named
explicitly, so the next assessment can pick up rather than re-litigate.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This was referenced Aug 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant