ho-04.5 — Runtime injection (sharibako run)

sharibako run [--scope <id>] [--dry-run] [--] <command> [args...] decrypts a scope's secrets into memory, spawns the given command with those values set in its environment, forwards stdio and signals, waits, and exits with the child's status. Nothing is written to disk. This is the second output verb the injection decision (kamae-2.1) committed to — the peer of materialize — and it closes the Class 4 workspace-file-reader exposure for consumers that can be wrapped.

What this ho is, and what it already isn't

The overview framed ho-04.5 as three deliverables — run, clean, and the SECURITY.md draft. Two of the three already exist:

• clean is built. CleanCommand + Materializer.clean(marker:) are complete — owned-line removal, delete-when-empty, --yes gate, no age key required. It rode in with its Materializer-triad siblings (materialize / update / heal) during the ho-03/ho-04 arc. The only unbuilt overview item is clean --all (clean every marker on the machine), which the overview itself deferred as an opt-in flag; it stays deferred.
• SECURITY.md is drafted, and thoroughly. It was written during the injection decision's downstream-update pass (kamae-2.1 lists it in "Reflected in") and already carries the four-class threat model, the materialize-vs-run exposure split, and per-verb sections for run, run --dry-run, and clean.

run is the one piece nothing else needed — a brand-new process-spawning verb no other command's work touches. The overview said as much: its spec was to be authored "after ho-04 lands." So this ho is run alone. clean and SECURITY.md are treated as shipped; the only work against them here is a reconcile-at-close check that the doc's run/--dry-run sections match what actually ships.

The ho-04.4→04.6 lesson (validate rough before hardening; don't over-build a UI) applies only weakly: run has no interactive surface — it is argv passthrough after --. The half that bites is "dogfood the rough version before writing the full test matrix." That's built into the task.

Think

Decision 1 — Child spawn: Foundation.Process

The injection decision described the mechanism as fork() + exec(). In Swift, Foundation.Process is that mechanism with the sharp edges handled: it sets the child's environment, inherits the parent's stdio when the standard handles are left at their defaults, exposes .processIdentifier for signal forwarding, and reports both terminationStatus and terminationReason (.exit vs. .uncaughtSignal) so the wrapper can propagate the child's fate faithfully. No raw posix_spawn. run spawns via Process, inherits stdin/stdout/stderr, sets .environment to the composed dict, and waitUntilExit()s.

Decision 2 — Vault Core addition: secrets(inScope:)

Add one public method to VaultCore (in the encryption extension, beside getValue):

func secrets(inScope scopeID: String) throws -> [String: String]

It loops inspect(scopeID) for the owned keys and calls getValue on each — which already resolves .link files to their shared targets — returning [key: plaintextValue]. This is the injection decision's get_all_secrets, named to match Swift's inspect/getValue neighbors. materialize does this same loop privately (loadVaultValues); run needs it at the CLI boundary, so it graduates to a public method. One age-key unlock (one Touch ID) per invocation covers every key in the scope.

Decision 3 — Environment merge: parent env overlaid, scope wins

The child's environment is ProcessInfo.processInfo.environment with the scope's secrets merged on top — on a key collision, the vault value wins. This matches the injection decision ("scope wins on conflict") and is what a developer expects: sharibako run should make the scope's OPENAI_API_KEY authoritative even if a stale one is already exported in the shell.

Decision 4 — --dry-run needs no age key

--dry-run prints the names of the secrets that would be set, one per line, sorted, then exits 0. It resolves those names via inspect (filenames only) — so, like clean, it needs no age key and triggers no Touch ID. Decrypting to print nothing but names would be pointless biometry. This gives the "safe summary I can paste to an agent" use case a genuinely zero-exposure path: no values are ever decrypted. --json output is deferred (overview default: one line per name; add JSON when a real user needs it).

Decision 5 — Exit-code propagation

• Child exits normally → run exits with the child's exit code (terminationReason == .exit → terminationStatus).
• Child dies from a signal → run exits 128 + signum (terminationReason == .uncaughtSignal → 128 + terminationStatus), the shell convention, so $? reads the way a user expects after a Ctrl-C'd child.

run uses Foundation.exit(...) with the mapped code rather than letting ArgumentParser return, so the child's status is what the parent shell sees.

Decision 6 — Signal forwarding: SIGINT, SIGTERM, SIGHUP; 5s grace → SIGKILL

run installs handlers for SIGINT, SIGTERM, and SIGHUP (via DispatchSourceSignal, which composes with Process far better than C signal() and needs the default disposition set to ignore first). On receipt, it forwards the same signal to the child's PID, waits a 5-second grace period, then sends SIGKILL if the child is still alive. SIGKILL and SIGSTOP are uncatchable and are not in the set. SIGQUIT and SIGUSR1/2 are follow-ons only if a real use case surfaces (overview).

The process-group nuance, named so the executor doesn't chase a ghost. In an interactive terminal, Process does not put the child in a new session or process group, so terminal-generated signals (Ctrl-C → SIGINT, Ctrl-\ → SIGQUIT) are delivered by the tty to the entire foreground process group — the child already receives them directly. Explicit forwarding therefore matters mainly for signals delivered programmatically to the wrapper's PID (kill <sharibako-pid>, a process manager, a parent script). Double-delivery in the terminal case is harmless: the child is already handling its own SIGINT, and a forwarded second one arrives against a process that's already shutting down. Do not try to suppress it by creating a new process group — that would break the terminal Ctrl-C path, which is the common case.

Decision 7 — Memory scrub: minimal best-effort

The temp age-key file is already scrubbed-and-deleted on handle.release() (KeychainAgeKeyProvider.scrubAndDelete); run keeps that via the same defer handle.release() pattern materialize uses. For the decrypted values, v1 does nothing beyond letting them go out of scope. Swift String backing storage is immutable and copy-on-write — there's no reliable in-place wipe without restructuring the whole decrypt→env pipeline onto [UInt8]/Data, and even then the values still live in the child's environ for the child's whole lifetime, which is the point of the verb. The residual risk (recovering a wrapper-process copy from physical memory after a crash) is low and already stated honestly in SECURITY.md's "Known limits." We harden later if a real reason appears. No memset_s theater over [String: String] in v1.

Decision 8 — Flags and passthrough parsing

run takes --scope <id> as an @Option (not a positional, since positionals after it are the command), reuses ScopeResolver.resolve(explicit:startingFrom:) for the cwd walk-up when --scope is omitted (same resolution as materialize), and captures everything after -- as the command with ArgumentParser's passthrough capture (@Argument(parsing: .captureForPassthrough) var command: [String]). --dry-run is a @Flag. Reuses GlobalOptions (--vault, --age-key, --json, --verbose) unchanged.

Decision 9 — Edge cases

• Empty scope (marker resolves, scope has zero owned keys): run the child with the parent environment unchanged and print a one-line note to stderr that no secrets were injected. Not an error — a scope can legitimately be empty mid-setup.
• No --scope and no marker in the cwd walk: VaultError.markerNotFound, reported through the existing ErrorReporter.
• Unknown scope (--scope foo, no such scope): surfaces as the getValue/inspect scopeNotFound error.
• Empty command (nothing after --): usage error — there is nothing to run.
• age/Keychain failure mid-unlock: the existing VaultError/CLIError paths already cover it; run adds no new swallowing.