Skip to content

fix(env): reload .env credential changes without a gateway restart - #23569

Closed
RohanK6 wants to merge 2 commits into
mainfrom
env-hotreload-22450-v4
Closed

RohanK6 wants to merge 2 commits into
mainfrom
env-hotreload-22450-v4

Conversation

@RohanK6

@RohanK6 RohanK6 commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An edit to $KIROCREW_HOME/.env takes effect on a running gateway, restarting only the affected channel, without a full gateway restart.

Edits to $KIROCREW_HOME/.env took effect only after a full gateway restart. The live config watcher fingerprinted config.json only, and nothing re-read .env after boot. The dashboard's own credential writer applied its changes live, but a hand edit or any other writer did not, so a rotated token kept reading as the old value until someone restarted the gateway.

Why it matters

Operators rotate channel credentials by editing .env. Today the edit silently does nothing until a restart, so a revoked token keeps a channel failing to authenticate, and a new token looks "saved" but is not in force. Requiring a full restart for a credential change also drops every running session.

Not a goal

  • Hot-swapping a Slack token in place. Slack's client is host-managed with no in-process restart path, so a Slack token change logs a "run kirocrew restart" notice instead.
  • Pushing a new environment into already-running children (ACP sessions, MCP servers). They keep their environment until they respawn.
  • Changing which keys .env supports or how boot reads it.

What changed (motivation → approach → change)

Symptom: a .env edit is ignored until restart. Root cause: ConfigWatch never watched .env. Change: .env is reconciled in the same poll cycle that already reloads config.json.

operator edits $KIROCREW_HOME/.env
        │
        ▼
ConfigWatch._cycle()  ── same poll that already reloads config.json
        │
        ├─ env_fingerprint(.env) unchanged → nothing to do
        │
        └─ env_fingerprint(.env) changed
                │
                ▼
        read_env_credentials_raw()       (off-loop, permission-checked)
        _prepare_path_additions()        (off-loop: PATH expand + validate)
                │
                ▼
        diff vs baseline (seeded once at boot from the raw map
        load_credentials() actually read, not a later disk read)
                │
                ├─ validate every changed key first (atomic batch)
                │
                ▼
        apply_env_credential_changes()   (on-loop: os.environ mutation only)
                │   set/pop os.environ, honouring the Docker scrub and PATH carve-outs
                │   pop only what .env itself propagated (ownership is recorded)
                │
                ├─ success → advance fingerprint + baseline
                │            dispatch credentials.<KEY> (+ Teams restart_credentials)
                │                     │
                │                     ▼
                │            restart_channel() re-reads load_credentials()
                │            (Slack: host-managed → "run kirocrew restart" notice)
                │
                └─ failure → leave fingerprint + baseline untouched
                             next tick retries the whole diff
  • After boot, every gateway-side credential read (channel reconnect, readiness badge, jira/doctor/upload-destination) uses load_credentials(propagate=False), so a worker-thread read cannot reseed a credential the watcher just removed.
  • The dashboard's credential writer now goes through the same apply_env_credential_changes instead of its own set/pop loop, so it also respects the Docker credentials scrub.
  • A .env PATH line is expanded and validated off the event loop (env.prepare_env_path_additions, run via asyncio.to_thread) and handed to the applier as path_additions. A ~otheruser entry calls pwd.getpwnam / the SAM database, and that lookup no longer runs on the loop. os.path.expanduser semantics are unchanged.
  • A live set records .env ownership only when the write takes the entry over (a new key, a rotation, an overwrite of a foreign value, or a key .env already owns). A line whose value merely matches what the process inherited from a service unit or shell is not owned, so removing it later leaves the inherited credential in place, as boot's setdefault already does.
  • The .env ownership record survives an in-app restart through one environment marker, _KIROCREW_ENV_OWNED_KEYS. The record is Python module state, and os.execv keeps os.environ but resets module state, so without it the restarted gateway would find every .env key already set, treat each one as inherited, and never pop any of them on a later removal. Right before the exec, reexec_launcher / reexec_python_module call _carry_env_ownership_across_reexec, which writes the owned key NAMES (comma-joined, no values; an empty marker when nothing is owned) into _KIROCREW_ENV_OWNED_KEYS. In the successor, the first load_credentials(propagate=True) (at the latest the one in run_gateway, which runs before the orchestrator is built and before anything in that function spawns a process) calls adopt_env_owned_keys_from_reexec, which pops the marker from os.environ and restores the record, so spawned children never inherit it. The only callers of those two seams are the gateway's update/restart paths, and a failed exec there exits the process (exit_after_failed_restart_exec) rather than leaving it running with the marker set. If writing the marker fails, the restart still goes ahead (a warning is logged), and the only effect is that the restarted gateway treats those keys as inherited: a later .env removal leaves them set until the next full restart, the same as any inherited value.
  • The applier decides per os.environ ENTRY rather than per .env spelling. On Windows (case-insensitive os.environ) every spelling of a key (HTTPS_PROXY / https_proxy) is grouped and resolved once, to the first non-empty spelling in .env order (boot's setdefault precedence), so a rename, a partial duplicate removal, or both spellings edited in one save cannot leave the entry depending on iteration order. On POSIX each entry has one spelling, so nothing changes there.
  • The watcher's diff (changed_env_keys) also compares each entry's effective value, so a Windows save that only reorders two spellings with different values is applied instead of silently adopted as the new baseline.
  • The Weixin QR sign-in writes its token through the same apply_env_credential_changes as the dashboard channel writer, so it records .env ownership (a later removal of the line revokes it in-process) and keeps the Docker scrub guard.
  • The Weixin QR sign-in's .env + config.json commit runs under live.hold() (like every sibling channel saver) and through drained_to_thread, so the watcher never restarts Weixin between the two writes and a cancelled request never releases the hold mid-write.
  • The boot .env record is tied to the file it was read from: the watcher adopts it only for the same .env, so a record from another data home is never taken as its baseline.
  • Teams: closing the client on a credential removal also clears its bound webhook handler and returns 503 for a request already past the close check, because the inbound route stays registered independently of the client. A tenant-only edit restarts Teams through a new restart_credentials descriptor field. The tenant gets its own descriptor field rather than joining credentials because readiness (channels.py channel_readiness) reports any absent credentials key as missing, and an unset tenant is the supported multi-tenant mode.
  • Teams: the webhook handler (state.teams_on_activity) is bound only once a client is the accepted handle, after boot's start_channels and after a restart passes its generation check. maybe_start_teams no longer binds it before the connect completes, so a restart superseded mid-connect never exposes its handler (the route answers 503 until then).
  • Slack: the restart-needed notice matches credential keys by canonical entry name, the same rule as registry.changed_credential_keys, so a lowercase .env Slack key on Windows still gets the notice.
  • The .env writers match lines by canonical entry name (_env_name_key), not literal spelling: the dashboard channel writer (_write_env_updates_locked) and the Weixin sign-in's _write_env_secret / _read_env_value / _delete_env_key. Before this, on Windows a hand-typed slack_bot_token= line was left in place and the saved SLACK_BOT_TOKEN= was appended after it, so the first-non-empty-spelling rule above put the OLD token back in force while the save reported success. Now a save rewrites the first case-equivalent spelling under the declared name and drops the rest, a clear removes every spelling, and the rollback read returns the spelling boot actually propagates. On POSIX the canonical name is the name itself, so a lowercase line is a different variable and is left alone.

This supersedes #23027, #23470, #23491 and #23514 (all closed). The reviewed change is one commit on current main, plus a second commit for the Windows case-spelling writer fix above, so PR Hygiene's two-commit limit is met without a force-push. It folds in every review fix from those PRs, including the structural-guard registrations, the Weixin sign-in hold, and scoping the boot .env record.

Backwards compatibility

Compatible: boot still seeds .env with setdefault, every key .env accepted before is still accepted, and PATH entries resolve exactly as before.

Removes nothing: the diff adds a watcher input and routes existing credential writes through one applier; no key, kind, public function or stored data is removed or renamed.

Reader: src/kiro_crew/dashboard/messaging_api/channel_config_writes.py:write_channel_env -- crew page -- under _KIROCREW_CREDS_SCRUBBED a dashboard save no longer writes credential keys into os.environ, matching the boot loop; children read them from .env (test_a_landed_write_honours_the_docker_creds_scrub)

Tests

Proof: PROVEN test/test_channel_boot_hot_reload.py::TestTeamsCloseClearsWebhookHandler::test_closing_teams_clears_the_late_bound_webhook_handler, test/test_channel_boot_hot_reload.py::TestTeamsWebhookPublishedOnlyForTheAcceptedClient::test_an_accepted_start_binds_its_handler, test/test_channel_boot_hot_reload.py::TestCredentialChangeRestartsChannel::test_a_credential_change_restarts_the_owning_channel, test/test_channel_boot_hot_reload.py::TestCredentialChangeRestartsChannel::test_a_credential_change_for_a_degraded_channel_is_deferred_not_dropped, test/test_channel_boot_hot_reload.py::TestSlackCredentialChangeWarns::test_a_slack_token_change_logs_a_restart_needed_notice , test/test_slack_config_handlers.py::test_windows_save_replaces_a_lowercase_spelling_of_the_key (head 5e779ea)

  • test/test_env_credential_hot_reload.py: an env-only edit dispatches credentials.<KEY> and applies os.environ; a failed apply leaves the baseline so a repair re-applies the rotation; an undecodable or wide-encoded .env is retried rather than read as every key cleared; a removal pops only what .env propagated; a .env PATH edit is expanded on a worker thread, not the loop thread; a Windows case-duplicate keeps its entry when one spelling is removed; a live add that matches an inherited value does not take ownership, so deleting the line keeps the inherited token, while an add that writes a new value does own it and is popped on removal; both spellings edited in one save resolve to boot's precedence in either iteration order, modelled with a case-folding os.environ; a reorder of two Windows spellings with different values is a diff and installs the new winner, while a reorder of equal values is not.
  • test/test_dotenv_path_extension.py: a .env PATH line appends absolute directories behind the existing PATH, deduped; relative and unexpanded entries are dropped with a warning; ~ and ~otheruser still expand through os.path.expanduser.
  • test/test_channel_boot_hot_reload.py: a credential change restarts only the owning channel; a degraded channel's change is deferred, not dropped; a Slack token change logs the restart notice; closing Teams clears the late-bound webhook handler; a Teams restart superseded mid-connect never binds its webhook handler while an accepted one does; a lowercase Slack key on Windows still logs the notice.
  • test/test_weixin_qr.py: a first sign-in records ownership, so deleting the line afterwards revokes the token in-process; a confirmed sign-in persists while the watcher is held and a cancelled one keeps the hold until the write finishes; a boot record from another .env file is refused; on Windows a sign-in replaces a lowercase weixin_token line and the rollback delete removes every spelling, while on POSIX both leave the lowercase name alone.
  • test/test_slack_config_handlers.py: on Windows a dashboard save replaces a lowercase spelling of the key, collapses several spellings to one line where the first was, and a clear removes every spelling; on POSIX a lowercase name is left untouched. The five Windows cases fail against the previous writers.
  • test/conftest_resets.py: the boot .env record and the ownership set are reset around every test, so neither leaks across an xdist worker.
  • test/test_teams_gateway.py: maybe_start_teams registers the transport but leaves the webhook handler unbound for the host.
  • test/test_channel_env_write_off_loop.py: the dashboard writer honours the Docker credentials scrub.

Local on head 609fb58fbc (Python 3.12): 1775 passed across every changed test file plus the facade-mirror, gateway-bindings, composition-contract, loader-owners, env BOM, config-live, host-isolation and flake-ratchet suites; flake-pattern ratchet passes against the merge base.

Local on head 5e779ea66e (Python 3.12): 1367 passed across all 15 changed test files; isort and flake8 clean on every file the second commit changes; mypy src/kiro_crew/ clean (3584 files); scripts/check_black_formatting.py gate passes.

Manual verification

N/A — the watcher cycle, applier, and channel restart dispatch are each driven end to end by the ConfigWatch._cycle() tests above against a real temp .env, which is the path a hand edit takes.

Related Issues

Fixes #22450

Sibling sweep

Swept: git grep -nE "load_credentials(|apply_env_credential_changes|os.environ[.*] *=" -- src/
Sibling: src/kiro_crew/dashboard/messaging_api/channel_config_writes.py -- changed here
Sibling: src/kiro_crew/slack/gateway_runtime/channel_lifecycle.py -- changed here
Sibling: src/kiro_crew/dashboard/source_providers/jira.py -- changed here
Sibling: src/kiro_crew/dashboard/upload_destination.py -- changed here

Swept (case-equivalent .env spellings): git grep -nE 'split("=", 1)[0]|partition("=")' -- src/
Sibling: src/kiro_crew/dashboard/messaging_api/channel_config_writes.py:_write_env_updates_locked -- changed here
Sibling: src/kiro_crew/dashboard/handlers/weixin_qr.py:_write_env_secret, _read_env_value, _delete_env_key -- changed here
Sibling: src/kiro_crew/cli_setup.py:_read_env_pairs -- not changed: kirocrew setup --slack keys its merge by literal spelling, so on Windows a lowercase Slack line also survives a setup save. That is pre-existing, outside this diff, and is a CLI setup path rather than the dashboard rotation the finding names; left for a follow-up so this PR stays within two commits.

Pattern harvest

Not generalizable: the defect was one missing watcher input (.env alongside config.json), not a repeated code shape a rule could catch.

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) — docs/system-specs/modules/config.md
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

…22450)

Edits to $KIROCREW_HOME/.env took effect only after a full gateway
restart: the live config watcher fingerprinted config.json only and
nothing re-read .env after boot. The dashboard's own credential writer
applied its changes live, but a hand edit or any non-dashboard writer
did not.

ConfigWatch now reconciles .env in the same cycle that reloads
config.json. It tracks a separate env fingerprint
(loader.env_fingerprint), kept out of _config_fingerprint because that
one is the parsed-config cache key. On an .env change it re-reads the
raw credential map off the loop, diffs it against a baseline, and
pushes changed keys into os.environ (set/pop), dispatching the same
path a synthetic credentials.<KEY> change takes so the channel-restart
applier restarts only the channels whose descriptor credentials
changed (restart_channel, which re-reads load_credentials). Slack is
host-managed with no in-process restart path, so a Slack token change
logs a restart-needed notice instead. Teams gains a restart_credentials
descriptor field for keys (the tenant id) that are restart-relevant but
not required for readiness, since folding the tenant into `credentials`
would wrongly report multi-tenant Teams as un-startable.

Diff semantics, built up across review rounds and pinned by tests:
- A removed key is popped from os.environ only when the current value
  still equals what .env last propagated, so an inherited shell/systemd
  value a removal never set is left alone.
- The overwrite warning fires only on a genuinely foreign value
  collision, not on every routine rotation.
- The watcher's diff baseline is seeded from the raw .env map the
  first boot-time load_credentials() actually read (recorded once,
  consumed once), not a later disk read, so a credential rotated in
  the boot window is still diffed and applied instead of silently
  adopted as the new baseline.
- The fingerprint and baseline only advance after an apply succeeds;
  a failed apply (e.g. a malformed `=value` line in the same write as
  a real rotation) leaves both untouched so the next tick retries the
  whole diff, and the apply validates every key before mutating
  anything so a batch is atomic.
- Every post-boot credential read (channel reconnect, readiness badge,
  jira/doctor/upload-destination readers) now calls
  load_credentials(propagate=False), so a worker-thread read can no
  longer reseed a credential the live watcher just removed. The
  dashboard's own credential writer routes through the same
  apply_env_credential_changes instead of hand-rolling os.environ
  set/pop, so it inherits the Docker-scrub skip and PATH carve-out.
- A non-BOM decode error on .env is treated as non-definitive (warned
  once, retried) instead of wedging the watcher permanently.
- Teams: a credential removal closes the live client but its inbound
  webhook route stays registered, so TeamsClient now re-checks
  "closed" after the processing awaits (not just at entry) and 503s
  once closed; closing clears the bound activity handler.

Adds loader helpers (env_fingerprint, read_env_credentials_raw,
changed_env_keys, apply_env_credential_changes,
record_boot_raw_env/take_boot_raw_env) and
registry.changed_credential_keys (case-insensitive on Windows), plus
tests for the loader helpers, the watcher's .env tracking and boot-
window baseline, the credential-driven channel restart, and the
Teams webhook-after-close race.

Later review rounds, folded into this commit:
- A .env PATH line is expanded and validated off the event loop
  (ConfigWatch._prepare_path_additions -> env.prepare_env_path_additions,
  run via asyncio.to_thread) and handed to the applier as path_additions,
  so a ~otheruser entry's pwd.getpwnam / SAM lookup never blocks the loop.
  os.path.expanduser semantics are unchanged.
- The applier decides per os.environ ENTRY, not per .env spelling: on
  Windows (case-insensitive os.environ) all spellings of a key are grouped
  and resolved once, to the first non-empty spelling in .env order (boot's
  setdefault precedence), so renames, partial duplicate removals and
  both-spellings edits are no longer order-dependent.
- Ownership is recorded only when a write takes the entry over (new key,
  rotation, overwrite of a foreign value). A line that merely matches an
  inherited service/shell value is not owned, so removing it keeps the
  inherited credential.
- Teams: the webhook handler (state.teams_on_activity) is bound only once
  a client is the accepted handle (after boot's start_channels, and after
  a restart passes its generation check), so a restart superseded
  mid-connect never exposes its handler.
- Slack: the restart-needed notice matches credential keys by canonical
  entry name, like registry.changed_credential_keys.
- The watcher's diff (changed_env_keys) also compares each entry's
  effective value, so a Windows save that only reorders two spellings with
  different values is applied rather than adopted as the new baseline.
- The Weixin QR sign-in writes its token through apply_env_credential_changes
  like the dashboard channel writer, so it records .env ownership (a later
  removal revokes it in-process) and keeps the Docker scrub guard.
- The Weixin QR sign-in's .env + config.json commit runs under live.hold()
  (like every sibling channel saver) and through drained_to_thread, so the
  watcher never restarts Weixin between the two writes and a cancelled
  request never releases the hold mid-write.
- The boot .env record is tied to the file it was read from; the watcher
  adopts it only for the same .env. The root test conftest resets the boot
  record and the ownership set around every test.
@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

Nothing to check. The change is backend only, with no website/ files, and the only new user-facing text is a log line telling operators to run kirocrew restart after a Slack token change.

[UX-REVIEWED] 5e779ea

Description read

[DESCRIPTION-READ] 6a51684f8d29645ae9e3ce5dc9aa961a17fc79e43df01896503e7ad134634544

That sha256 names everything this verdict read: the PR description, plus the 4 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

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

No design-level concerns: .env is reconciled in the poll cycle that already reloads config.json, and nothing is removed.

Notes

  • The Windows case-spelling grouping is one of the larger parts of the change, but the head commit is the only part of the diff that names it, and the 8,000-byte description cut off before any ## Backwards compatibility section. Stating both in the description's opening would make the review surface clearer.
  • loader_credentials.py takes on about 650 new lines here: ownership tracking, the re-exec marker, the boot record and the applier. A sibling module such as loader_env_live.py would keep the boot-time .env reader separate from the live reconciler before the 1,600-line split rule forces it.

[DESIGN-REVIEWED] 5e779ea

Description read

[DESCRIPTION-READ] cd94ea0cd50eb1254834ff8f50d59ee4598be6e320916b4e96c6ca87b2fba648

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) — 🔴 BLOCK

Premise-level review of 5e779ea66eff66fcc1cf2aa659a03b4f9878dc28 — 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: BLOCK

The .env ownership hand-off across re-exec adds a second pre-exec hook beside keep_for_reexec, which already passes a value to the exec successor only.

Notes

  • Item 3 — one consumer, generalized: restart_credentials: tuple[str, ...] = () on ChannelDescriptor has one user, channels.py:113 (Teams tenant). Grepped restart_credentials: 1 constructed value.

What this change ships

Inventory (10 items) — 8 justified

Intent: make an operator's .env edit (for example a rotated channel token) take effect on a running gateway without a full restart. ADDITION framed as a FIX.

  1. A hand edit to .env now reaches the running gateway and restarts the affected channel — justified
  2. A Slack token change logs a "run kirocrew restart" notice — justified
  3. A Teams tenant-only edit restarts Teams through a new descriptor field — one consumer, generalized
  4. A closed Teams client answers 503; the webhook handler is bound only after connect succeeds — justified
  5. The dashboard and Weixin credential writers go through the shared applier — justified
  6. The Weixin QR save runs under live.hold() — justified
  7. Credential reads after boot no longer write to os.environ — justified
  8. .env ownership survives an in-app restart via _KIROCREW_ENV_OWNED_KEYS — duplicate of platform_compat_runtime.keep_for_reexec
  9. Windows case-variant .env keys are resolved as one entry — justified
  10. A .env PATH line is expanded off the event loop — justified

Blockers

Second spelling of the exec-successor hand-off — duplicate of src/kiro_crew/platform_compat_runtime.py keep_for_reexec
Trigger: reexec_launcher now runs _carry_env_ownership_across_reexec() on the line right before os.environ.update(_KEPT_FOR_REEXEC) (lines 166–167), and reexec_python_module does the same. _KEPT_FOR_REEXEC's docstring describes this job: "Variables … that its OWN exec successor must see again."
Outcome: two mechanisms for passing values to the exec successor, kept in step across both re-exec functions. platform_compat_runtime also gains an import of config.loader that runs at exec time.
Subtraction: delete _carry_env_ownership_across_reexec and its two calls. Make the ownership-record mutators call keep_for_reexec(_ENV_OWNED_KEYS_REEXEC_MARKER, ",".join(sorted(owned))).
Clears when: the re-exec functions carry the ownership marker only through _KEPT_FOR_REEXEC.

[FIRST-PRINCIPLES-REVIEWED] 5e779ea

Description read

[DESCRIPTION-READ] 59ffa95772ce62af959a09289f8e350ac2fcf6a517b01e2a1556e3cf40517491

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

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 5e779ea

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

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 5e779ea

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

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

@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: checking Automated validation is still running labels Oct 23, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD (policy-sensitive) at 609fb58.

This PR changes how credentials reach and leave the gateway's process environment. It adds a live .env applier that sets and pops credential values in os.environ, a record of which keys .env owns, a marker carried across in-app re-exec, the Docker scrub carve-out, and a change to when the Teams webhook accepts requests. The owner reserves credential and network-admission changes for a human reviewer, and the repository's own Sensitive Change Review check is still queued.

In the parts I read, I found no definite defect. The applier validates the whole diff before writing, pops only keys .env itself set, and treats an unreadable .env as unknown rather than as every key cleared. All AI lanes pass. Two advisory notes from First Principles and Design are open: the one-use restart_credentials field, and the undescribed _KIROCREW_ENV_OWNED_KEYS re-exec marker. The description should at least explain the marker.

What clears it: a maintainer reviews the credential and Teams changes and Sensitive Change Review completes.

— crew-pr-reviewer (r123)

@RohanK6

RohanK6 commented Oct 24, 2026

Copy link
Copy Markdown
Contributor Author

Disposition at 609fb58fbc: description updated, advisory notes answered, human review still needed

Thanks for the read. This comment covers what I could address without a new commit. It does not clear the hold: the credential and Teams admission changes still need a maintainer's review, and Sensitive Change Review is still waiting for a runner.

What this does to credentials and Teams admission, in plain words

  • Credentials. When an operator edits $KIROCREW_HOME/.env on a running gateway, the config watcher (the same poll that already reloads config.json) reads the file off the event loop, diffs it against the last state it applied, and sets or removes the changed keys in the gateway's own os.environ. A channel whose credential changed is restarted; Slack, which has no in-process restart, logs a "run kirocrew restart" notice. Already-running children keep their environment until they respawn. Under _KIROCREW_CREDS_SCRUBBED (the Docker entrypoint), credential keys are not written back into os.environ, the same carve-out boot makes. The dashboard channel writer and the Weixin QR sign-in now go through the same applier instead of writing os.environ themselves.
  • Teams admission. The inbound webhook route is pre-registered and outlives the client, so its late-bound handler is now bound only once a Teams client is the accepted handle (after boot's channel start, or after a restart passes its generation check), and it is cleared when that client closes. A closed client also answers 503 to a request that reached it before the clear. Until a client is accepted, the route answers 503.

The safety properties you named, as the code does them

  • The whole diff is validated before anything is written. apply_env_credential_changes checks every key it would write (a legal name, no NUL in the value) and raises before the first mutation, so a malformed line never leaves a half-applied batch. The watcher then advances neither its baseline nor its fingerprint, and retries on the next tick.
  • Only keys .env itself set are removed. On the watcher path, removing a line pops the entry only when the ownership record says .env wrote it, either at boot (setdefault found the name absent) or through a later live write that actually changed the entry. A value inherited from the service or shell, including one that merely equals the .env line, is left in place. One stated exception: the dashboard writer has no baseline, so it removes a key its own save cleared, which is what that path already did before this PR.
  • An unreadable .env means unknown, not every key cleared. A file that can't be read or decoded (UTF-16/UTF-32, an invalid byte) is a non-definitive read: nothing is diffed or applied, and the fingerprint is not advanced, so the next tick reads the file again.

Advisory notes

  • Design and First Principles, the undescribed _KIROCREW_ENV_OWNED_KEYS marker. The description now explains it in "What changed". In short: os.execv keeps os.environ but resets Python state, so the ownership record is written as key names (no values) into that one variable right before an in-app restart's exec. The successor's first load_credentials(propagate=True) deletes it from os.environ and restores the record. On Design's concern about children seeing it: in run_gateway that load runs before the orchestrator is built, and nothing earlier in that function spawns a process. The only exec callers are the gateway's update/restart paths, and a failed exec there exits the process. If writing the marker fails, the restart still proceeds; the restarted gateway then treats those keys as inherited, which is the safe direction. First Principles' alternative of deferring the marker to its own change is reasonable. Without it, a key that .env set before an in-app restart is never popped by a later .env removal until the next full restart. I'd keep it here, but it can be split out if a reviewer prefers.
  • First Principles, the one-use restart_credentials field. It has one user today: the Teams tenant. It is a separate field rather than another entry in credentials because channel_readiness reports any absent credentials key as missing, and an unset tenant is the supported multi-tenant mode, so folding it in would show a working multi-tenant Teams as unconfigured. The suggested subtraction (matching CRED_MICROSOFT_APP_TENANT_ID inside the restart matcher's Teams case) would also work. It trades one data field on the descriptor for a channel-specific branch in the generic matcher. I haven't made that change, since it would need a new commit.

Still needed

A maintainer review of the credential handling and the Teams admission change, and Sensitive Change Review completing. This comment is context for that review, not a substitute for it.

@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 24, 2026
On Windows os.environ is case-insensitive, so slack_bot_token and
SLACK_BOT_TOKEN are one entry. The dashboard channel writer and the
WeChat sign-in writer matched .env lines by literal spelling, so a
hand-typed lowercase line stayed in place and the new uppercase line
was appended after it. Boot and the watcher take the first non-empty
spelling, so the old token came back while the save reported success.

Both writers now match by the loader's canonical entry name
(_env_name_key): the first spelling is rewritten under the declared
name and the rest are dropped; a clear removes every spelling, and
the rollback read returns the spelling boot actually propagates.
POSIX stays case-sensitive, so nothing changes there.

Refs #22450
@RohanK6

RohanK6 commented Oct 24, 2026

Copy link
Copy Markdown
Contributor Author

Superseded by #23836.

@RohanK6 RohanK6 closed this Oct 24, 2026
RohanK6 added a commit that referenced this pull request Oct 24, 2026
…22450)

Edits to $KIROCREW_HOME/.env took effect only after a full gateway
restart: the live config watcher fingerprinted config.json only. The
watcher now reconciles .env in the same poll cycle, applies the diff to
os.environ through one applier (honouring the Docker credentials scrub
and the PATH carve-out), pops only keys .env itself owns, and restarts
only the channel whose credential changed. Slack, which has no
in-process restart, logs a "run kirocrew restart" notice.

The .env ownership record is carried across an in-app re-exec through
the existing keep_for_reexec channel, so a post-restart .env removal
still pops what .env owned. The dashboard channel writer and the Weixin
sign-in writer match .env lines by canonical os.environ entry name, so
on Windows a lowercase spelling of a saved key cannot keep an old token
in force. POSIX stays case-sensitive.

Supersedes #23569.

Fixes #22450
RohanK6 added a commit that referenced this pull request Oct 24, 2026
…22450)

Edits to $KIROCREW_HOME/.env took effect only after a full gateway
restart: the live config watcher fingerprinted config.json only. The
watcher now reconciles .env in the same poll cycle, applies the diff to
os.environ through one applier (honouring the Docker credentials scrub
and the PATH carve-out), pops only keys .env itself owns, and restarts
only the channel whose credential changed. Slack, which has no
in-process restart, logs a "run kirocrew restart" notice.

The .env ownership record is carried across an in-app re-exec through
the existing keep_for_reexec channel, so a post-restart .env removal
still pops what .env owned. The dashboard channel writer and the Weixin
sign-in writer match .env lines by canonical os.environ entry name, so
on Windows a lowercase spelling of a saved key cannot keep an old token
in force. POSIX stays case-sensitive.

Supersedes #23569.

Fixes #22450
RohanK6 added a commit that referenced this pull request Oct 25, 2026
…22450)

Edits to $KIROCREW_HOME/.env took effect only after a full gateway
restart: the live config watcher fingerprinted config.json only. The
watcher now reconciles .env in the same poll cycle, applies the diff to
os.environ through one applier (honouring the Docker credentials scrub
and the PATH carve-out), pops only keys .env itself owns, and restarts
only the channel whose credential changed. Slack, which has no
in-process restart, logs a "run kirocrew restart" notice.

The .env ownership record is carried across an in-app re-exec through
the existing keep_for_reexec channel, so a post-restart .env removal
still pops what .env owned. The dashboard channel writer and the Weixin
sign-in writer match .env lines by canonical os.environ entry name, so
on Windows a lowercase spelling of a saved key cannot keep an old token
in force. POSIX stays case-sensitive.

Supersedes #23569.

Fixes #22450
RohanK6 added a commit that referenced this pull request Oct 25, 2026
…22450)

Edits to $KIROCREW_HOME/.env took effect only after a full gateway
restart: the live config watcher fingerprinted config.json only. The
watcher now reconciles .env in the same poll cycle, applies the diff to
os.environ through one applier (honouring the Docker credentials scrub
and the PATH carve-out), pops only keys .env itself owns, and restarts
only the channel whose credential changed. Slack, which has no
in-process restart, logs a "run kirocrew restart" notice.

The .env ownership record is carried across an in-app re-exec through
the existing keep_for_reexec channel, so a post-restart .env removal
still pops what .env owned. The dashboard channel writer and the Weixin
sign-in writer match .env lines by canonical os.environ entry name, so
on Windows a lowercase spelling of a saved key cannot keep an old token
in force. POSIX stays case-sensitive.

Supersedes #23569.

Fixes #22450
RohanK6 added a commit that referenced this pull request Oct 25, 2026
…22450)

Edits to $KIROCREW_HOME/.env took effect only after a full gateway
restart: the live config watcher fingerprinted config.json only. The
watcher now reconciles .env in the same poll cycle, applies the diff to
os.environ through one applier (honouring the Docker credentials scrub
and the PATH carve-out), pops only keys .env itself owns, and restarts
only the channel whose credential changed. Slack, which has no
in-process restart, logs a "run kirocrew restart" notice.

The .env ownership record is carried across an in-app re-exec through
the existing keep_for_reexec channel, so a post-restart .env removal
still pops what .env owned. The dashboard channel writer and the Weixin
sign-in writer match .env lines by canonical os.environ entry name, so
on Windows a lowercase spelling of a saved key cannot keep an old token
in force. POSIX stays case-sensitive.

Supersedes #23569.

Fixes #22450
RohanK6 added a commit that referenced this pull request Oct 25, 2026
…22450)

Edits to $KIROCREW_HOME/.env took effect only after a full gateway
restart: the live config watcher fingerprinted config.json only. The
watcher now reconciles .env in the same poll cycle, applies the diff to
os.environ through one applier (honouring the Docker credentials scrub
and the PATH carve-out), pops only keys .env itself owns, and restarts
only the channel whose credential changed. Slack, which has no
in-process restart, logs a "run kirocrew restart" notice.

The .env ownership record is carried across an in-app re-exec through
the existing keep_for_reexec channel, so a post-restart .env removal
still pops what .env owned. The dashboard channel writer and the Weixin
sign-in writer match .env lines by canonical os.environ entry name, so
on Windows a lowercase spelling of a saved key cannot keep an old token
in force. POSIX stays case-sensitive.

Supersedes #23569.

Fixes #22450
RohanK6 added a commit that referenced this pull request Oct 25, 2026
…22450)

Edits to $KIROCREW_HOME/.env took effect only after a full gateway
restart: the live config watcher fingerprinted config.json only. The
watcher now reconciles .env in the same poll cycle, applies the diff to
os.environ through one applier (honouring the Docker credentials scrub
and the PATH carve-out), pops only keys .env itself owns, and restarts
only the channel whose credential changed. Slack, which has no
in-process restart, logs a "run kirocrew restart" notice.

The .env ownership record is carried across an in-app re-exec through
the existing keep_for_reexec channel, so a post-restart .env removal
still pops what .env owned. The dashboard channel writer and the Weixin
sign-in writer match .env lines by canonical os.environ entry name, so
on Windows a lowercase spelling of a saved key cannot keep an old token
in force. POSIX stays case-sensitive.

Supersedes #23569.

Fixes #22450
RohanK6 added a commit that referenced this pull request Oct 25, 2026
…22450)

Edits to $KIROCREW_HOME/.env took effect only after a full gateway
restart: the live config watcher fingerprinted config.json only. The
watcher now reconciles .env in the same poll cycle, applies the diff to
os.environ through one applier (honouring the Docker credentials scrub
and the PATH carve-out), pops only keys .env itself owns, and restarts
only the channel whose credential changed. Slack, which has no
in-process restart, logs a "run kirocrew restart" notice.

The .env ownership record is carried across an in-app re-exec through
the existing keep_for_reexec channel, so a post-restart .env removal
still pops what .env owned. The dashboard channel writer and the Weixin
sign-in writer match .env lines by canonical os.environ entry name, so
on Windows a lowercase spelling of a saved key cannot keep an old token
in force. POSIX stays case-sensitive.

Supersedes #23569.

Fixes #22450
RohanK6 added a commit that referenced this pull request Oct 25, 2026
…22450)

Edits to $KIROCREW_HOME/.env took effect only after a full gateway
restart: the live config watcher fingerprinted config.json only. The
watcher now reconciles .env in the same poll cycle, applies the diff to
os.environ through one applier (honouring the Docker credentials scrub
and the PATH carve-out), pops only keys .env itself owns, and restarts
only the channel whose credential changed. Slack, which has no
in-process restart, logs a "run kirocrew restart" notice.

The .env ownership record is carried across an in-app re-exec through
the existing keep_for_reexec channel, so a post-restart .env removal
still pops what .env owned. The dashboard channel writer and the Weixin
sign-in writer match .env lines by canonical os.environ entry name, so
on Windows a lowercase spelling of a saved key cannot keep an old token
in force. POSIX stays case-sensitive.

Supersedes #23569.

Fixes #22450
RohanK6 added a commit that referenced this pull request Oct 28, 2026
…22450)

Edits to $KIROCREW_HOME/.env took effect only after a full gateway
restart: the live config watcher fingerprinted config.json only. The
watcher now reconciles .env in the same poll cycle, applies the diff to
os.environ through one applier (honouring the Docker credentials scrub
and the PATH carve-out), pops only keys .env itself owns, and restarts
only the channel whose credential changed. Slack, which has no
in-process restart, logs a "run kirocrew restart" notice.

The .env ownership record is carried across an in-app re-exec through
the existing keep_for_reexec channel, so a post-restart .env removal
still pops what .env owned. The dashboard channel writer and the Weixin
sign-in writer match .env lines by canonical os.environ entry name, so
on Windows a lowercase spelling of a saved key cannot keep an old token
in force. POSIX stays case-sensitive.

Supersedes #23569.

Fixes #22450
iamwhatever pushed a commit that referenced this pull request Oct 29, 2026
…22450) (#23836)

Edits to $KIROCREW_HOME/.env took effect only after a full gateway
restart: the live config watcher fingerprinted config.json only. The
watcher now reconciles .env in the same poll cycle, applies the diff to
os.environ through one applier (honouring the Docker credentials scrub
and the PATH carve-out), pops only keys .env itself owns, and restarts
only the channel whose credential changed. Slack, which has no
in-process restart, logs a "run kirocrew restart" notice.

The .env ownership record is carried across an in-app re-exec through
the existing keep_for_reexec channel, so a post-restart .env removal
still pops what .env owned. The dashboard channel writer and the Weixin
sign-in writer match .env lines by canonical os.environ entry name, so
on Windows a lowercase spelling of a saved key cannot keep an old token
in force. POSIX stays case-sensitive.

Supersedes #23569.

Fixes #22450
@bolichen97
bolichen97 deleted the env-hotreload-22450-v4 branch November 6, 2026 07:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

.env changes require a full gateway restart (no hot-reload)

2 participants