Skip to content

fix(cli): print signing key repair steps when restart fails - #19829

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
Pearcekieser:fix/signing-key-refusal-launcher-hint
Oct 29, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
Pearcekieser:fix/signing-key-refusal-launcher-hint

Conversation

@Pearcekieser

@Pearcekieser Pearcekieser commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: When kirocrew restart fails because the gateway refused to boot on a truncated token_signing.key, the terminal that ran the restart shows the repair steps.

Since #14457 the gateway refuses to start when token_signing.key is a regular file under 32 bytes, and prints the manual repair steps from token_secret.signing_key_remedy to its stderr. Under kirocrew restart nobody is reading that stderr. A detached gateway writes it to gateway.log, and a service gateway writes it to the journal. The restart prints "Replacement gateway (pid N) died immediately" or "the gateway was NOT restarted" with a pointer to kirocrew logs -f or journalctl, and the person has to open the log to learn that the fix is four steps on one file. #14457 promised a follow-up for the refused state; a dashboard banner cannot work because a refused gateway serves no dashboard, so this puts the steps in the launcher output instead.

Why it matters

A truncated key blocks every boot until someone removes it by hand. The restart command is where the operator is looking at that moment, and it already knows the boot failed.

Not a goal

  • The desktop app. Its start-failure dialog already shows the last 60 lines of gateway.log, which carry the gateway's own CRITICAL line with the same steps.
  • Repairing the key from the CLI. The steps stay manual for the reasons in signing_key_remedy's docstring.
  • Any change to when the gateway refuses.

What changed (motivation → approach → change)

The restart already detects both failure shapes, so the hint hangs off those two branches rather than parsing logs. cli_server_restart._signing_key_refusal_lines() takes the same read-only lstat look kirocrew doctor and the boot preflight take, through signing_key_health with the same two bits: confined from sandbox.agent_confinement_evidence, and require_denied_open when the only signal is a Seatbelt verdict Kiro Crew did not create. A sandbox mask over a healthy key never reads as short, and a readable truncated key under a foreign Seatbelt still does. On "short", and only when token_secret.open_is_denied says this process can open the file, it returns the signing_key_remedy steps with restart_command_hint(), and on any other state or any exception it returns nothing. The open check is the guard kirocrew doctor already applies: a short key that refuses the open may be the mode-0 sandbox mask over a healthy key, and the steps delete the file. _restart prints those lines after the "died immediately" message only when the #20055 gateway.log relay printed nothing, because the relayed lines already carry the gateway's own refusal and the same steps, and it appends them to a service report that has a RESTART_NOT_UP failure. A RESTART_REFUSED restart never ran the gateway, so it gets no steps and no probe.

Backwards compatibility

Additive: two failure messages gain lines only when the key is short. Exit codes and audit records are unchanged.

Tests

  • test_replacement_that_dies_on_a_truncated_key_prints_the_repair_steps and test_unit_not_up_on_a_truncated_key_prints_the_repair_steps fail on origin/main and pass here.
  • test_replacement_that_dies_on_a_healthy_key_prints_no_repair_steps covers ok, absent, masked, other and unstatable.
  • test_a_short_key_this_process_cannot_open_gets_no_removal_steps covers the doctor guard.
  • test_a_readable_short_key_under_a_seatbelt_follows_doctor runs the real signing_key_health on a truncated key: under a foreign Seatbelt the steps print, as the boot preflight and doctor would refuse the key, and under Kiro Crew's own sandbox they do not. The foreign case fails without the require_denied_open argument.
  • test_relayed_refusal_is_not_followed_by_a_second_copy_of_the_steps checks that a died report whose gateway.log relay already shows the refusal does not print the steps a second time.
  • test_a_failing_key_probe_leaves_the_died_report_unchanged and test_unit_the_manager_refused_to_restart_gets_no_key_steps cover the probe error and the refused verb.
  • The tests live in test/test_cli_restart.py and test/test_cli_restart_readiness.py since test: split the rest of test_cli.py into topic files (2 of 2) #22152 split test_cli.py. Those two files and test_cli_server_facade.py give 144 passed; test_signing_key_preflight.py and test_sandbox_signing_key_mask_unreadable.py give 103 passed. flake8 and the scoped black gate pass.

Manual verification

N/A. The change is two print paths in _restart, and the tests drive _restart through both.

Related Issues

Closes #19828

Follow-up to #14457, replacing the refused-state banner promised there.

Tracked follow-up: #20054, implemented in #20055. When the replacement dies, the restart prints the last lines that gateway added to gateway.log, which also covers the persistence preflight, the preflight timeout and the no-worker-thread refusals.

Pattern harvest

Rule candidate: review-prompt
Pattern: a gateway boot refusal whose reason reaches only the gateway's own stderr, where kirocrew restart never shows it

Every boot refusal in slack/gateway.py writes its reason only to the gateway's own stderr, which kirocrew restart does not show. This PR fixes the short-key case with its repair steps. #20054 / #20055 fix the class by relaying the dead replacement's new gateway.log lines on the "died immediately" branch.

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

Contributions are accepted under the project's Apache-2.0 license.

@Pearcekieser
Pearcekieser requested review from a team and KiroCrewCaptain as code owners October 13, 2026 15:29
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Oct 13, 2026
@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision ec9453b44f6a27efc560f0b26286d030515d82bc 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 13, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of ec9453b44f6a27efc560f0b26286d030515d82bc via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the change adds output only, reuses the existing remedy and doctor's guard, and leaves exit codes and audit records unchanged.

Notes

  • _signing_key_refusal_lines is now the third copy of the confined / require_denied_open derivation. The other two are doctor_checks/access.py:73 and gateway_runtime/process_entry.py:185. If one copy changes and the others don't, restart, doctor and the boot preflight will disagree on "short". One shared helper in token_secret would keep them in step.

[DESIGN-REVIEWED] ec9453b

Description read

[DESCRIPTION-READ] 4b2b6e01a4f74c625da7404b13a8884728fd1836a8d8e9010263cda737644664

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 13, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed ec9453b44f6a27efc560f0b26286d030515d82bc via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] ec9453b

@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed ec9453b44f6a27efc560f0b26286d030515d82bc via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ec9453b

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): For the account that installed it, the system unit reads the same key file the restart checks. service/linux.py writes the system unit with User= set to the installing account, HOME taken from _home_for_user for that account, and the service_environment(home) lines, so the unit's config_dir() resolves to the same place as that account's CLI. A mismatch can happen only when a different account runs the restart, for example a sudo -H restart with HOME=/root. In that case signing_key_health checks a different path, which is normally absent, and the restart prints no steps, the same as main does today. The steps are printed only for a file that really is under 32 bytes, so they never point at a healthy key. No code change.

@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of ec9453b44f6a27efc560f0b26286d030515d82bc via the fork AI-review pipeline — 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 service-unit branch removes a real gap: the refusal only reaches the journal. The detached branch adds little now that #20055 relays gateway.log.

Notes

  • Item 2 — symptom-level: the steps print only when "the feat(cli): relay a dead replacement gateway.log tail on restart #20055 gateway.log relay printed nothing". The gateway's own refusal already reaches gateway.log, so the relay only comes back empty when the log can't be read. Subtraction: delete the else: branch after if tail: in _restart's died path, and keep the service-unit item.

What this change ships

Inventory (5 items) — 4 justified

Intent: when a restart fails because the gateway refused a truncated signing key, show the operator the repair steps in the restart terminal. This is a FIX.

  1. A service restart whose unit is not up now prints the key repair steps when the key is short — justified
  2. A detached restart whose replacement dies prints the steps when the gateway.log relay is empty — symptom-level; the relay already covers it
  3. Steps are withheld when the key cannot be opened, or under Kiro Crew's own sandbox mask — justified
  4. A refused service verb gets no probe and no steps — justified
  5. _signing_key_refusal_lines is added to the cli_server facade's type-checking exports — justified

[FIRST-PRINCIPLES-REVIEWED] ec9453b

Description read

[DESCRIPTION-READ] c5d1e3a701c898f504d27deba7e55009c8c38b9682f979c6698bc052943e03c0

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 13, 2026
@Pearcekieser
Pearcekieser force-pushed the fix/signing-key-refusal-launcher-hint branch from 0fec99e to 303fd45 Compare October 13, 2026 17:15
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

issue (non-blocking): Upheld, the restart's short branch should not skip doctor's open_is_denied guard. An agent shell whose confinement signals both miss sees the mode-0 mask over a healthy key as a short file, and the restart would have printed the steps that delete it. _signing_key_refusal_lines now returns nothing when token_secret.open_is_denied(key_path) is true, the same check doctor_checks/access.py makes before its removal steps. The gateway's own refusal still covers a real unreadable short key, because the boot preflight runs outside the sandbox. test_a_short_key_this_process_cannot_open_gets_no_removal_steps covers it, and the change is in the amended commit 303fd450cd.

@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 13, 2026
@Pearcekieser

Pearcekieser commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor Author
  • Item 1: the hint re-derives one refusal reason instead of relaying why the replacement exited

issue (non-blocking): Upheld, this fix is symptom-level. slack/gateway.py has 3 sibling boot refusals that print to stderr and raise SystemExit(1) into the same log the restart terminal never shows: the persistence preflight, the signing-key preflight timeout and the no-worker-thread exit. This PR covers none of them, and its hint re-probes the key from the CLI process rather than reading what the gateway said. Readiness has passed on this head, so I am not pushing a restructure for a non-blocking item. After this merges I will open a follow-up PR that relays the dead replacement's last gateway.log lines on the "died immediately" branch, which covers all 4 refusals, and drops _signing_key_refusal_lines with its signing_key_health and open_is_denied re-probe if the relay makes it redundant.

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

This PR prints the token_signing.key repair steps in the kirocrew restart terminal when the replacement gateway dies right away or a service unit is not up and the key is under 32 bytes, so the operator no longer has to open gateway.log or the journal to find them. The code is correct: _signing_key_refusal_lines (src/kiro_crew/cli_server.py:1494) uses the same signing_key_health look with sandbox evidence and the same open_is_denied guard kirocrew doctor uses, returns nothing on any other state or any exception, and only fires on the RESTART_NOT_UP and "died immediately" branches, not on RESTART_REFUSED. I tried to get it to hand the file-deleting steps to a healthy key: a sandbox mode-0 mask is caught by open_is_denied, a different-account sudo -H restart checks a path that is normally absent and prints nothing, and a probe error is swallowed; the tests cover each of these and would fail on main for the two positive cases. The one thing left is a follow-up item, so per our rule this is not an approve yet: your First Principles disposition agrees the fix is symptom-level and promises a later PR that relays the dead gateway's last gateway.log lines on the "died immediately" branch (cli_server.py:1887), which would also cover the 3 sibling refusals in slack/gateway.py (persistence preflight, signing-key preflight timeout, no worker thread). Please open a GitHub issue for that relay work and link it in the PR description; the description's "Pattern harvest: Not generalizable" line should also be updated, since the disposition now says the pattern does generalize. I will approve on the next round once the issue is linked. — crew-pr-reviewer (deep re-check)

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 14, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

@iamwhatever note (non-blocking): Both description changes are in. The relay follow-up is tracked as #20054 and implemented in #20055, which prints the last 20 lines the replacement added to gateway.log when it dies right away. Lines written before the restart are skipped, and each line is limited to printable characters and 400 of them. Related Issues now links #20054 and #20055. The Pattern harvest line now says the fix generalizes and names that PR as the class fix. No code changed on this PR, and the head is still 303fd450cd.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 14, 2026
@Pearcekieser
Pearcekieser force-pushed the fix/signing-key-refusal-launcher-hint branch from 303fd45 to ab29c51 Compare October 14, 2026 09:47
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): Rebased on main after #20055 merged, no behaviour change. Both PRs edit the died-immediately branch of the restart and the tests beside it; the resolution keeps both, so the relayed gateway.log lines print first and the signing-key repair steps follow on a truncated key. 58 targeted tests in test/test_cli.py pass, flake8 and the black gate are clean. New head ab29c51.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 14, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 20, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): Backend Tests (3.12, 2) on fa0e198 hit the #22007 flake a third time. test_facade_mirror_guards.py::test_every_name_the_test_trees_patch_through_a_facade_reaches_its_readers ran past the 120 s pytest timeout, with no assertion failure. This PR doesn't touch that test or the facade mirror. A maintainer re-run of job 118558096855 should clear it. I won't push again for this.

@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 20, 2026
@Pearcekieser
Pearcekieser force-pushed the fix/signing-key-refusal-launcher-hint branch from fa0e198 to f496c99 Compare October 21, 2026 08:21
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): Rebased on main 0b89e0c to pick up #22320, no behaviour change. New head f496c99. #22320 raises the per-test timeout for the whole-tree facade mirror guard scan, which is the #22007 timeout that failed Backend Tests (3.12, 2) on the last three heads. The diff is still 235 added lines across the same four files. All 108 tests in test/test_cli_restart.py and test/test_cli_restart_readiness.py pass, test/test_cli_server_facade.py passes, and flake8 is clean.

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

Pearcekieser commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor Author

note (non-blocking): Coverage Gate on f496c99 failed with "frontend-test=skipped -- failing closed", not on a test. This is the main regression in #22697: since #22425 a backend-only diff skips Frontend Lint, and that skip makes every test shard skip too, backend and frontend, which the gate rejects. So no tests ran on this head, and the earlier (3.12, 2) timeout question is still open. Other backend-only PRs show the same result today. I'll rebase once the #22697 fix lands on main; no code change is needed here.

@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 21, 2026
@Pearcekieser
Pearcekieser force-pushed the fix/signing-key-refusal-launcher-hint branch from f496c99 to 7699956 Compare October 22, 2026 14:46
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): Rebased on main 788f021, no behaviour change. New head 7699956. This picks up #22717, which fixed #22697: on f496c99 every test shard was skipped because the PR is backend-only, so Coverage Gate failed closed with no tests run. It also includes #22320, which raised the timeout behind the earlier Backend Tests (3.12, 2) failures. None of this PR's four files changed on main. The diff is still 235 added lines. 142 tests in test/test_cli_restart.py, test/test_cli_restart_readiness.py and test/test_cli_server_facade.py pass, and flake8 is clean.

@Pearcekieser
Pearcekieser force-pushed the fix/signing-key-refusal-launcher-hint branch from 7699956 to 9fee0a7 Compare October 22, 2026 15:23
@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • src/kiro_crew/cli_server_restart.py:39 restart checks the signing key without require_denied_open

issue (blocking): Fixed in 9fee0a7bf5. #22385 added require_denied_open to signing_key_health after this PR was written, and doctor and the boot preflight pass it while my call did not. So under a foreign macOS Seatbelt, a readable truncated key read as masked here, and the restart printed no steps for the exact refusal the hint exists for. _signing_key_refusal_lines() now computes confined once and passes require_denied_open=confined and not sandbox.agent_confinement_is_kirocrew_own(), the same expression as doctor_checks/access.py and process_entry.py. The separate open_is_denied check on a short key stays, as it does in doctor.

test_a_readable_short_key_under_a_seatbelt_follows_doctor writes a 5-byte key and runs the real signing_key_health. Under a foreign Seatbelt the steps print; under Kiro Crew's own sandbox they don't. The foreign case fails on 769995636a and passes on 9fee0a7bf5. 144 tests in test_cli_restart.py, test_cli_restart_readiness.py and test_cli_server_facade.py pass, as do 103 in test_signing_key_preflight.py and test_sandbox_signing_key_mask_unreadable.py. flake8 and the black gate are clean. The PR body's approach and Tests sections now say the same.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • cli_server_restart.py: RESTART_NOT_UP branch probes the key where the gateway.log relay could cover every boot refusal

thought (non-blocking): Agreed that relaying gateway.log on the service branch would cover every refusal there, not just the short key. I'm not swapping it in on this PR. The #20055 relay works because the detached path records the log's identity and size before it spawns the replacement. On the service branch the unit manager starts the process, the unit may have restarted more than once before the readiness wait gives up, and on Linux the reason can also sit only in the journal. Bounding which lines belong to this restart there is a separate change with its own tests. This PR keeps the narrow, read-only key check that doctor and the boot preflight already make, now with the same require_denied_open bit.

  • cli_server_restart.py: died-immediately branch restates the steps only when the relay printed nothing

thought (non-blocking): Keeping it. The fallback is six lines and runs only when _gateway_log_mark returned nothing or the read raised OSError, which is exactly when the operator has no relayed refusal on screen. Pointing at kirocrew logs -f there sends them to the same unreadable log. test_relayed_refusal_is_not_followed_by_a_second_copy_of_the_steps pins that a relayed refusal is never followed by a second copy.

@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention labels Oct 22, 2026
…ails

A gateway that refuses to boot on a token_signing.key under 32 bytes prints
its repair steps to its own stderr. Under kirocrew restart that stderr is
gateway.log (detached) or the journal (service), so the terminal that ran the
restart only saw 'died immediately' or 'not up' and a pointer to the logs.

When the replacement dies, or a restarted unit does not stay up, restart now
takes the same read-only look doctor does and, on a short key this process
can open, prints the steps from signing_key_remedy with the service-aware
restart command. A short key that refuses the open may be the sandbox mask
over a healthy key, so like doctor it gets no file-removing steps. A refused
restart verb never ran the gateway and gets no steps. Follow-up to kirodotdev#14457.
@Pearcekieser
Pearcekieser force-pushed the fix/signing-key-refusal-launcher-hint branch from 9fee0a7 to ec9453b Compare October 28, 2026 23:12
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): Rebased on main 6512997, no behaviour change. New head ec9453b. #25366 added _config_dir_owner and _died_replacement_message in cli_server_restart.py at the spot where this PR adds _signing_key_refusal_lines, so the two conflicted. Both are kept. The died-immediately branch now prints #25366's message, then the relayed gateway.log lines, then this PR's repair steps only when nothing was relayed. The diff is still 276 added lines in the same four files. 225 tests in test_cli_restart.py, test_cli_restart_readiness.py, test_cli_server_facade.py and test_signing_key_preflight.py pass, and flake8 and the black gate are clean.

@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention labels Oct 28, 2026

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

Approve at ec9453b.

When a restart fails on a truncated token_signing.key, the restart terminal now shows the repair steps. The probe is read-only. It uses doctor's sandbox bits, and doctor's open_is_denied guard keeps the file-removing steps away from a masked healthy key. Any error prints nothing (cli_server_restart.py#L679-L716). The steps appear only on a RESTART_NOT_UP service report and on a died replacement whose gateway.log relay was empty. Our earlier request is met: #20054 is linked (done by #20055), and the Pattern harvest line is updated. All checks are green.

AI findings judged non-blocking:

  • Design: this is the third copy of the confined/require_denied_open derivation (also doctor_checks/access.py#L70-L74). The copies match today, so this is a refactor suggestion, and open_is_denied still guards a drift.

I read the diff and CI. I did not run tests.

— crew-pr-reviewer (r134)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

kirocrew restart hides the truncated signing key repair steps

4 participants