Skip to content

feat(apps): inject gateway origin into backends - #6599

Merged
NicholasRBowers merged 1 commit into
kirodotdev:mainfrom
dgomesbr:feat/aidlc-gateway-origin-v2
Sep 23, 2026
Merged

NicholasRBowers merged 1 commit into
kirodotdev:mainfrom
dgomesbr:feat/aidlc-gateway-origin-v2

Conversation

@dgomesbr

@dgomesbr dgomesbr commented Aug 28, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

A backend.entryPoint app child has no reliable way to learn the address of the gateway that spawned it. The gateway's port can be configured, OS-assigned (--port auto), or changed between generations — so a backend that needs to call back into the gateway (for example POST /api/notifications/push on a declared channel) today has to guess from config, an inherited variable, or a hardcoded default, and every one of those can point at a sibling gateway or at a port nothing listens on.

Why it matters

Without a trustworthy callback base, notification-declaring backend apps either cannot push at all or push to the wrong gateway — silent misdelivery that is worst exactly when several gateways or generations coexist on one host. A wrong-port callback is also a credential hazard: a conforming backend authenticates with its per-app secret, so an address that does not belong to its own gateway is a place that secret should never be sent.

What changed (motivation → approach → change)

Goal: hand every spawned backend its gateway's true origin — evidence, never a guess.

KIROCREW_GATEWAY_ORIGIN — set in the spawn env to http://<bound host>:<bound port>, built ONLY from the gateway's own bound-address evidence (KIROCREW_BOUND_PORT). The host follows the bind's family: 127.0.0.1 for IPv4 loopback/wildcard, [::1] for IPv6 loopback/wildcard (exported as KIROCREW_BOUND_HOST=::1 — an IPv6-only bind leaves IPv4 loopback seizable). Loopback shapes only: backend callbacks carry no Origin header, which the CSRF barrier trusts only from loopback peers — a specific-interface bind omits the origin instead of minting a refused one. With no valid evidence nothing is injected — fail closed, logged at warning when the app declares notification channels.

KIROCREW_GATEWAY_ORIGIN_PROOF — when the app has a readable .app_secret, the gateway also injects HMAC-SHA256(app_secret, origin) (hex): a spawn-time attestation that the origin was planted by a gateway holding that app's secret. Not a liveness signal; a secret-less backend gets the origin only. The remedy named in bolichen97's blocking review.

Port-reservation boot contract (dashboard/server.py) — the gateway reserves its port (binds AND listens) before the app-backend spawn pass and exports the socket's kernel-assigned name as the evidence. Nothing serves until SockSite wraps it; early callbacks queue in the backlog:

  • No credential-exposure window. The port is owned before any child exists — a squatter can never receive a backend's X-App-Secret; a held port fails the boot before anything spawns.
  • No lifecycle races, no overlap binds. No HTTP handler is reachable during the boot pass. The reservation applies asyncio's address-hygiene options (SO_REUSEADDR POSIX-only; IPV6_V6ONLY, so :: stays v6-only) plus Windows SO_EXCLUSIVEADDRUSE — a tightening asyncio never applies.
  • --port auto gets a real origin. The socket's name exists before the spawn — true origins for fixed and auto ports alike.

The reservation reuses the existing reclaim/retry ladder; on Windows an EADDRINUSE with no live holder (TIME_WAIT, where the exclusive bind is refused) stretches the wait to TcpTimedWaitDelay so routine restarts survive; a live holder keeps the fast exit. One failure handler spans the boot pass — spawn, hook wiring, runner setup, serve: any error sweeps the spawned backends (idempotent) and closes the socket, so no child outlives a failed boot.

Shutdown hardening — the shutdown sweep runs even when enumerating installed apps fails (list_apps moved inside the try whose finally stops backends).

Docs — injected-variables table and security bullets (docs/app-kit/api-reference.md); freshness, attestation and push-endpoint notes (docs/system-specs/modules/app-notifications.md); reservation-time export passages (config.md, cli.md, dev-fleet.md).

Scope note: feature by Diego Magalhaes (@dgomesbr); rebase, proof restoration, the reservation contract, removal of the pre-read os.chmod of .app_secret, and brand-rule respellings by Kiro Crew. apps/backend.py is main + the injection block only. mcp_core.py and port_resolution.py docstrings state the reservation-time export where readers meet the evidence; pod/runtime.py scrubs the origin variables at the pod boundary; apps/hooks_integration.py carries the matching comment. dashboard/listener_guard.py: main's Windows rebind watchdog now accepts the SockSite handoff — bind parameters read from the live socket's real name; recovery rebinds through _bind_once into a fresh SockSite, keeping the reservation's exclusive option set.

Tests

  • Origin + proof injection: exact-hex proof with the right key, wrong-key mismatch, secret-less → origin only, no bound-port evidence → neither injected.
  • Boot contract (each proven red on the prior design): the spawn pass observes the reserved socket's real port (superseding stale inherited evidence, fixed and auto alike); a failed reservation spawns no backends; a failed listen sweeps the backends it spawned; a runner-setup failure and a partial spawn-pass failure each sweep the spawned backends and close the reserved socket.
  • Reservation-socket parity: one test drives the real _bind_once on an ephemeral port and pins the whole option set — the socket is in the listen state, SO_REUSEADDR on POSIX, IPV6_V6ONLY on an IPv6 bind, and the Windows-exclusivity branch present — so no property can be silently dropped by a later edit (the helper is a module-level function precisely so this test needs no mocks).
  • Shutdown: sweep still runs when list_apps raises mid-shutdown.

Manual verification

  • isort / flake8 / mypy clean; 437 tests across the five affected backend/dashboard test files pass locally.
  • Full backend suite run at parity with pristine main (identical host-environment-dependent failures on both).

@dgomesbr
dgomesbr requested review from a team and smeyffret August 28, 2026 18:25
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Aug 28, 2026
@github-actions

ghost commented Aug 28, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — 🔴 changes requested (blocking)

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

Adjudication upheld 1 of 1 blocking finding(s); those must be resolved before merging.

BLOCKING -- src/kiro_crew/dashboard/server.py:2315 -- unknown reclaim outcomes trigger a four-minute boot stall
budget = max(budget, int(_TIME_WAIT_BUDGET_SECS / delay))
Windows port collision -> UNAVAILABLE/RECLAIM_FAILED -> gateway waits 240 seconds although no TIME_WAIT state was established.
Anchor: no-new-work-on-gateway-boot-path
Fix: extend the budget only when outcome == NO_HOLDER.

FINDING -- docs/app-kit/api-reference.md:962 -- "exported bound address when it is bound to one specific interface" contradicts the changed backend, which omits the origin for specific-interface binds -> Fix: document that these binds omit the origin.

FINDING -- test/test_dashboard_server_startup_coverage.py:476 -- changing SO_EXCLUSIVEADDRUSE from 1 to 0 leaves the source-string assertion green while removing exclusive ownership -> Fix: assert the live socket option is nonzero on Windows. (origin: validation)

[GPT-REVIEWED] 82b2033
[BLOCK-MERGE] 82b2033

Adjudication (Opus 4.8) — is blocking on each finding proportionate?

The finding names dashboard/server.py's new _reserve_dashboard_port budget-stretch line. Let me confirm the branch structure and the rule anchor, both of which I've now read: the outcome constants are NO_HOLDER, UNAVAILABLE, FOREIGN_HOLDER, HEALTHY_PEER, RECLAIMED, RECLAIM_FAILED (port_reclaim.py:63-68), and the diff's elif outcome not in (HEALTHY_PEER, FOREIGN_HOLDER) branch (patch, new server.py:~2313) does trigger the Windows 240s budget for UNAVAILABLE and RECLAIM_FAILED too — neither of which is the "no live holder / TIME_WAIT" signature the code's own comment claims. RECLAIM_FAILED in particular means a live process still holds the port and waiting cannot free it.

The finding cites anchor no-new-work-on-gateway-boot-path, which is blocking: true in AUTOSDE.yaml:129-130 and covers src/kiro_crew/dashboard/server.py (file-patterns:133). A 4-minute boot stall is exactly the compounding slow-boot harm that rule exists to prevent.

MEDIUM harm: up to a 240s boot stall on Windows on a rare port-collision outcome (UNAVAILABLE/RECLAIM_FAILED), confirmed at new server.py:~2313 (elif outcome not in (HEALTHY_PEER, FOREIGN_HOLDER) → budget = max(...)), with the recovery being eventual SystemExit(1) after the full budget (new server.py:~2325). Anchored to AUTOSDE.yaml:130 blocking: true; the real fix is the one-line narrowing to outcome == NO_HOLDER, near-zero remedy cost with no maintenance load.

[ADJUDICATION] 82b2033a4e4726aafa47f556419e19dc67c99a4a total=1 uphold=1 downgrade=0
UPHOLD F1 src/kiro_crew/dashboard/server.py:2315 reason=autosde-blocking-rule
[GPT-ADJUDICATED] 82b2033a4e4726aafa47f556419e19dc67c99a4a

@github-actions

ghost commented Aug 28, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

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

Review details

I've validated the candidate list (which reported no candidates) and independently examined every changed hunk: the bound-port-gated origin/proof injection in apps/backend.py, the host classification and env exports in start_dashboard, the _reserve_dashboard_port/_bind_once reservation ladder, the SockSite/bind_factory recovery in listener_guard.py, the except BaseException cleanup (runner cleanup + explicit sweep + socket close), the on_gateway_shutdown walk-inside-try move, and the pod-env KIROCREW_BOUND_HOST scrub.

Verified as correct rather than defective: the env vars are read from the gateway's os.environ and always set-or-popped (no stale leak); the reservation binds+listens before exporting, so the port is owned kernel-hard before any backend spawns; the SockSite recovery refuses to arm without bind_factory, preserving the exclusive option set; failure paths release both spawned backends and the socket idempotently; the TIME_WAIT stretch is gated on NO_HOLDER and os.name == "nt" exactly. Nothing clears the 80+ bar for a real defect in the changed lines.

No findings.

[OPUS-REVIEWED] 9ca5383

@github-actions

ghost commented Aug 28, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — 🟡 CONCERNS

Design-level review of 9ca53833985123d0d8219aa1b360e675dad49e38 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

Guard recovery may now die on Windows TIME_WAIT: the exclusive rebind keeps the ~15s ladder the boot path itself deemed too short for that refusal.

Watch

The PR's own reservation analysis says an SO_EXCLUSIVEADDRUSE bind "is documented to refuse the port until those remnants expire" and stretches the boot ladder to 240s on NO_HOLDER — but ListenerGuard recovery, which now rebinds through the same _bind_once, keeps 5 attempts × 8s max backoff and then _give_up exits the gateway. A listener death mid-serving (the guard's own scenario) leaves TIME_WAIT remnants on that exact port, so on Windows the recovery the guard exists for may be systematically refused into a full gateway exit; whether the old plain-bind recovery tolerated TIME_WAIT is a Windows semantics question only a real host settles.
Clears when: a Windows check shows the exclusive rebind succeeds within the guard's ladder against live TIME_WAIT remnants, or the guard's SockSite recovery gets the same NO_HOLDER TIME_WAIT budget as _reserve_dashboard_port.

[DESIGN-REVIEWED] 9ca5383

@github-actions

ghost commented Aug 28, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — 🟡 CONCERNS

Premise-level review of 9ca53833985123d0d8219aa1b360e675dad49e38 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/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

KIROCREW_GATEWAY_ORIGIN_PROOF is permanent App-Kit surface with zero consumers, backed only by a review link — delete or defer it until a defect is on record.

Not justified as shipped

  • Item 2 — inherited: the proof's only provenance is "The remedy named in [bolichen97's blocking review]" — a review assertion, not a linked issue, repro, or failing test; grep KIROCREW_GATEWAY_ORIGIN_PROOF: 0 consumers beyond the injection site, tests and docs (no shipped app declares channels from an entryPoint backend; the bridge RFC itself records "Phase 2 has no producer app").
    Subtraction: delete the proof injection in apps/backend.py and its two doc rows; ship the origin alone.
    Clears when: a linked issue or reproduction of the spoofed/inherited-origin defect on a real path, a counted consumer, or the deletion made.
  • Item 6 — rides along: a declared shutdown-robustness fix (list_apps moved inside the try) shipped beside the feature; harm named, test added.
  • Item 8 — undeclared: _arm_listener_guard's silent skip and the getattr softening exist, by their own comments, for "an inert site double in wiring tests" — "Real sites cannot hit this."
    Subtraction: delete the skip branch and getattr softening; stub _arm_listener_guard in the wiring tests instead.
    Clears when: the deletion made, or a real non-test path that reaches a socket-less site is named.
  • Item 10 — duplicate of _start_site (src/kiro_crew/dashboard/server.py): the description says the reservation "reuses the existing reclaim/retry ladder", but the diff copies it — post-patch the "still in use after" ladder exists twice in one file (base: once), already diverging (TIME_WAIT stretch in one copy only).
    Subtraction: fold the headless _start_site bind onto _reserve_dashboard_port + SockSite so one ladder remains.
    Clears when: the ladders unify, or maintainers accept the two-entrypoint divergence as deferred.

What this change ships

Inventory (10 items) — 6 justified

Intent: give every spawned entryPoint app backend a trustworthy address for the gateway that spawned it, so channel-declaring apps can push notifications back — an ADDITION.

  1. Spawned backends receive the gateway's real address (KIROCREW_GATEWAY_ORIGIN), omitted fail-closed with a warning — justified
  2. Backends also get an HMAC attestation of that address — inherited (zero consumers; provenance is a review link)
  3. The gateway owns its port (bound and listening) before any app backend spawns — justified
  4. Windows restarts wait up to 4 minutes for TIME_WAIT-pinned ports instead of 15 seconds — justified
  5. Any boot failure after the bind stops spawned backends and frees the port — justified
  6. Shutdown still stops backends when app enumeration fails — rides along (declared fix beside the feature)
  7. Windows listener recovery keeps the reserved port's exclusive-ownership options — justified
  8. The listener guard silently skips sites with no live socket — undeclared (exists only for test doubles)
  9. The gateway exports its bound host family (KIROCREW_BOUND_HOST) to children — justified
  10. Dashboard and headless boots use two separate port-wait ladders — duplicate of _start_site (src/kiro_crew/dashboard/server.py)

Capped at 10: an eleventh rider, the "KiroCrew"→"Kiro Crew" respelling of two log lines, is declared and mandated by the brand rule.

[FIRST-PRINCIPLES-REVIEWED] 9ca5383

@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 Aug 28, 2026
@dgomesbr

ghost commented Aug 29, 2026

Copy link
Copy Markdown
Contributor Author

Status update and one request for a maintainer.

Every CI/test check on this PR passes or is skipped except a single Windows test shard: Backend Tests (Windows) (3) (run 33216936703, job 99006265019). Windows shards 1, 2, and 4 pass.

That failure is not in this patch. It is a worker crash / timeout in the git-subprocess-heavy test/test_md_notebook.py (worker gw0 crashed with worker restart disabled, e.g. test_sync_refuses_rather_than_pushing_a_subset), none of which this change touches. The diff only modifies src/kiro_crew/apps/backend.py, test/test_app_backend.py, and two docs files - there is no patch-owned test failure.

I cannot rerun it as a fork contributor: the re-run-failed-jobs API returns 403 "Must have admin rights to Repository".

Could a maintainer please rerun just that one job (Backend Tests (Windows) (3)) once? A single rerun should clear the flake. I am not asking for a rerun-all and I am not claiming CI is green.

For reference: the PR is mergeable, head 36abf95, two commits. PR Readiness is still red on one blocking item because maintainer review has not happened yet - review is still required.

Thanks.

@bolichen97
bolichen97 enabled auto-merge August 29, 2026 23:58

ghost 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.

Description ↔ code mismatch: the KIROCREW_GATEWAY_ORIGIN_PROOF mechanism is not in this diff

Blocking finding from a Description-vs-code consistency audit. Criterion: the description claims a behaviour that is absent from the code, and the absent behaviour is the security property this PR is advertised on.

The claim

The PR body describes a proof mechanism in six places, including an end-to-end verification claim:

  • KIROCREW_GATEWAY_ORIGIN_PROOF = HMAC-SHA256(app_secret, origin) hex, injected only when the app has a .app_secret. The child recomputes it with its secret …
  • The proof lets a backend distinguish a gateway-minted origin from an inherited or spoofed env value before trusting it as a callback base.
  • TestGatewayOriginInjection (test/test_app_backend.py): exact origin/proof off the bound port (distinct from the app PORT), proof accepted under the right secret and rejected under a wrong key …
  • Verified end to end with an isolated app on port 6777: the backend received the gateway origin and a valid proof …

What the code actually does

src/kiro_crew/apps/backend.py injects exactly two variables:

+        env["KIROCREW_GATEWAY_ORIGIN"] = f"http://127.0.0.1:{int(bound_port)}"
...
+            _proxy_secret = secret_path.read_text().strip()
         if _proxy_secret:
             env["KIROCREW_PROXY_SECRET"] = _proxy_secret

Across all four changed files, the string KIROCREW_GATEWAY_ORIGIN_PROOF appears 0 times, and there is no HMAC computation. The only hmac token in src/kiro_crew/apps/backend.py is a pre-existing comment about the X-KiroCrew-Proxy header the gateway signs on forwarded requests — a different mechanism, unrelated to this env var.

test/test_app_backend.py's TestGatewayOriginInjection asserts on KIROCREW_GATEWAY_ORIGIN and KIROCREW_PROXY_SECRET only. There is no "accepted under the right secret / rejected under a wrong key" case, because there is nothing to accept or reject.

Why this blocks

The stated security property — that a child can tell a gateway-minted origin from an inherited or spoofed one — does not hold as implemented. KIROCREW_GATEWAY_ORIGIN arrives unauthenticated, so a spoofed env value is indistinguishable from a real one, which is precisely the case the description says is covered. A reviewer reading the body will approve on the assumption that an HMAC binding exists, and the "verified end to end … a valid proof" line asserts observed behaviour that the diff cannot produce.

The docs in this same PR (docs/app-kit/api-reference.md, docs/system-specs/features/app-notifications.md) are consistent with the code — they document KIROCREW_GATEWAY_ORIGIN + KIROCREW_PROXY_SECRET and never mention a proof. So the PR body contradicts both the code and its own docs.

Required change — pick one

  1. Implement it: inject KIROCREW_GATEWAY_ORIGIN_PROOF = HMAC-SHA256(app_secret, origin) gated on .app_secret existing, document it alongside the other two variables, and add the right-secret/wrong-key test cases the body already claims exist.
  2. Or correct the description: delete the proof/HMAC bullets, the rejected under a wrong key test claim, and the and a valid proof end-to-end line, so the body matches the actual change — inject the bound-port origin, plus the raw proxy secret when one exists.

Everything else in the description checks out and is not at issue: the bound-port-only guard on KIROCREW_BOUND_PORT, the restrict_to_owner-before-read_text (0600-before-read) ordering, fail-closed omission of the origin, missing-secret silent tolerance, and no-injection for non-entryPoint apps all match the diff and its tests.

Automated Description↔code consistency audit. Only these five classes are treated as blocking: described behaviour absent from code; undisclosed change to user-visible behaviour/API/permissions/security boundary; test-pass claims contradicted by evidence; undisclosed scope beyond what the description says; conflict with spec/docs/an invariant. Wording and style are never flagged.

@bolichen97
bolichen97 disabled auto-merge September 3, 2026 21:25
@bolichen97
bolichen97 enabled auto-merge (squash) September 3, 2026 21:25
@bolichen97

ghost commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

Open PR relationship audit

This is a consolidated, point-in-time code-level audit note. It compares complete merge-base diffs and current/merged code; it does not treat a shared topic as duplication or partial coverage as completion.

Relationship findings

  • PR #7901 is OVERLAPPING relative to this PR. The goals differ or the implementations can complement each other; this is not a duplicate claim. Recommended action for PR #7901: CONTINUE_DEVELOPMENT. Independent goals in one shared function. Keep both; sequence them and expect a one-hunk conflict resolution in the spawn-env block for the second to land. Files: src/kiro_crew/apps/backend.py.

No PR, Issue, label, branch, or review state was changed by the relationship-note portion of this audit.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 6, 2026
@bolichen97
bolichen97 force-pushed the feat/aidlc-gateway-origin-v2 branch from 36abf95 to cb42102 Compare September 8, 2026 19:22
@bolichen97

ghost commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

Rebased onto main 6ae74179 by a maintainer as part of the 2026-09-08 open-PR audit. Net diff is unchanged: +359/-4 in 4 files.

Conflicts resolved:

  • src/kiro_crew/apps/backend.py: import-block conflicts only (main added http.client / loopback_urlopen); took both sides, and the final commit needs no new imports. The .app_secret block re-applied cleanly onto main's drifted spawn-env code.
  • docs/system-specs/features/app-notifications.md: main moved this file to docs/system-specs/modules/app-notifications.md in docs: refresh prompts, skills and docs against the shipped code #8905. Your new "Reaching the endpoint from an entryPoint backend" section was moved verbatim to the new path.
  • docs/app-kit/api-reference.md: auto-merged.

Gates run locally on changed files: isort, flake8, black (both files are in .github/black-baseline.txt, so their pre-existing formatting is unchanged), and pytest test/test_app_backend.py -> 174 passed, 4 skipped.

Please review the resolution. A maintainer push makes the maintainer the last pusher, so a second approver is needed under the repo's last-push rule. Reply if anything looks wrong.

@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Sep 8, 2026
@NicholasRBowers

ghost commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

Verified legitimate: _probe_gateway_healthy requires an HTTP status line, the reserved socket answers none until SockSite.start(), so a second gateway racing for the same port can terminate a healthy booting peer.
Deferred, not fixed here: the terminate mechanism is pre-existing on main (this PR only lengthens the silent window from ~0 to the boot pass); the trigger needs two fresh boots contending for one port simultaneously; harm is bounded (orphans reaped by the next boot) and availability-class, not security.
The Clears-when remedies (reservation-time responder, or connect-accepted-but-silent + young-holder probe heuristic) are reclaim-ladder/boot redesign — outside this PR's intent ("Not a goal: redesigning the boot sequence").
Issue #11633 carries the task with the deferred-finding label, an assignee, and a due date.

@NicholasRBowers

ghost commented Sep 18, 2026

Copy link
Copy Markdown
Contributor
  • Extract the reclaim/retry ladder shared by _reserve_dashboard_port and _start_site — span=78dcfe53af80 — rebutted

Any dedup — extraction into a shared helper included — edits _start_site, the headless entrypoint's serving path on main, which is main-refactor scope under the standing maintainer follow-up ruling recorded on this PR's earlier rounds and outside round-0 intent.
Nine rounds of evidence strengthen the ruling rather than weaken it: the two ladders remain behaviorally identical and each is pinned by its caller's tests; no divergence has materialized.
The retrospective (#4) reviewed this exact suggestion and ruled KEEP: deferral to the follow-up already ruled by the maintainer, no code change in this PR.

@NicholasRBowers

ghost commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

Verified: start_enabled_app_backends/start_deferred_app_backends are invoked only by start_dashboard, where the reserved port exists before the main wave — the two-wave split no longer buys anything on that path.
Deferred, not collapsed here: the split is #10330's mechanism with its own ordering tests; folding it is main-refactor scope, and the wave is harmless as shipped (Dev Fleet simply starts in the second wave).
Issue #11633 carries the collapse task with the deferred-finding label, an assignee, and a due date.

@NicholasRBowers

ghost commented Sep 18, 2026

Copy link
Copy Markdown
Contributor
  • Item 5 — duplicate of _start_site's reclaim/retry ladder; delete _start_site or share one loop — span=7974a86f1a31 — rebutted

The named subtraction (delete _start_site, fold the headless path onto the reservation helper) rewrites the headless entrypoint's serving path on main — boot-sequence redesign that round-0 intent explicitly excludes, and the maintainer's standing follow-up ruling on this PR already assigns ladder unification to a separate change.
The duplication is stable, not drifting: both copies are pinned by their callers' tests and have stayed behaviorally identical across nine review rounds.
Retrospective #4 reviewed this item and ruled KEEP for this PR, deferral per the standing ruling.

@NicholasRBowers

ghost commented Sep 18, 2026

Copy link
Copy Markdown
Contributor
  • Item 8 — shutdown-sweep fix (list_apps moved inside the try) rides along; not the feature — span=5da7db143b2d — rebutted

The sweep IS this PR's safety mechanism: the origin/proof injection is only safe because no backend outlives its gateway, and the boot-failure handler fixed this round funnels into the same sweep. A shutdown path that skips the sweep when list_apps raises is a hole in exactly the guarantee this PR ships.
It was raised as a reviewer finding on an earlier round of this PR and fixed with a pinning test — removing it now would reopen a reviewed defect in code the diff already owns.
Declared in the PR body's shutdown-hardening line; smallest possible shape (one statement moved inside an existing try).

@NicholasRBowers

ghost commented Sep 18, 2026

Copy link
Copy Markdown
Contributor
  • Item 9 — "KiroCrew" → "Kiro Crew" log respellings ride along — span=dac0c07099ac — rebutted

Mandated, not elective: the repo's Brand Name Gate fails CI on any ADDED line spelling the product as one word, and these lines enter the diff via this PR's own additions and moves — the gate red-failed this PR's head 347141e until they were respelled.
Pre-existing occurrences on untouched lines are grandfathered and remain untouched; only lines this diff adds carry the respelling, so the change cannot be split out.

@NicholasRBowers

ghost commented Sep 22, 2026

Copy link
Copy Markdown
Contributor

The premise half is fixed where it is free: the PR description no longer claims the "complete asyncio.create_server option set" — it now names the Windows flag as a deliberate tightening asyncio never applies (body edited in place on this head; no code change, so the green lane stamps stand).
The verification half is real and deferred, not dismissed: #11633 Task 3 (due 2026-10-18) carries the Windows TIME_WAIT restart verification (or sizing the ladder past TcpTimedWaitDelay) plus the _bind_once posture-comment correction, to land with the next code-touching round rather than minting a comment-only head that resets four settled review lanes.
The tightening itself is retained deliberately: the exclusive bind is what makes the reservation's ownership guarantee hold on Windows against a co-resident SO_REUSEADDR overlap-bind — the credential-theft blocker GPT upheld in round 10 — and the lane concedes the hijack rationale is sound and precedented.

@NicholasRBowers

ghost commented Sep 22, 2026

Copy link
Copy Markdown
Contributor
  • Extract the shared reclaim/retry ladder so the two entrypoints cannot drift — span=c8e2a0141ab6 — rebutted

Standing ruling on this exact question (recorded on head 347141e, spans 3b412aae23a0 / 7cb26ed168f6, and re-affirmed by the round-11 retrospective): right end state, wrong PR. _start_site is main's tested surface — a dedicated test file with a real-bind EADDRINUSE integration test plus source-order pins in four other test files — and unifying the ladders here converts an additive feature PR into a boot-path refactor of both entrypoints, the exact blast-radius growth this PR's retrospectives identified as how its review rounds spiraled. The duplication is contained (one ladder, two homes, both documented as such) and the unification is recorded follow-up work.

@NicholasRBowers

ghost commented Sep 22, 2026

Copy link
Copy Markdown
Contributor
  • Migrate the headless entrypoint onto the reservation contract (follow-up PR) — span=07d607c4961c — rebutted

The lane itself frames this as "a worthwhile follow-up PR", which is the standing ruling verbatim (recorded on head 347141e, span a6b7416c56c9): the headless entrypoint spawns no app backends at boot, so it has no pre-spawn evidence property to uphold — the reservation exists for exactly that property. Converting it would rewrite main's tested bind path for symmetry alone. The headless path is byte-identical to main; the follow-up unification is where its test migration can be reviewed in isolation.

@NicholasRBowers

ghost commented Sep 22, 2026

Copy link
Copy Markdown
Contributor
  • Item 2 — origin proof's only support is a review comment; the spoofer it defeats delivers the verifying secret through the same channel — span=693118247303 — rebutted

Deleting KIROCREW_GATEWAY_ORIGIN_PROOF contradicts the maintainer's explicit ruling: bolichen97's blocking review on this PR names restoring the proof as the required change (#6599 (review)), and a maintainer ruling on this exact question stands over a lane preference. The threat-model question the lane raises — name the attacker who controls a backend's spawn env but not KIROCREW_HOME/.app_secret — is legitimate and is already parked as the standing needs-a-decision addressed to him on this thread; his answer either keeps the proof or removes it, and this PR ships his recorded instruction until he reverses it.

@NicholasRBowers

ghost commented Sep 22, 2026

Copy link
Copy Markdown
Contributor
  • Item 4 — _reserve_dashboard_port copies _start_site's reclaim/retry ladder; the two will diverge — span=743876c156ff — rebutted

The lane's own subtraction line concedes "acceptable as deferred", which is the standing ruling (heads 347141e spans 3b412aae23a0 / 7cb26ed168f6): the two copies serve different contracts on different entrypoints — the reservation returns an owned, listening socket before the spawn pass (the pre-spawn evidence property), while _start_site binds-and-serves for the headless path, which has no such property to uphold. Collapsing them means refactoring main's tested bind surface (dedicated test file, real-bind EADDRINUSE integration test) inside a feature PR. The deletion is recorded follow-up work; until it lands, both homes document the duplication explicitly.

@NicholasRBowers

ghost commented Sep 22, 2026

Copy link
Copy Markdown
Contributor
  • Item 9 — guard arming's decline path has zero production consumers; set _server = None on the doubles instead — span=8fef427a850e — rebutted

The decline path is a deliberate fail-open posture for an auxiliary recovery watchdog, not a test-double accommodation: the listener guard exists to recover a dropped Windows listener, and a boot that crashes with AttributeError because its watchdog cannot read a listener's name inverts that priority — the monitoring aid must never be the boot liability. A site exposing no live listener genuinely cannot be guarded (there is no real socket name to re-arm on), so declining with a log line is the correct semantics for that input, whoever supplies it; that today only doubles supply it is why the diff's comment says so honestly. The alternative (doubles grow _server = None, production stays strict) still requires the constructor to handle None — the same branch, moved — while making every future site-shaped test double repeat the accommodation. One tolerant read in the arming gate is the smaller total surface, and the regression test pins it.

@NicholasRBowers

ghost commented Sep 22, 2026

Copy link
Copy Markdown
Contributor

The lane's own subtraction line says "larger than this diff, deferrable", and the retirement is now recorded: #11633 (due 2026-10-18) carries migrating the Dev Fleet broker to KIROCREW_GATEWAY_ORIGIN and deleting the scoped KIROCREW_BOUND_PORT pass-through, folded with Task 2's two-wave collapse — the deferred wave exists for that pass-through, so the two retire together. Removing it inside this PR would touch #10330's mechanism and its ordering tests, the exact scope the round-11 retrospective ruled out.

@NicholasRBowers

ghost commented Sep 22, 2026

Copy link
Copy Markdown
Contributor
  • Item 8 — shutdown list_apps hardening rides along — span=043dc2ed481e — rebutted

The sweep IS this PR's safety mechanism (standing answer, recorded on head f1e6f3a span 5da7db143b2d): the origin/proof injection is only safe because no backend outlives its gateway, and the boot-failure handler funnels into the same sweep — a shutdown path that skips it when list_apps raises is a hole in exactly the guarantee this PR ships. It was raised as a reviewer finding on an earlier round of this PR and fixed with a pinning test; the lane itself marks it "declared, tested". Smallest possible shape (one statement moved inside an existing try).

@NicholasRBowers

ghost commented Sep 22, 2026

Copy link
Copy Markdown
Contributor
  • Socket-readiness ratchet anchors before serving (test/test_runtime_memory.py:168) — span=08c9b3c79343 — rebutted

Downgraded by the lane's own adjudication as disproportionate (harm LOW): the anchor (web.SockSite(...) construction) and await site.start() are adjacent statements, HeapTrimMaintainer() is created hundreds of lines downstream, and the assertion still catches any placement above the construction line — the only escape is inserting the maintainer between two adjacent statements, a benign ordering for a heap-trim scheduler. The re-anchor is a one-line improvement worth taking, but not worth minting a new head for alone (it would reset four settled review lanes and a running CI board); it rides with the next code-touching round, and #11633's follow-up work provides one.

The gateway spawns each backend.entryPoint app child with
KIROCREW_GATEWAY_ORIGIN, its own http://127.0.0.1:<bound port> address
(or http://[::1]:<port> for a v6-loopback bind), so the backend can
call back to the gateway (for example POST /api/notifications/push on
a declared channel). The origin is built ONLY from KIROCREW_BOUND_PORT,
the port this gateway actually owns, and only for the loopback bind
shapes: a backend callback carries no Origin header, and the CSRF
barrier trusts an Origin-less mutating request only from a loopback
peer, so a specific-interface bind omits the origin rather than mint
one whose every callback would be refused. With no valid evidence both
the origin and its proof are omitted, so a backend that needs a
callback base fails closed (and the omission is logged at warning when
the app declares notification channels, since dormancy is then
operator-visible state).

When the app has a .app_secret, the gateway also injects
KIROCREW_GATEWAY_ORIGIN_PROOF = HMAC-SHA256(app_secret, origin), hex —
a spawn-time attestation that the origin was planted by a gateway
holding that secret rather than an inherited or spoofed env value.
A secret-less backend gets the origin only.

At boot the gateway RESERVES its port — binds and listens, with accept
deferred to the SockSite handoff — before the app-backend spawn pass
and exports the reserved socket's real name as the evidence: the port
is kernel-owned and overlap-proof before any child exists; nothing is
served during the pass, so no lifecycle handler can race it; and
--port auto is real before the spawn, so boot-spawned backends get the
true origin for fixed and auto ports alike. A failed reservation dies
before anything spawns; every failure after it — spawn pass, runner
setup, serve — runs one unconditional handler that sweeps the backends
this boot spawned and closes the socket, so no child ever outlives a
boot whose port promise failed. On Windows, an EADDRINUSE with no live
holder (the TIME_WAIT signature) stretches the reservation's wait to
TcpTimedWaitDelay, because the exclusive bind refuses the port while
remnant connections expire and a routine restart must out-wait them.

The Windows listener guard (main's rebind-on-dead-listener watchdog)
now accepts the SockSite this handoff serves on: bind parameters are
captured from the live socket's real name — never wider than the
reservation — and recovery rebinds through the reservation's own bind
primitive into a fresh SockSite, so a recovered listener carries the
same exclusive option set the reservation held.

Original feature authored by Diego Magalhaes (dgomesbr). Rebase onto
current main, restoration of the origin-proof from the predecessor PR,
the port-reservation boot contract, and removal of the pre-read chmod
of .app_secret (symlink-following os.chmod flagged in review; the
writer already enforces 0600) by Kiro Crew.

Co-authored-by: Kiro Crew <noreply@kirodotdev.github.io>
@NicholasRBowers

ghost commented Sep 23, 2026

Copy link
Copy Markdown
Contributor

The lane's clears-when offers two exits, and both route through the same Windows host evidence this PR cannot produce: whether an exclusive rebind clears TIME_WAIT remnants inside the guard's 5-attempt ladder is, as the lane itself says, "a Windows semantics question only a real host settles" — the identical question #11633 Task 3 already carries for the boot ladder (due 2026-10-18), now extended in place to name the guard's recovery window as a second consumer and the budget-parity option as its remedy.
Sizing the guard's ladder today without that evidence would be guessing at the same constant twice: the boot-path stretch shipped this round only because its trigger (NO_HOLDER EADDRINUSE) was pinned by a red-proven test, and the guard's mid-serving death delivers a different precondition (the dying listener's own socket just closed, which is what starts the TIME_WAIT clock) that the Windows check must characterize first.
Deliberately not minted as a new head: the item is advisory on an otherwise fully green board, and the budget-parity change rides with #11633's code-touching round.

@NicholasRBowers

ghost commented Sep 23, 2026

Copy link
Copy Markdown
Contributor
  • Item 2 — KIROCREW_GATEWAY_ORIGIN_PROOF is permanent App-Kit surface with zero consumers, backed only by a review link — span=840e282e4fe9 — rebutted

Deleting the proof contradicts the maintainer's explicit ruling: bolichen97's blocking review on this PR names restoring the proof as the required change (#6599 (review)), and a maintainer ruling on this exact question stands over a lane preference. The provenance question the lane raises is legitimate and is already parked as the standing needs-a-decision addressed to him on this thread; his answer either keeps the proof or removes it, and this PR ships his recorded instruction until he reverses it. Same span, same answer as the prior head (span 693118247303 on d762c6c) — nothing about the proof changed in this diff.

@NicholasRBowers

ghost commented Sep 23, 2026

Copy link
Copy Markdown
Contributor
  • Item 6 — shutdown-robustness fix (list_apps moved inside the try) rides along — span=ab10b3545b20 — rebutted

The sweep IS this PR's safety mechanism (standing answer, recorded on head f1e6f3a span 5da7db143b2d and re-affirmed on d762c6c span 043dc2ed481e): the origin/proof injection is only safe because no backend outlives its gateway, and the boot-failure handler funnels into the same sweep — a shutdown path that skips it when list_apps raises is a hole in exactly the guarantee this PR ships. It was raised as a reviewer finding on an earlier round of this PR and fixed with a pinning test; the lane itself marks it "declared... harm named, test added". Smallest possible shape (one statement moved inside an existing try).

@NicholasRBowers

ghost commented Sep 23, 2026

Copy link
Copy Markdown
Contributor
  • Item 8 — _arm_listener_guard's silent skip and getattr softening exist only for an inert site double in wiring tests — span=6537917da875 — rebutted

The decline path is a deliberate fail-open posture for an auxiliary recovery watchdog, not a test-double accommodation (standing answer, recorded on d762c6c span 8fef427a850e): the listener guard exists to recover a dropped Windows listener, and a boot that crashes with AttributeError because its watchdog cannot read a listener's name inverts that priority — the monitoring aid must never be the boot liability. A site exposing no live listener genuinely cannot be guarded (there is no real socket name to re-arm on), so declining is the correct semantics for that input, whoever supplies it; that today only doubles supply it is why the diff's comment says so honestly. The proposed subtraction (stub _arm_listener_guard in the wiring tests) removes the arm gate from exactly the tests that exercise start_dashboard's boot sequence, trading a covered branch for an uncovered stub; one tolerant read in the arming gate is the smaller total surface, and the regression test pins it.

@NicholasRBowers

ghost commented Sep 23, 2026

Copy link
Copy Markdown
Contributor
  • Item 10 — the reservation copies _start_site's reclaim/retry ladder; two copies in one file, already diverging — span=0baed93be82e — rebutted

Standing ruling on this exact question (recorded on head 347141e spans 3b412aae23a0 / 7cb26ed168f6, re-affirmed on d762c6c spans c8e2a0141ab6 / 743876c156ff, and by the round-11 retrospective): right end state, wrong PR. The two copies serve different contracts on different entrypoints — the reservation returns an owned, listening socket before the spawn pass (the pre-spawn evidence property), while _start_site binds-and-serves for the headless path, which spawns no backends and has no such property to uphold. The divergence the lane cites as new evidence is that contract difference made visible: the TIME_WAIT stretch exists to keep the reservation's ownership guarantee affordable on Windows restarts, and the headless path was left byte-identical to main deliberately — unifying the ladders here converts an additive feature PR into a boot-path refactor of main's tested bind surface (dedicated test file, real-bind EADDRINUSE integration test, source-order pins in four other files). The unification is recorded follow-up work, and its clears-when ("maintainers accept the two-entrypoint divergence as deferred") is the recorded state.

ghost 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.

Re-reviewed at head 9ca5383. The blocking description↔code mismatch is resolved by implementing the advertised mechanism: KIROCREW_GATEWAY_ORIGIN_PROOF is injected in apps/backend.py as HMAC-SHA256(app_secret, origin), only when the secret is readable and the origin was itself injected; it is documented in the api-reference table and the app-notifications spec, and the right-key / wrong-key / secret-less / no-evidence cases are pinned by tests that drive the real spawn path. Body, docs and code now agree.

Independently verified the rest: bound-port-only, loopback-only origin ([::1] for v6 binds; specific-interface binds fail closed with a warning for channel-declaring apps); the port reservation (_bind_once: family-resolved, SO_REUSEADDR / IPV6_V6ONLY / SO_EXCLUSIVEADDRUSE, immediate listen) precedes the backend spawn pass; one failure handler sweeps spawned backends and closes the socket; SockSite handoff and ListenerGuard recovery use the same bind primitive; the shutdown sweep survives a list_apps failure. 446 tests across the ten touched test files pass locally; flake8 / isort / brand gate clean; the branch merges cleanly onto current main. Approving.

Residual nits, non-blocking (fine as follow-ups): the config / cli / dev-fleet specs and the mcp_core.py / port_resolution.py docstrings still say _export_bound_port republishes after the reservation, which the dashboard path no longer does; the new KIROCREW_BOUND_HOST variable is undocumented in config.md; app-notifications.md omits the [::1] origin shape; the reservation window vs a different-home peer's reclaim probe stays tracked in #11633. Note for other reviewers: server.py is +229/-22 under git diff -w — the large raw diff is indentation from the try/except wrap.

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.

6 participants