boxdown 1.2.0 → 1.3.0

package/docs/features/commit-signing.md

@@ -8,10 +8,23 @@ If the agent is unavailable, has no identities, or has multiple identities
 that Boxdown cannot distinguish, Boxdown warns and configures unsigned commits.
 It never guesses a key and does not block setup or commits.
 
+Signing readiness is resolved when generated devcontainer configuration is
+written. A container created while readiness is unavailable does not gain an
+SSH-agent mount later; recreate it after correcting the warning:
+
+```bash
+boxdown setup --workspace /path/to/project --recreate
+```
+
 The container can request operations from identities exposed by the forwarded
 agent. Use a dedicated signing identity or an agent that confirms sensitive
 operations when that exposure is unacceptable.
 
+On Docker Desktop, Boxdown places a small root-owned relay between the
+host-facing agent socket and the non-root container user. The relay exposes no
+private-key material and lets normal `node`-user Git commits reach the host
+agent.
+
 GitHub verification is separate from signing. Upload the selected public key as
 a GitHub SSH signing key once to receive the Verified badge:
 
@@ -21,3 +34,61 @@ gh ssh-key add /path/to/signing-key.pub --type signing --title "Boxdown commit s
 
 The same key may already be registered for GitHub SSH authentication; GitHub
 requires a second registration with type `signing`.
+
+## Optional: configure SSH signing on the host
+
+Boxdown can sign commits without changing the host Git configuration. The
+container uses the selected identity from the host SSH agent directly. Configure
+the host as well when you also make commits outside Boxdown, or when you want
+to make the selected Boxdown identity explicit.
+
+First, verify the intended identity is loaded in the SSH agent. `ssh-add -l`
+prints loaded key fingerprints:
+
+```bash
+ssh-add -l
+```
+
+Then configure Git to use that public key for SSH signing:
+
+```bash
+git config --global gpg.format ssh
+git config --global user.signingkey ~/.ssh/id_ed25519.pub
+git config --global --unset-all gpg.program || true
+git config --global commit.gpgsign true
+```
+
+Replace `~/.ssh/id_ed25519.pub` with the selected public key when you use a
+different identity. The public key must also be registered with GitHub as a
+Signing key for pushed commits to display the Verified badge.
+
+Boxdown accepts `user.signingkey` as an inline SSH public key, a `key::` public
+key, an absolute path, a `~/` path, or a path relative to the workspace. Only
+public-key files are read. An explicitly configured key is authoritative: if
+it is unreadable, invalid, or absent from the SSH agent, Boxdown disables
+signing instead of selecting another identity.
+
+## User configuration precedence
+
+Boxdown defaults to SSH signing only when Git has no explicit signing
+preference. A repository-local `commit.gpgsign=false`, a non-SSH `gpg.format`,
+or an explicit `gpg.program` is preserved. Explicit SSH signing remains
+supported; Boxdown maps an inaccessible host public-key path to the selected
+public-key snapshot inside the container. This policy is intentional and may
+be revisited in a future release if Boxdown becomes authoritative.
+
+Git can require `gpg.ssh.allowedSignersFile` for trust-aware local verification
+such as `git log --show-signature`. It is not required to create SSH signatures
+or for GitHub to verify a commit.
+
+## Troubleshooting
+
+Signing failures remain non-blocking. User-facing lifecycle commands print a
+concise reason, while the workspace `boxdown.log` records a stable reason code
+and sanitized diagnostic detail. Container validation further distinguishes a
+missing mounted public key, an unavailable forwarded agent, a selected key that
+is not loaded, and a failed disposable signed-commit probe.
+
+Run `boxdown doctor --workspace /path/to/project` to recheck host identity
+selection and GitHub signing-key registration. After fixing the reported
+condition, use `--recreate`; existing unsigned commits are not rewritten.

package/docs/features/generated-config-and-state.md

@@ -62,6 +62,19 @@ entries with best-effort Docker state.
 Metadata may also record the last inspected Docker image ID for the workspace so
 `boxdown purge` can remove that exact image even after the container is gone.
 
+## Runtime Secret State
+
+`ANTHROPIC_API_KEY`, `SNYK_TOKEN`, and the optional 1Password service-account
+token are written to owner-only files in a per-workspace runtime directory,
+separate from persistent workspace data. Boxdown mounts that directory
+read-only at `/run/boxdown/secrets`; only non-secret mount and Bash-bootstrap
+paths appear in generated Docker configuration.
+
+Bash sessions load available files as ordinary environment variables. Missing
+host values and failed 1Password lookup are non-blocking. `boxdown down` and
+`boxdown purge` remove the workspace runtime directory after container removal.
+Boxdown does not use or modify project `.env.development` files.
+
 ## External App Config
 
 External app integration config is not Boxdown workspace state. Boxdown writes
@@ -104,14 +117,16 @@ Boxdown starts from `assets/devcontainer/devcontainer.json` and rewrites:
 - `postCreateCommand`, to call mounted container assets.
 - `postStartCommand`, to call mounted container assets.
 - `mounts`, to add the read-only asset mount, public-key mount, host Git config
-  snapshot mount, host `~/.agents` mount when that directory exists, and host
-  `~/.codex/auth.json` read-only mount when that file exists.
+  snapshot mount, runtime secret mount, host `~/.agents` mount when that
+  directory exists, and host `~/.codex/auth.json` read-only mount when that
+  file exists.
 - `containerEnv`, to point SSH bootstrap at the mounted public key and actual
   container workspace.
 
 The target repository is still the Dev Container workspace via
 `--workspace-folder`.
 
-Mounts are create-time container settings. Use `boxdown start --recreate` after
-creating or removing host `~/.agents` or `~/.codex/auth.json` so Docker
+Mounts are create-time container settings. Existing containers created before
+runtime-mounted secrets require `boxdown start --recreate`. The same applies
+after creating or removing host `~/.agents` or `~/.codex/auth.json` so Docker
 receives the updated mount set.

package/docs/features/github-auth-refresh.md

@@ -72,5 +72,6 @@ signing programs that are unavailable inside Linux.
 If host `gh` is missing, logged out, or cannot return a token, the refresh is a
 no-op.
 
-`OP_SERVICE_ACCOUNT_TOKEN`, when present, is a 1Password service account token.
-It is not a GitHub token and is not used by `gh` or GitHub Git operations.
+`OP_SERVICE_ACCOUNT_TOKEN`, when available through Boxdown's runtime secret
+mount, is a 1Password service account token. It is not a GitHub token and is
+not used by `gh` or GitHub Git operations.

package/docs/features/lifecycle.md

@@ -129,6 +129,19 @@ do not prompt so existing targeted scripts keep working. Non-interactive
 `purge` from an untracked directory fails safely instead of treating the current
 directory as a workspace.
 
+## Container runtime readiness
+
+Commands that may create or start a devcontainer wait for Docker before writing
+workspace metadata. Docker daemon and Buildx builder startup races are retried
+for up to 60 seconds; the underlying `devcontainer up` command is still run only
+once after readiness succeeds.
+
+For a daemon timeout, run `docker info`. For a Buildx timeout, run
+`docker buildx inspect`. Logged lifecycle errors also print the workspace
+command-log path, which contains full redacted stdout and stderr. A generic Dev
+Containers JSON error without nested output means the command log is the next
+place to inspect.
+
 ## Doctor
 
 `doctor` validates required host prerequisites: Node, Docker CLI, Docker
@@ -148,3 +161,9 @@ starts Docker. Required failures stop setup; warnings remain non-blocking.
 
 GitHub CLI auth is optional. Missing or unauthenticated `gh` is reported as a
 warning rather than a failure.
+
+Doctor uses the same SSH signing identity precedence as environment creation.
+It honors an explicit `user.signingkey` public-key value or path, can select a
+single GitHub authentication-key match from multiple loaded identities, and
+checks the selected key's GitHub signing registration when available. Signing
+readiness warnings never fail setup.

package/docs/features/setup.md

@@ -20,6 +20,11 @@ interactive shell. It accepts:
 --verbose
 ```
 
+Setup readiness runs before prompts or workspace state is written. A missing
+Docker CLI fails immediately; a starting Docker daemon or discoverable Buildx
+builder is polled once per second for up to 60 seconds. If this preflight fails,
+setup leaves no workspace metadata, generated devcontainer config, or SSH key.
+
 ## Flow
 
 1. Resolve the workspace to a real absolute path.

package/docs/features/start-and-shell.md

@@ -21,6 +21,11 @@ boxdown antigravity
 Use `boxdown setup` when you want to prepare the devcontainer and SSH/app
 integration without opening an interactive shell.
 
+Start does not require a completed setup. It performs a fresh runtime-readiness
+check, then writes workspace inventory metadata and creates the generated state
+needed for the devcontainer. It does not install the setup-only SSH alias or
+external application integrations.
+
 `boxdown shell` remains supported as an alias for `boxdown start`, but `start`
 is the canonical command used in help and documentation.
 `boxdown cc` remains supported as an alias for `boxdown claude`, but `claude`
@@ -98,6 +103,11 @@ BOXDOWN_TTY_NORMALIZE=0 boxdown start
 Use it when changing create-time settings such as image, features, mounts, or
 Docker `runArgs`.
 
+Existing containers created before Boxdown adopted runtime-mounted secrets
+must be recreated once. After recreation, Boxdown-provided secrets remain
+ordinary Bash-session environment variables but are absent from Docker
+container configuration and `docker inspect`.
+
 ## Port Hint
 
 The v1 asset config publishes container port `3000` with a dynamic host port.

package/docs/superpowers/plans/2026-07-17-node-ssh-agent-proxy-signing.md

@@ -0,0 +1,132 @@
+# Node SSH-Agent Proxy Signing Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Enable best-effort SSH commit signing for the non-root Boxdown user while preserving explicit user Git-signing preferences.
+
+**Architecture:** A root Node proxy forwards the raw mounted agent socket to a node-owned socket. The post-create hook starts and verifies that proxy before signing bootstrap. The bootstrap applies Boxdown's SSH default only when neither global nor local Git configuration expresses a signing preference.
+
+**Tech Stack:** TypeScript, Node `net` Unix sockets, Bash lifecycle hooks, Node test runner.
+
+## Global Constraints
+
+- Do not read, copy, mount, or log private keys.
+- Signing and proxy failures must never block lifecycle commands or commits.
+- Preserve explicit user `commit.gpgsign`, `gpg.format`, `user.signingkey`, and `gpg.program` settings.
+- Existing containers require `--recreate`.
+
+---
+
+### Task 1: Add the node-accessible SSH-agent proxy
+
+**Files:**
+
+- Create: `assets/devcontainer/utils/ssh-agent-proxy.mjs`
+- Modify: `assets/devcontainer/hooks/post-create.sh`
+- Test: `__tests__/app.test.ts`
+
+- [ ] **Step 1: Write a failing proxy forwarding test**
+
+Create a temporary raw Unix server, launch the proxy with a temporary target
+socket and the current test user's UID/GID, send bytes through the target, and
+assert the raw server receives and echoes them.
+
+- [ ] **Step 2: Run the focused test to verify it fails**
+
+Run: `fnm exec --using v24.15.0 -- node --import tsx --test --test-name-pattern='forwards node SSH-agent connections' __tests__/app.test.ts`
+
+Expected: FAIL because the proxy asset does not exist.
+
+- [ ] **Step 3: Implement the proxy and lifecycle startup helper**
+
+Implement a Node `net.createServer()` bridge that unlinks stale target sockets,
+listens with mode `0600`, changes ownership to the supplied UID/GID, and pipes
+each client to the raw socket. Start it with `sudo` in post-create, wait for
+the target socket, and run `ssh-add -L` through it before signing bootstrap.
+
+- [ ] **Step 4: Run the focused test to verify it passes**
+
+Run the Task 1 command. Expected: PASS.
+
+### Task 2: Route generated configuration and diagnostics through the proxy
+
+**Files:**
+
+- Modify: `src/config.ts`
+- Modify: `assets/devcontainer/utils/git-signing-bootstrap.sh`
+- Test: `__tests__/app.test.ts`
+
+- [ ] **Step 1: Write failing generated-config and hook tests**
+
+Assert enabled plans set `SSH_AUTH_SOCK` to `/run/boxdown/ssh-agent-node.sock`,
+retain the raw source only in `BOXDOWN_GIT_SIGNING_SOURCE_SOCKET`, and disable
+signing with `container-agent-proxy-unavailable` when proxy readiness fails.
+
+- [ ] **Step 2: Run the focused tests to verify they fail**
+
+Run: `fnm exec --using v24.15.0 -- node --import tsx --test --test-name-pattern='node SSH-agent proxy|proxy-unavailable' __tests__/app.test.ts`
+
+Expected: FAIL because generated configuration still exposes the raw socket.
+
+- [ ] **Step 3: Implement proxy socket configuration and failure reporting**
+
+Add constants or literal paths for raw and node-facing sockets, update generated
+container environment, and teach the bootstrap to report the proxy reason
+without replacing user configuration.
+
+- [ ] **Step 4: Run the focused tests to verify they pass**
+
+Run the Task 2 command. Expected: PASS.
+
+### Task 3: Preserve explicit user signing configuration
+
+**Files:**
+
+- Modify: `assets/devcontainer/utils/git-signing-bootstrap.sh`
+- Modify: `docs/features/commit-signing.md`
+- Modify: `docs/superpowers/specs/2026-07-11-default-commit-signing-design.md`
+- Test: `__tests__/app.test.ts`
+
+- [ ] **Step 1: Write failing bootstrap tests**
+
+Add separate tests for repository-local `commit.gpgsign=false`, global
+non-SSH `gpg.format`, and an explicit SSH signing key. Assert the first two
+remain unchanged; assert the SSH case maps only its public-key path to the
+mounted snapshot and signs successfully.
+
+- [ ] **Step 2: Run the focused tests to verify they fail**
+
+Run: `fnm exec --using v24.15.0 -- node --import tsx --test --test-name-pattern='preserves explicit.*signing' __tests__/app.test.ts`
+
+Expected: FAIL because the bootstrap currently overwrites global SSH settings.
+
+- [ ] **Step 3: Implement explicit-preference detection**
+
+Check local configuration first, then copied global configuration. Preserve an
+explicit opt-out or non-SSH configuration; use Boxdown defaults only with no
+explicit preference. For explicit SSH configuration, replace only an
+unavailable public-key path with the selected mounted key.
+
+- [ ] **Step 4: Run the focused tests to verify they pass**
+
+Run the Task 3 command. Expected: PASS.
+
+### Task 4: Document and verify
+
+**Files:**
+
+- Modify: `docs/features/commit-signing.md`
+- Modify: `docs/superpowers/specs/2026-07-11-default-commit-signing-design.md`
+- Create: `.changeset/<generated-name>.md`
+
+- [ ] **Step 1: Document the proxy, user-precedence policy, and `--recreate` requirement**
+
+- [ ] **Step 2: Add a patch changeset**
+
+- [ ] **Step 3: Run complete verification**
+
+Run: `pnpm test`, `pnpm lint`, `pnpm build`, `bash -n assets/devcontainer/utils/git-signing-bootstrap.sh`, `node --check assets/devcontainer/utils/ssh-agent-proxy.mjs`, and `git diff --check`.
+
+- [ ] **Step 4: Commit**
+
+Use: `git commit -m "fix: proxy SSH agent for commit signing"`

package/docs/superpowers/plans/2026-07-17-runtime-secret-environment.md

@@ -0,0 +1,174 @@
+# Runtime Secret Environment Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Keep Boxdown-provided secrets available in Bash sessions without writing their values to the repository, persistent Boxdown state, Docker environment configuration, or workspace logs.
+
+**Architecture:** A private per-workspace runtime directory holds three secret files and is mounted read-only at `/run/boxdown/secrets`. A Bash bootstrap exports values for interactive, non-interactive, SSH, and Boxdown coding-agent Bash sessions. Docker configuration carries only paths; metadata inspection requests only image fields; logging structurally redacts known assignments.
+
+**Tech Stack:** Node.js 24, TypeScript, Bash, `node:test`, Docker/Dev Containers configuration.
+
+## Global Constraints
+
+- Do not print, log, serialize, or place a secret value in generated configuration, command arguments, metadata, or diagnostics.
+- Fixed Boxdown secret names: `ANTHROPIC_API_KEY`, `SNYK_TOKEN`, and `OP_SERVICE_ACCOUNT_TOKEN`.
+- Missing values and unavailable 1Password access are non-blocking; the affected variable is absent.
+- `.env.development` is project-owned: Boxdown does not create, edit, delete, or migrate it.
+- Runtime secret directories/files use `0700`/`0600` and are outside `workspaceDataDir`.
+- Existing containers require `boxdown start --recreate`; do not add legacy cleanup or `doctor --fix-secrets`.
+
+---
+
+## File Structure
+
+| File | Responsibility |
+| --- | --- |
+| `src/constants.ts`, `src/paths.ts` | Runtime secret paths and fixed secret-name constants. |
+| `src/config.ts`, `assets/devcontainer/devcontainer.json` | Read-only mount and non-secret Bash bootstrap config. |
+| `assets/devcontainer/hooks/initialize.sh` | Atomically create/remove runtime secret files. |
+| `assets/devcontainer/utils/secret-env-bootstrap.sh` | Read fixed files and export present values without output. |
+| `assets/devcontainer/hooks/post-create.sh`, `src/shell.ts` | Source bootstrap for interactive and Boxdown-launched Bash sessions. |
+| `src/main.ts`, `src/purge.ts` | Remove workspace runtime state after down/purge. |
+| `src/devcontainer.ts`, `src/logging.ts` | Narrow Docker inspection and structural redaction. |
+| `src/doctor.ts`, docs, `__tests__/app.test.ts` | Safety checks, documentation, and regression tests. |
+
+### Task 1: Define runtime secret state and remove workspace injection
+
+**Files:**
+
+- Modify: `src/constants.ts`, `src/paths.ts`, `src/config.ts`, `assets/devcontainer/devcontainer.json`, `assets/devcontainer/hooks/initialize.sh`, `assets/devcontainer/hooks/post-start.sh`, `__tests__/app.test.ts`
+
+**Interfaces:**
+
+```ts
+export const BOXDOWN_SECRET_ENV_NAMES = ['ANTHROPIC_API_KEY', 'SNYK_TOKEN', 'OP_SERVICE_ACCOUNT_TOKEN'] as const
+export const BOXDOWN_CONTAINER_SECRET_ENV_DIR = '/run/boxdown/secrets'
+export const BOXDOWN_CONTAINER_SECRET_ENV_BOOTSTRAP = '/opt/boxdown/devcontainer/utils/secret-env-bootstrap.sh'
+export function defaultRuntimeRoot (env?: NodeJS.ProcessEnv): string
+// WorkspaceContext adds runtimeRoot, workspaceRuntimeDir, workspaceSecretEnvDir.
+```
+
+- [ ] **Step 1: Write failing tests**
+
+Create a context with `BOXDOWN_RUNTIME_HOME`. Assert that its secret directory starts below runtime root but not persistent workspace data. Assert generated config mounts that directory read-only at `/run/boxdown/secrets`, sets the non-secret bootstrap `BASH_ENV`, retains `NODE_ENV`, and serializes none of `--env-file`, `.env.development`, or the three secret names.
+
+- [ ] **Step 2: Verify red**
+
+Run `pnpm test -- --test-name-pattern "runtime secret|generated config"`. Expected: FAIL because the current config injects workspace-file and Docker-environment secrets.
+
+- [ ] **Step 3: Implement paths and config**
+
+Add the fixed constants. Resolve runtime root in this order: `BOXDOWN_RUNTIME_HOME`; then `join(XDG_RUNTIME_DIR, PACKAGE_NAME)`; then `join(tmpdir(), package-name plus UID)`. Add workspace-ID scoped runtime/secret paths. Append the read-only secret mount and `BASH_ENV`; remove the base `--env-file` pair and secret `containerEnv` values while preserving non-secret entries.
+
+- [ ] **Step 4: Implement host runtime-file refresh**
+
+Pass only `BOXDOWN_SECRET_ENV_DIR` to `initializeCommand`. Set `umask 077`; create the directory at `0700`; write each nonempty file through `mktemp` plus `chmod 0600` plus atomic rename; remove a file when its host value is absent. Read the existing 1Password reference into a local variable and never echo it. Remove all `.env.development` preparation/upsert logic and post-start deletion.
+
+- [ ] **Step 5: Verify green and commit**
+
+Run `pnpm test -- --test-name-pattern "runtime secret|generated config|devcontainer git config hooks"` and `bash -n assets/devcontainer/hooks/initialize.sh assets/devcontainer/hooks/post-start.sh`; expect both to pass. Commit the listed sources and tests as `feat: mount runtime secret environment`.
+
+### Task 2: Export secret files in supported Bash sessions and clean runtime state
+
+**Files:**
+
+- Create: `assets/devcontainer/utils/secret-env-bootstrap.sh`
+- Modify: `assets/devcontainer/hooks/post-create.sh`, `src/shell.ts`, `src/main.ts`, `src/purge.ts`, `__tests__/app.test.ts`
+
+**Interfaces:**
+
+```bash
+# Bootstrap reads /run/boxdown/secrets/<fixed-name> and exports only present values.
+```
+
+- [ ] **Step 1: Write failing tests**
+
+Run the bootstrap against a temporary secret directory with sentinel values. Assert each present value is exported, an absent file remains unset, and stdout/stderr do not contain a sentinel. Assert interactive shell/agent scripts source the bootstrap before `exec`. Assert down/purge remove only workspace runtime state.
+
+- [ ] **Step 2: Verify red**
+
+Run `pnpm test -- --test-name-pattern "secret bootstrap|runtime secret cleanup|interactive shell setup"`. Expected: FAIL because no bootstrap or runtime cleanup exists.
+
+- [ ] **Step 3: Implement bootstrap/session loading**
+
+Create a no-output script that reads the three fixed files with `IFS= read -r`, exports only nonempty values, and never sources secret file contents as code. Add an idempotent source line to the node user's `.bashrc` in post-create. Add the same bootstrap source before final `exec` in both shell script builders; never add a value to `interactiveShellEnvArgs`.
+
+- [ ] **Step 4: Implement safe runtime cleanup**
+
+Add a path-contained helper that removes only `context.workspaceRuntimeDir`, accepts absence, and never removes `runtimeRoot`. Invoke it after successful down and during purge before persistent state removal.
+
+- [ ] **Step 5: Verify green and commit**
+
+Run `pnpm test -- --test-name-pattern "secret bootstrap|runtime secret cleanup|interactive shell setup"` and `bash -n assets/devcontainer/utils/secret-env-bootstrap.sh assets/devcontainer/hooks/post-create.sh`; expect pass. Commit as `feat: export runtime secrets in Bash sessions`.
+
+### Task 3: Replace full Docker inspection and harden logging
+
+**Files:**
+
+- Modify: `src/devcontainer.ts`, `src/logging.ts`, `__tests__/app.test.ts`
+
+**Interfaces:**
+
+```ts
+export function parseDockerInspectImage (output: string, containerId: string): DockerImageInfo | undefined
+export function redactKnownSecretEnvironmentAssignments (value: string): string
+```
+
+- [ ] **Step 1: Write failing tests**
+
+Test parsing two JSON-string lines representing image ID/name. Add a fake Docker complete-inspect fixture containing an OP sentinel, assert the lifecycle log omits it and inspect uses a narrow format. Test plain and Docker-JSON assignment forms for each known secret variable.
+
+- [ ] **Step 2: Verify red**
+
+Run `pnpm test -- --test-name-pattern "docker inspect|known secret|workspace logger"`. Expected: FAIL because inspect uses `{{json .}}` and logging is value-only.
+
+- [ ] **Step 3: Implement projection/redaction**
+
+Use Docker format `{{json .Image}}` followed by `{{json .Config.Image}}`; parse exactly two scalar JSON lines and provide a container-ID-specific malformed-output error. Redact values after each fixed name before dynamic redactions and apply it through logger `#redact` for arguments, sections, errors, and child output while preserving the names.
+
+- [ ] **Step 4: Verify green and commit**
+
+Run `pnpm test -- --test-name-pattern "docker inspect|known secret|workspace logger"`; expect pass. Commit as `fix: keep container secrets out of workspace logs`.
+
+### Task 4: Doctor coverage and documentation
+
+**Files:**
+
+- Modify: `src/doctor.ts`, `__tests__/app.test.ts`, `assets/devcontainer/README.md`, `docs/features/generated-config-and-state.md`, `docs/features/start-and-shell.md`
+
+- [ ] **Step 1: Write failing tests**
+
+Extend doctor fake-command tests to require a disposable runtime-secret mount probe and a warning when generated config contains env-file, `.env.development`, or a fixed secret name in `containerEnv`. Add existing-style static documentation assertions for session exposure and `--recreate`.
+
+- [ ] **Step 2: Verify red**
+
+Run `pnpm test -- --test-name-pattern "doctor|generated config|runtime secret"`. Expected: FAIL because doctor does not inspect those conditions.
+
+- [ ] **Step 3: Implement non-blocking checks/docs**
+
+Add `workspaceSecretEnvDir` to disposable mount probes. Add a `secret-environment-config` doctor result: missing generated config is warning, unsafe config is warning, safe config is ok; never read secret file contents. Update docs: values are ordinary Bash-session variables but not Docker config; `.env.development` is ignored; missing values are non-blocking; existing containers need recreate; legacy leaked values/logs require manual removal and rotation.
+
+- [ ] **Step 4: Verify green and commit**
+
+Run `pnpm test -- --test-name-pattern "doctor|generated config|runtime secret"`; expect pass. Commit as `docs: describe runtime secret environment handling`.
+
+### Task 5: Full verification
+
+- [ ] **Step 1: Run the complete suite**
+
+Run `pnpm test`, `pnpm lint`, `pnpm build`, `bash -n` for all changed hooks/utilities, `git diff --check`, and `git diff main...HEAD --check`. Expected: every command exits 0.
+
+- [ ] **Step 2: Review secret-safety diff**
+
+Run `git diff main...HEAD -- assets/devcontainer/devcontainer.json src/config.ts src/devcontainer.ts src/logging.ts`. Confirm no implementation path writes `.env.development`, uses `--env-file`, or contains literal token-like values.
+
+- [ ] **Step 3: Commit a verification-only correction when required**
+
+If verification requires a source correction, commit only that correction as `test: cover runtime secret environment regression`.
+
+## Plan Self-Review
+
+- Tasks 1–2 implement runtime-only state and compatible Bash-session exports.
+- Task 3 removes the full-inspect log leak and adds a logging backstop.
+- Task 4 adds doctor/documentation coverage without legacy cleanup.
+- Task 5 runs full test, lint, build, Bash syntax, and diff checks.