Skip to content

fix(dashboard): answer a spawn stopped before its claim as stopped, not spawned - #24763

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/spawn-stopped-before-start-15821
Oct 27, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/spawn-stopped-before-start-15821

Conversation

@CrysisDeu

@CrysisDeu CrysisDeu commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A run that was stopped before it started is never reported as started.

SubagentManager.spawn / spawn_async can accept a row and then have its claim refused, because the run was stopped while it waited (CLAIM_REFUSED). The manager then returns a terminal placeholder: queued=True, done=True, user_stopped=True, with an empty error. Every surface that starts a run tests only for done with an error, so that placeholder fell through to its success answer.

Why it matters

The caller is told a run started, under an id that never produces a card or a completion event. A person, spawn_run, a channel user or an app waits on, or retries, something that already ended.

Not a goal

  • Changing how the manager or the task store decides a claim is refused, or the placeholder itself.
  • Changing the answer for any other start outcome (rejection, capacity, deferral, a run stopped after it started).
  • The successor bookkeeping in SubagentManager._settle_continuation (see Sibling sweep).

Intended? / Repro

Intended? No. Nothing in the spec says a refused claim should read as started. docs/system-specs/modules/subagent.md (the CLAIM_REFUSED bullet) says spawn "returns a queued+done+user_stopped info without registering and the drain takes the next row", so nothing will run. The "Typed rejections" section of the same file gives every other non-start a typed code. No test pins a started answer for this placeholder.

Repro (code read on current main):

  • src/kiro_crew/subagent_manager/admission/gate.py:1408-1423: if not proceed: returns SubagentInfo(..., queued=True, done=True, user_stopped=True) with no error.
  • src/kiro_crew/subagent_manager/admission/taskq_bridge_accept.py:343: _replace(point.queued, done=True, user_stopped=True), the same shape.
  • dashboard/messaging_api/spawn.py api_spawn: if info.done and info.error: is false for that info, so the route answers {"id": ..., "status": "spawned"}.
  • dashboard/messaging_api/spawn.py api_spawn_continue: the same check, then status: "spawned".
  • dashboard/messaging_api/run_control.py _retry_failed_run: the same check, then settle_retry(old, info.id) and status: "spawned". That also records the dead id as the failed run's successor, so a second retry is refused retry_superseded.
  • messaging/commands.py spawn_task_reply (the channel spawn command): the same check, then a "Spawned" reply.
  • apps/spawn_sdk.py build_spawn_impl: tests only error, then returns the dead id to the app.

Input: any of those starts while the manager returns the placeholder. Seen: a started answer (HTTP 200 spawned, a "Spawned" reply, or an id) for a run that never starts.

What changed (motivation → approach → change)

Symptom: a stopped-before-start row is reported as started. Cause: each surface checks only for done with an error. Change: one test for the record, read by every surface that starts a run.

  • subagent_wait_reasons.py (the leaf module the channel command layer already reads): stopped_before_start(info). It is True only when queued, done and user_stopped are all True and error is empty. queued is part of it: a registered run stopped during its start's last await is done and user_stopped but not queued, and it ran, so it keeps its id.
  • dashboard/messaging_api/spawn.py: STOPPED_BEFORE_START_CODE = "stopped_before_start" and _stopped_before_start(info, *, counted=False), a 409 with that code when the test holds.
    • api_spawn calls it with counted=True after the typed-rejection branch, because spawn() already counted the submission (the same reason the 400 and 429 answers carry it), so spawn_run does not reconcile it as lost.
    • api_spawn_continue calls it after its typed-failure branch.
  • dashboard/messaging_api/run_control.py _retry_failed_run calls it before settle_retry(old, info.id). The claim stays pending and the route's existing finally releases it (settle_retry(old, None)), so the failed run stays retryable.
  • messaging/commands.py spawn_task_reply: replies "Subagent <id> was stopped before it started; nothing ran." instead of announcing a start.
  • apps/spawn_sdk.py build_spawn_impl: raises SpawnError (not a host decline) instead of returning the id.
  • dashboard/handlers/messaging.py: binds the new names on the facade the composed owners run on.
  • docs/system-specs/modules/subagent.md: a "Stopped before it started" paragraph under Typed rejections.

Backwards compatibility

Compatible: only the refused-claim placeholder, which was reported as a started run that never existed, now gets a not-started answer. Every other answer is unchanged. spawn_run already treats an error body as a refusal and reads counted to skip the lost-submission reconcile; an app already handles SpawnError from spawn.run.

Removes nothing: no key, field, route or function is removed; the change only gives a no-run answer its own typed answer.

Tests

  • test/test_handlers_messaging_coverage.py:
    • TestApiSpawn::test_a_row_stopped_before_its_claim_is_not_answered_spawned: 409, code == "stopped_before_start", counted is True, no status.
    • TestApiSpawn::test_a_run_stopped_after_it_started_keeps_its_spawned_answer: done + user_stopped without queued still answers 200 with its id.
    • TestApiSpawnContinue::test_a_continuation_stopped_before_its_claim_is_not_answered_spawned: 409 with the code.
    • TestApiSpawnRetry::test_a_retry_stopped_before_its_claim_releases_the_claim: 409 with the code, and the claim is released (settle_retry(old, None) only), not settled with the dead id.
  • test/test_messaging_commands.py::...::test_a_spawn_stopped_before_it_started_is_not_announced: the exact not-started reply.
  • test/test_app_spawn_capability.py::TestSpawnSDK::test_a_spawn_stopped_before_it_started_raises: SpawnError, declined is False.

On main the four stopped-before-start tests get a started answer (200 spawned, the "Spawned" reply, or the id).

Proof: not provable -- other: this host runs no local tests; CI runs the new tests

Manual verification

N/A: unit coverage is enough. The change is one pure check on the record the manager returns, read at five start sites.

Static gates run locally on the changed files: black, isort, flake8, scripts/check_file_line_cap.py, scripts/docs_lint.py, and the error-code ratchet scan (no new opaque_body or missing_code). mypy and the test suite run in CI.

Related Issues

Fixes #15821

Sibling sweep

Swept: git grep -nE ".done and [a-z_]+.error" -- src/ ; git grep -nE "spawn_async|.spawn(" -- src/kiro_crew/messaging src/kiro_crew/apps
Sibling: src/kiro_crew/dashboard/messaging_api/spawn.py -- changed here (api_spawn and api_spawn_continue)
Sibling: src/kiro_crew/dashboard/messaging_api/run_control.py -- changed here (_retry_failed_run)
Sibling: src/kiro_crew/messaging/commands.py -- changed here (spawn_task_reply)
Sibling: src/kiro_crew/apps/spawn_sdk.py -- changed here (build_spawn_impl)
Sibling: src/kiro_crew/subagent_parts/continuation_surface.py:156 -- not affected -- it records which start took the conversation, not an answer to a caller

Pattern harvest

Rule candidate: review-prompt
Pattern: a start site that tests only done and error reads a terminal no-error placeholder as success.

Checklist

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

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@CrysisDeu
CrysisDeu requested review from a team and KiroCrewCaptain as code owners October 27, 2026 06:20
@CrysisDeu
CrysisDeu requested a review from iamwhatever October 27, 2026 06:20
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 27, 2026
@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of b240dcf86de573beb46f9f9786f58c410c20bfbf — 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 does not.

First-Principles-Verdict: PASS

The fix is at mechanism level and has a linked issue. Nothing in the inventory lacks a named harm. The root cause sits upstream in the placeholder itself, which the Goal deliberately leaves untouched.

Notes

  • Item 1 — symptom-level: the placeholder is built in two places with no error/code: subagent_manager/admission/gate.py:1408 and taskq_bridge_accept.py:343. Because of that, 4 sites testing \.done and [a-z_]*\.error (grepped) plus 2 more sites now each need a second test. The PR opts out of this explicitly: "Not a goal: … the placeholder itself". Subtraction: give those 2 placeholder sites a typed error/code, then delete _stopped_before_start and the 5 per-surface branches.
  • Item 7 — deferred sibling: subagent_parts/continuation_surface.py:156 still records the dead id as _continued_as. It is the same root cause, and the PR defers it under "Not a goal".

What this change ships

Inventory (7 items) — 5 justified

Intent: callers are never told that a run stopped before it started was started. FIX.

  1. POST /api/spawn answers 409 stopped_before_start (with counted) instead of spawned — symptom-level
  2. POST /api/spawn/{id}/continue answers 409 instead of spawned — justified
  3. A retry that was stopped before it started answers 409 and frees its claim, so the run can still be retried — justified
  4. The channel spawn command replies "stopped before it started" instead of "Spawned" — justified
  5. The app spawn SDK raises SpawnError instead of returning a dead id — justified
  6. New public error code stopped_before_start and the helper stopped_before_start() — justified
  7. Continuation successor bookkeeping is left as it is — symptom-level, deferred sibling

[FIRST-PRINCIPLES-REVIEWED] b240dcf

Description read

[DESCRIPTION-READ] 66b321b255645a36aade877f599407eea8bab4967f822f60d3ad60488342522a

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

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

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] b240dcf

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable b240dcf86de573beb46f9f9786f58c410c20bfbf false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of b240dcf86de573beb46f9f9786f58c410c20bfbf — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: one record predicate, read by all five start sites, matching how the existing typed rejections answer.

Notes

  • counted: true on the 409 matches the 400 and 429 answers: gate.py counts the submission before the if not proceed: branch. So spawn_run's wave reconcile treats this member the same way it treats any other refused member.

[DESIGN-REVIEWED] b240dcf

Description read

[DESCRIPTION-READ] 507dd0b5f194a9358614a53ccc5b4b143537ba20aedbf561a3cb6969cca03135

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

@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] b240dcf

False positive or not applicable? A repository writer can comment:
/ai-review override gpt b240dcf86de573beb46f9f9786f58c410c20bfbf false-positive: <reason, 20 to 500 characters>

@CrysisDeu
CrysisDeu force-pushed the fix/spawn-stopped-before-start-15821 branch from 1938f99 to 23eb632 Compare October 27, 2026 07:18
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 27, 2026
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

Replies to the non-blocking notes on 23eb6325a:

  • First Principles, pump.py duplicate: I'm leaving _after_dispatch_impl alone in this PR. Its check does not test error, and stopped_before_start requires an empty error. Swapping one for the other would change which drained records the pump treats as "take the next row". That's a behavior change inside the pump, which is out of scope for a route-answer fix.
  • Design, a future sixth start site: the new spec paragraph ("Stopped before it started", subagent.md under Typed rejections) already names subagent_wait_reasons.stopped_before_start as the one test, and says every surface that starts a run reads it.

The red backend shard 2 (Linux and Windows) comes from test_crew_log_fullscan_guard.py::test_a_warm_session_read_that_earns_a_savepoint_reads_only_the_gap going XPASS(strict) after the recent crew-log merges on main. This PR doesn't touch that code; #24774 drops that xfail.

@CrysisDeu
CrysisDeu force-pushed the fix/spawn-stopped-before-start-15821 branch from 23eb632 to b240dcf Compare October 27, 2026 13:23
@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 Oct 27, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) October 27, 2026 16:09

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Tier 1 auto-approve: fix (10 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: answers a spawn stopped before its claim with a coded 409 or a SpawnError instead of 'spawned', on every surface that starts a run; with tests. Spec files changed as a ride-along (a minority of the diff on both file count and changed lines), not reviewed as a design decision: docs/system-specs/modules/subagent.md.

@KiroCrewCaptain
KiroCrewCaptain merged commit 0a864a5 into main Oct 27, 2026
108 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/spawn-stopped-before-start-15821 branch October 27, 2026 16:12
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 27, 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.

fix(dashboard): a spawn whose claim is refused is answered as spawned

2 participants