Skip to content

fix(admission): name the remedy when the admission policy is missing - #23256

Merged
bolichen97 merged 1 commit into
mainfrom
fix/admission-policy-seed-marker
Oct 23, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/admission-policy-seed-marker

Conversation

@JLargent42

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: When the admission policy file is missing, the gateway's refusal says the policy is missing and how to get it back, instead of only "not on the approved allowlist".

On a 0.9.0.4 macOS install the gateway stops at startup. The log says no admission policy found ... failing closed, and then that the companion plugin "is not on the approved allowlist". Restarting does not help. The first-run seed is guarded by a one-shot marker, so the file is never written again. The only way out is to delete a hidden marker file that nothing names.

Why it matters

Every start of an edition with a companion plugin is blocked, and the message sends the user after the wrong cause. Two users hit this from two different install routes.

Not a goal

  • Re-seeding the policy automatically after it is deleted. Failing closed on a deleted policy is the intended security design, and it stays.
  • Changing whether a first run with KIROCREW_ADMISSION_POLICY set stamps the seed marker. That is a separate design question.
  • Changing the app-admission store (apps/admission.py).

What changed (motivation → approach → change)

The refusal blamed the allowlist, when the real problem was that no policy file existed and a restart could not make one.

A new helper, missing_policy_remedy() in platform/admission.py, gives an answer only when no policy is present (no env override, no default file). It tells two cases apart by the seed marker. If the marker is present, the seed already ran, so it names the marker to delete and says a managed fleet should restore its own file. If the marker is absent, the seed never managed to write the file, so it points at the data-home write.

platform/discovery.py adds that text to the PluginAdmissionError it raises. load_admission_policy adds it to its own error line, so other callers (the ops adapter path) log it too. A plugin rejected by a policy that does exist gets no extra text. The SEL audit record keeps the plain decision reason. The plugin-admission section of platform-context.md describes the recovery.

Backwards compatibility

Compatible: the same plugins are admitted and rejected as before. Only the text of the rejection and of one error log line grows.

Removes nothing: no path, key, record or check is taken away.

Tests

test/test_platform_admission.py::TestDiscoveryGate gains four tests:

  • deleted after the seed: the refusal names the missing policy and the marker path, and the file is still not re-created (fail-closed holds);
  • first run under the env override: the marker exists with no file, and the same remedy appears once the override is gone;
  • seed write fails: the refusal points at the write, not the marker;
  • policy present and the plugin banned: no missing-policy text, and missing_policy_remedy() is None.

With admission.py and discovery.py reverted to main, all four fail. With the change, all 97 tests in the file pass, plus test_governance_policy_signatures.py.

Manual verification

N/A: the change is message text on a boot-failure path, and the unit tests drive that path through discover_companion_context with real files in a temp home.

Related Issues

Closes #23255

Sibling sweep

Swept: git grep -n "load_admission_policy()" -- src/
Sibling: src/kiro_crew/apps/builtins/ops_mission_control/backend/companion.py -- not affected -- its rejection skips one ops adapter without stopping the gateway, and the error line from load_admission_policy now carries the remedy
Sibling: src/kiro_crew/apps/admission.py -- not affected -- a separate app-admission store whose absent file means admit, so it has no missing-file dead end

Pattern harvest

Rule candidate: review-prompt
Pattern: a fail-closed default that a restart cannot undo must name the step that undoes it in the error it raises

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • 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

@JLargent42
JLargent42 requested review from a team and KiroCrewCaptain as code owners October 23, 2026 00:24
@JLargent42
JLargent42 requested a review from bolichen97 October 23, 2026 00:24
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 23, 2026
@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision fdb31c5bddf1854494ed5e0733d845249f249e4d 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 23, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: this changes only message text on a path the unit tests already drive, and fail-closed behaviour is unchanged.

Notes

  • When the seed marker is present, the remedy tells the user to delete the marker. On a managed fleet that re-seeds the open default. The text does tell fleets to restore their own file, but it lists the open-default step first. Consider putting the fleet case first, or saying "standalone only" for the marker step.

[DESIGN-REVIEWED] fdb31c5

Description read

[DESCRIPTION-READ] 013d2e397c29c8eb5da23036695749c20ab0fb7a4c255ac10c7f5275fe9fd7a1

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of fdb31c5bddf1854494ed5e0733d845249f249e4d — 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 only changes message text, and the goal is the message. The issue still open is why fresh 0.9.0.4 installs have no policy file; this PR defers that.

Notes

  • Item 1 — symptom-level: "Two users hit this from two different install routes", but seed_default_policy stamps the marker even when wrote is False (admission.py:547), so an env-override first run leaves the home dead. The real cause is that stamping, and ## Not a goal defers it. The description does not say this PR fixes the message, not the cause.

What this change ships

Inventory (4 items) — 3 justified

Intent: an operator whose gateway refuses to boot for lack of an admission policy is told the real cause and the one step that recovers it. This is a FIX.

  1. When the admission policy is missing, the plugin refusal now names the missing file and the marker to delete, or points at the failed write. — symptom-level: the cause (the marker being stamped without a file) is deferred
  2. The "no admission policy found" error log line carries the same remedy, so the ops adapter path shows it too. — justified
  3. New public helper missing_policy_remedy(), with 2 non-test consumers (load_admission_policy, discover_companion_context). — justified
  4. The platform-context spec now describes how to recover from an absent policy. — justified

[FIRST-PRINCIPLES-REVIEWED] fdb31c5

Description read

[DESCRIPTION-READ] cdb9e93996187dd9f379b8349dca1741a4031418ff1c706ded195c3423ee47d8

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 commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] fdb31c5

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

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

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] fdb31c5

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

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

Looks good to ship. Head reviewed: a980a4c.

What I checked on this head:

  • Linked issue #23255 is tier:T1, and the diff stays inside its scope: message and remedy text only. No admission decision changes, the SEL record keeps the plain reason, and the seed stays marker guarded.
  • Main does not already carry this fix, and main has not moved the touched files since the merge base.
  • I ran test/test_platform_admission.py and test/test_governance_policy_signatures.py on this head: 153 passed. With admission.py and discovery.py reverted to main, the four new TestDiscoveryGate tests fail and the other 93 pass, so the new tests pin the new behaviour.
  • Both remedy branches match the seed code: a failed seed write leaves no marker, and an env override run stamps the marker with no file.
  • No touched path is on the security path list. The change adds no new input parsing, no auth or trust boundary change, and no secret handling.
  • AI lanes on this head: Design PASS, First Principles PASS, Opus and GPT no blocking findings, UX skipped. I found no other open PR on the same files.

Remaining maintainer check: PR Readiness is still pending and several backend test shards are still running. I will approve once readiness passes on this same head.

@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 23, 2026
@JLargent42
JLargent42 force-pushed the fix/admission-policy-seed-marker branch from a980a4c to fdb31c5 Compare October 23, 2026 06:50
@JLargent42

Copy link
Copy Markdown
Contributor Author

Rebased once onto main for the #23264 Windows fix.

@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 23, 2026

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

Approving at fdb31c5. This change is the fix for the linked incident, review found no issues on this head, and the maintainer accepted it. The remaining red Windows shard is a known flaky test on main that is tracked separately; auto merge will wait for required checks.

@bolichen97
bolichen97 enabled auto-merge (squash) October 23, 2026 14:46
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Oct 23, 2026
@bolichen97
bolichen97 merged commit ebdac55 into main Oct 23, 2026
155 of 156 checks passed
@bolichen97
bolichen97 deleted the fix/admission-policy-seed-marker branch October 23, 2026 15:52
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 23, 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.

admission: an absent policy rejects the companion with 'not on the approved allowlist' and no way back

2 participants