[roodboi]

Refs HACK-1142 (WU29: ownership-safe shared host lifecycles).

What changes

The shared host helper contract from #343 (src/lib/shared-host-lifecycle.ts) is now usable from projects:

• Config: new lifecycle.sharedHelpers in hack.config.json, parsed in src/lib/project-shared-helpers.ts. Each entry has name, argv command, port, exactly one of upstream/upstreamEnv, and optional identityPath, cwd, env (names; the helper also gets PATH and nothing else), enabled and readyTimeoutMs. An invalid entry is refused, not skipped: hack up, hack down and hack restart fail with E_LIFECYCLE_FAILED before any hook, helper, lifecycle process or Compose command (a dedicated sharedHelpersError; other parse errors still only warn on the Compose path). JSON schema updated in src/templates.ts.
• hack up / hack restart (Compose and native): runLifecycleUpBeforeAndProcesses ensures each helper after up.before hooks and before lifecycle.processes. The holder is the instance's Compose project (<project>--<branch>). The claim dir is ~/.hack/shared-helpers/<name>-<port>/ (or $HACK_HOME), derived from helper and port only, so every branch and checkout shares one claim and lock.
• Same-instance ordering: overlapping hack up runs of one instance hold a per-instance lock across their ensures and record their operation id. A rollback releases only while it is still the latest start, so it never revokes a newer run's holder. hack down's release takes the same lock, so up and down of one instance never split its helper set.
• Rollback: a failed helper start, a later lifecycle/Compose failure, or SIGINT/SIGTERM during the start releases only the holders this run added. To support that, the library's ready result gains holderAdded, decided under the helper lock. SIGINT/SIGTERM handlers stay installed across the helper and lifecycle-process start. A signal aborts an in-flight helper start (the library stops a child it spawned), runs the cleanup for whatever started, then is re-raised. A disabled helper resolves none of its env.
• hack down: marks the instance stopping before Compose shutdown, then releases the instance's holder for every helper it acquired (recorded per instance at start) plus every configured one, so removing or renaming an entry does not strand a holder. A failed or unconfirmed release keeps the claim and fails hack down/hack restart with E_LIFECYCLE_FAILED (helper names in detail).
• Superseded starts (this slice's guarantee): hack up checks the instance right before containers start (a new beforeStart backend hook between up --no-start and up -d, before an attached up, at the end of native preparation, and before the restart repair start) and again after they start. A down during preparation is prevented (up fails E_LIFECYCLE_FAILED, no container starts). A down that completes after that check is detected after launch (detached up fails E_LIFECYCLE_FAILED; attached up only after Compose exits); the documented manual step is hack down --branch <name>, then hack up. Shutdown is tracked as a per-instance generation that only hack down advances. An up captures it when lifecycle preparation begins (before up.before hooks), so a down supersedes every up whose preparation began before it, even after a later up succeeds (with possibly different helpers), and a down during up.before stops that up before any helper starts. A newer start without a down in between does not supersede an earlier one, and once it is current the earlier start's cleanup (on failure or SIGINT/SIGTERM) skips the lifecycle session and helper holders it may have adopted. When the instance lock is too busy to decide, the cleanup keeps them and warns (hack down stops them).
• Messages carry the helper name and a closed reason only, never the upstream, argv or env values.

Acceptance items

Item	Status	Evidence
Wire the contract into config	fixed-with-test	tests/project-shared-helpers.test.ts (parse, refusals, readProjectConfig parse error), tests/project-config-schema.test.ts
Wire into up/down (and restart, native up)	fixed-with-test	e2e shared-host-helpers drives real hack up/down --branch
Wire into the daemon	deferred-with-reason	The daemon has no lifecycle surface today (no lifecycle code under src/daemon). Giving it start/stop authority over shared helpers is new live-session cleanup authority, which this task excludes. A read-only status view could be a follow-up.
Healthy shared helper	fixed-with-test	e2e: an external identity-matching helper is adopted; down releases it and it keeps serving. Module test too.
Wrong upstream	fixed-with-test	e2e: a sibling branch with another upstream fails E_LIFECYCLE_FAILED / wrong-upstream, the value is absent from output, and the shared helper and its holders are unchanged.
Foreign port	fixed-with-test	e2e: a silent TCP owner gives foreign-listener, survives and leaves no claim. Module test also covers a different helper kind.
Concurrent startup	fixed-with-test	e2e: two hack up --branch in parallel give one owned spawn and both holders.
Stale PID	fixed-with-test	e2e: a claim naming a live bystander PID with another birth is discarded; the bystander survives.
Child restart	fixed-with-test	e2e: a SIGKILLed owned helper is replaced under a fresh claim on the next up.
Shutdown during retry	fixed-with-test	e2e: SIGTERM to hack up while a never-ready helper retries; exit 143 within 5 s, the owned child is stopped and the claim removed.
Lost parent	fixed-with-test	e2e: SIGKILL to hack up leaves the helper recorded; the next up stops it at its deadline; a later up starts fresh.
No owned orphan / foreign survival / actual endpoint	fixed-with-test	Every e2e phase checks process liveness through the birth-verified census and fetches the endpoint.
Failed up rolls back only its own holder	fixed-with-test	e2e Compose-failure phase plus the module rollback test (pre-existing holder kept).
Independent review: down during a paused up	fixed-with-test	e2e "down during a paused up": up paused at image prep, down completes, the resumed up fails E_LIFECYCLE_FAILED and never runs up -d. Module test for the stopping mark.
Independent review: removed/changed helper entry	fixed-with-test	e2e "entry removed after start"; module test covers removal and a port change.
Independent review: failed release reported as successful down	fixed-with-test	e2e "unreleased helper": hack down exits non-zero with E_LIFECYCLE_FAILED and keeps the claim; module test keeps the acquired record for retry.
Second independent review 1: newer up tears down an adopted session	fixed-with-test	e2e "a newer up never makes an earlier up tear down its session" (helpers + a tmux lifecycle process; the earlier up is paused at image prep, the newer up adopts, the earlier up then succeeds without killing the session). Module test too.
Second independent review 2: release failures vanish with no helper configured	fixed-with-test	e2e "a release failure with no helper configured still fails down"; module test with helpers: undefined and [] for an unreadable record and an unavailable lock.
Second independent review 3: invalid config discarded	fixed-with-test	e2e "an invalid sharedHelpers entry is refused before any effect" (up, down and restart).
Second independent review 4: overstated startup guarantee	fixed (docs)	docs/lifecycle.md states "prevented during preparation, detected after launch" with the manual cleanup step.
Codex: restart repair unguarded	fixed-with-test	tests/project-restart-repair-guard.test.ts.
Third independent review 1: earlier failed up kills an adopted session	fixed-with-test	Process cleanup runs under the instance lock and is skipped once a newer start is current. e2e overlap phase now covers the earlier up succeeding, failing in Compose and receiving SIGTERM. Module test for runUnlessNewerStart.
Third independent review 2: later start erases shutdown invalidation	fixed-with-test	Shutdown generation. e2e "a newer up with the helper disabled does not restore an earlier up after down"; module test with a disabled and a changed-port helper.
Third independent review 3: cache bootstrap failure skips rollback	fixed (guard), no failing regression possible	Cleanup now runs on that branch, but it is unreachable with helpers today: the bootstrap runs only for a service-scoped up, which never starts lifecycle work or helpers.
Fourth independent review 1: lock-timeout fallback kills an adopted session	fixed-with-test	runUnlessNewerStart returns undecidable and keeps the session when the lock is unavailable; the rollback keeps holders (lock-unavailable) instead of throwing. e2e overlap variant sigterm-lock-held; module test with B successful and the lock held past the timeout.
Fourth independent review 2: shutdown generation captured too late	fixed-with-test	Captured at the start of runLifecycleUpBeforeAndProcesses, before up.before, and carried into helper startup. e2e "a down while an up waits in up.before supersedes that up"; module test.
Codex + fifth independent review 1: native down marks stopping before it is committed	fixed-with-test	nativeProjectDown gains beforeCleanup, run after the before hook and the ownership/finalization rechecks, immediately before graph cleanup; the mark lives there. tests/native-project-down.test.ts: a down refused by a finalization change, an ownership change or a failing hook leaves the shutdown generation and operation record unchanged; a committed down marks right before graph cleanup.
Fifth independent review 2: undecidable cleanup still ran the helper rollback	fixed-with-test	The combined cleanup skips the rollback when process cleanup is undecidable, keeping the session and holders together. tests/shared-helper-cleanup-combiner.test.ts.
Codex: session cleanup authority from helper order	fixed-with-test	SharedHelperSessionOwnership: session decision/creation recorded under the instance lock; a creator's cleanup runs only while the epoch is its own. Module tests and e2e overlap variants.
Sixth independent review 1: epoch record failure strands a created session	fixed-with-test	A failure after creation stops the session with its token before removing the entry; an unconfirmed stop keeps entry and token. tests/project-lifecycle-controller-ownership.test.ts.
Sixth independent review 2: a stale create decision erases the winner's entry	fixed-with-test	Revalidate, publish, create and record run under one instance-lock acquisition; a stale create decision refuses without publishing. Controller interleaving regression.
Sixth independent review 3: model made the decision and creation atomic	fixed (model)	See the model row; source mapping and coverage claims updated.
Codex: abort dropped the retained ownership record	fixed-with-test	starterAbort removes the entry only after a confirmed stop; regression through abort() with the kill still failing.
Seventh independent review 1: a displaced starter overwrites the replacement's entry	fixed-with-test	finalize() is a locked recheck with conditional publication; a displaced start gives up its authority (LifecycleSessionDisplacedError). Controller regression (replacement after creation, before finalize; reclaimed by the real stop controller).
Seventh independent review 2: session creation can hold the instance lock indefinitely	fixed-with-test	All non-interactive tmux/zellij commands bounded (MUX_COMMAND_TIMEOUT_MS); controller deadline on each mux call under the lock; unknown outcomes keep the entry and token. Hung-creation regression.
Seventh independent review 3: model folded process start and finalize into Record	fixed (model)	See the model row.
Codex: ownership dropped before a timed-out creation settled	fixed-with-test	Outstanding createSession tracked; cleanup and abort keep the record until it settles.
Eighth independent review 1–2: abandoned timed-out creation/replacement races other commands	fixed by design	The controller-level deadline race is removed. runMuxCommand bounds every lifecycle and backend mux call with a subprocess timeout, so each call settles (the client is killed) before the lock is released; no late creation or stale continuation exists. Replacement retires only the inspected entry, by token. Regressions: timed-out creation (created / not created, nothing in flight afterwards) and a stalled replacement with an overlapping up. Timeout settlement is an assumption, narrowed per backend in round 11 (see that row).
Eighth independent review 3: mux timeouts read as absence	fixed-with-test	Timeouts throw MuxCommandTimeoutError (presence reports unknown); lifecycle callers and doctor hygiene fail closed; the project-meta display skips the backend.
Eighth independent review 4: SIGTERM could wait on unbounded tmux commands	fixed-with-test	The controller's own set-environment, new-window, list-panes, send-keys and zellij run are bounded too. SIGTERM-during-environment-setup regression.
Eighth independent review 5: model lacked timeout and late-completion transitions	fixed (model)	See the model row.
Round 11 P2-1: a startup failure rolled back helpers under a retained session	fixed-with-test	abort() returns LIFECYCLE_SESSION_RETAINED; startLifecycleProcesses raises LifecycleSessionRetainedError; releaseAfterFailedProcessStart skips the rollback. The regression goes through the real startLifecycleProcesses catch (the second process fails, the kill fails).
Round 11 P2-2: failed-creation cleanup and abort() killed by name without the lock	fixed-with-test	The failure cleanup runs inside the creation lock; abort() and signal cleanup take the lock; the operation cleanup runs inside runIfOwned's lock (now always taken) and never re-acquires it. Regressions: a replacement overlapping the abort, and one overlapping the failed-creation cleanup (each stalls the kill's own token read).
Round 11 P2-3: a displaced start could set environment or launch into the replacement	fixed-with-test	tmux environment setup runs inside the locked creation transaction; each launch runs under the lock only while the entry and live session carry this start's token (otherwise LifecycleSessionDisplacedError, nothing launched). Regressions for a displaced launch (zellij call log) and for environment setup overlapped by a replacement (tmux event order).
Round 11 P2-4: down released holders after a failed or unknown session stop	fixed-with-test	stopSessionBeforeReleasingHelpers: down, restart and native retirement release only after the session stop succeeded; otherwise every holder is kept, a warning is shown and the command fails (E_LIFECYCLE_FAILED, helper names in detail). Unit regressions for both outcomes.
Round 11: mux timeout settlement	narrowed per backend, follow-up proposed	Killing a timed-out client does not prove the server will not still apply its command (tmux per-client queues; zellij's daemonized create). The README states the residual per late command (create, name-based kill, environment/window/pane) and why each stays recoverable for the same instance. Closing it needs session-ID targeting for tmux; zellij has no session ID.
Full launch prevention across a concurrent down	deferred-with-reason	Owner decision for this first slice. The instance lock is held only for each check, so a down can still complete between the last check and container start (or during an attached up). Closing it needs the instance coordinated through Compose start and down's shutdown (e.g. a lease held across both commands). Remaining work.
Executable negative controls	fixed-with-test	See below.
Migrate lifecycle.singleton configs	kept-with-reason	singleton keeps port-only adoption; moving to sharedHelpers is opt-in.
Public tunnel readiness (WU18-P06)	out of scope	No tunnel is started and no external service is contacted.
TLA+ model for the shared helper protocol	fixed (model)	tests/models/tla/shared-helper-instance: session ownership across overlapping ups and a down; SessionSafe, Reclaimable, NoForeignLaunch and HelpersKeptForSession over 7,466 states. The session decision, the locked creation transaction (revalidate, publish, create, environment, record, and the failure cleanup inside the lock), fenced process launches, the locked conditional finalize, and a down whose session stop fails are separate steps. Ten controls each fail with a named witness: no epoch check, no revalidation, unstopped epoch failure, stale finalize, abandoned creation, abandoned replacement, timeout read as absence, unlocked failure cleanup, unfenced launch, and release on a failed stop. Registered and mapped in the README and docs/reference/v5-model-coverage.md. The claim protocol itself stays fixture-covered.
(was) TLA+ model for the shared helper protocol	superseded	See the row above.
hack logs / projects --details visibility	deferred-with-reason	Helpers run outside the lifecycle mux session; up/down print value-free status lines only.

Note: the Linear connector was not authorized in the session that built this, so the items above come from the task brief and the in-repo contract docs, not from the issue's Acceptance text. Please reconcile against the issue.

Negative controls (source mutation, then the guarding test fails)

Mutation	Fails
M1: no rollback when a helper fails	module: "a later helper's failure rolls back only the holders this run added"
M2: rollback ignores holderAdded	same module test
M3: helper inherits the runner env	module: "the helper gets PATH and only its listed env"
M4: library holderAdded always true	library: "holderAdded reports whether this call recorded the holder"
M5: down does not release	e2e: "branch A down must leave the helper for branch B"
M6: SIGTERM does not abort the start	e2e: "SIGTERM during retry must promptly stop…" (exit after ~29.5 s)
M7: up ignores a failed helper	e2e: "a wrong-upstream sibling must fail closed"
M8: invalid entries are not a parse error	module: "an invalid sharedHelpers entry is a project config parse error"
M9: Compose failure skips helper rollback	e2e: "a compose failure must roll back A's new holder, not B's"
N1: rollback ignores a newer same-instance start	module: "an overlapping start of the same instance is never revoked by the earlier run's rollback"
N2: disabled helper resolves its env	module: "a disabled helper needs none of its runtime env"
N3: a caught signal skips the cleanup	module: "a signal anywhere in a guarded start runs its cleanup, then is re-raised"
N4: release bypasses the instance lock	module: "a release waits for a start of the same instance, so up and down never split the helper set"
A1: no check before containers start	e2e: "a superseded up must fail before starting containers"
A2: down ignores the acquired record	module: "down releases helpers the instance acquired even after their config entry is removed or changed" (and the failed-release retry test)
A3: down ignores helper release failures	e2e: "a failed helper release must fail down and keep the claim"
A4: the stopping mark writes nothing	module only: "a down that marks the instance stopping, or releases it, supersedes an in-flight start". The paused-up e2e does not catch it, because a completed down also deletes the operation record.
A5: the current-operation check always passes	e2e: "a superseded up must fail before starting containers" (exit 0)
B1: a newer start supersedes an earlier one	module: "a newer start of the same instance does not supersede an earlier one; a down supersedes both"
B2: unlisted release failures vanish	module: "with no helper configured, an unreadable record or a held lock still fails the release"; e2e (B2e): "an unreadable acquired record must fail down even with no helper configured"
B1e: a newer start supersedes (CLI)	e2e: "the earlier up must not tear down the adopted session or helpers"
C1: commands do not refuse invalid helpers	e2e: "hack down must refuse an invalid sharedHelpers entry"
C2: restart repair unguarded	module: both tests in tests/project-restart-repair-guard.test.ts
D1: a failing start records itself as current	module: "a start that fails after a down keeps the shutdown in force for an earlier start"
E1: operation record written outside the rollback	module: "a start whose operation record cannot be written rolls back its holders"
E2: no acquired-record limit before writing	module: "a start refuses to grow the acquired record past its limit; down still releases"
G1: process cleanup ignores a newer start	e2e: "the earlier up (compose-fails) must not tear down the adopted session or helpers", and on its own the sigterm variant (exit 143). Not caught by the module test, which calls runUnlessNewerStart directly.
H1: undecidable cleanup still kills the session	module: "when the instance lock outlasts the cleanup timeout, an earlier start keeps the session a newer start may have adopted"; e2e: "the earlier up (sigterm-lock-held) must not tear down the adopted session or helpers"
H2: generation read at helper start, not before up.before	module: "a down during an operation's preparation hooks supersedes it before any helper starts"; e2e: "an up superseded during up.before must start no helper or service"
I1: native mark before the ownership/finalization rechecks	tests/native-project-down.test.ts: both new tests
I2: helper rollback despite undecidable cleanup	tests/shared-helper-cleanup-combiner.test.ts: "an undecidable process cleanup keeps the helper holders too"
J1: creator cleanup ignores the session epoch	module: "session ownership follows adoption, not the order starts ensured their helpers" and two others
J2: adoption not recorded	e2e: "the earlier up (compose-fails) must not tear down the adopted session or helpers"
K1: no revalidation under the creation lock	tests/project-lifecycle-controller-ownership.test.ts: "a start that decided to create refuses after an overlapping start created and finalized the session"
K2: remove the entry without stopping the created session	tests/project-lifecycle-controller-ownership.test.ts: both epoch-record-failure tests
L1: abort removes the entry without a confirmed stop	tests/project-lifecycle-controller-ownership.test.ts: "when that stop is not confirmed, the entry and token stay so the session is reclaimable"
M1: finalize publishes unconditionally	tests/project-lifecycle-controller-ownership.test.ts: "a start displaced after creating its session, before finalizing, leaves the replacement owned and reclaimable"
M2: no deadline on session creation	tests/project-lifecycle-controller-ownership.test.ts: "a hung session creation releases the instance lock within its bound and stays reclaimable" (fails with "creation did not settle")
N1/N2: cleanup or abort ignores an outstanding creation	tests/project-lifecycle-controller-ownership.test.ts: "a timed-out creation keeps its ownership record until the creation settles…"
O1: a timed-out command returns its result (old [])	tests/mux-command-timeout.test.ts: both tests
O2: a deadline race that abandons the replacement	tests/project-lifecycle-controller-ownership.test.ts: "a stalled replacement holds the lock until it settles…" (an abandoned call is still in flight)
O3: unbounded set-environment	tests/project-lifecycle-controller-ownership.test.ts: "SIGTERM during tmux environment setup settles within the mux bound"
P1: startup catch drops the retained signal	tests/project-lifecycle-controller-ownership.test.ts: "a startup whose second process fails and whose session stop is unconfirmed keeps the shared helpers (real startup catch)"
P2: abort() without the instance lock	same file: "abort's token read and kill run under the instance lock…"
P3: failed-creation cleanup after the lock is released	same file: "failed-creation cleanup reads the token and kills under the creation lock…"
P4: tmux environment setup after the lock is released	same file: "tmux environment setup finishes under the creation lock…"
P5: launch without the lock and token check	same file: "a displaced start never launches a process into its replacement's session"
P6: down releases holders after a failed session stop	tests/shared-helper-cleanup-combiner.test.ts: "down keeps every helper holder and reports them when the session stop failed or is unknown"
G2: a later start restores an earlier one (old operation check)	e2e: "the earlier up must stay superseded after a later up with the helper disabled"; module: "a later successful start does not restore an earlier start after a down…"

M6 first slipped through: locally bun on PATH is a wrapper, and SIGTERM to it tore down the whole process scope. The signal probe now signals the CLI process itself (process.execPath index.ts) and bounds the exit time.

Validation (local, Linux x64)

• bun test tests/project-shared-helpers.test.ts tests/project-restart-repair-guard.test.ts: 29 pass
• bun test tests/shared-host-lifecycle.test.ts: 39 pass
• bun test tests/project-config-schema.test.ts tests/project-config.test.ts: pass
• bun tests/e2e/run.ts --only=shared-host-helpers: pass (~15 s; registered as a local-tier scenario, so it runs in the docker-e2e shards)
• bun run typecheck, bun run check, bun run docs:check: pass
• bun run test (full suite, Linux host without a C linker; config compiler copied from a same-base build): 850 failures in 76 files, almost all native/macOS VM suites. Rerunning those 76 files one at a time gives 844 failures on both base 31b497cf and head, identical file by file; the other 6 pass in isolation. None is introduced here.
• tests/project-shared-helpers.test.ts is added to the hosted linux-process-lifetime job.
• Round 11 at df72b183: bun run typecheck, bun run check, bun run docs:check pass. The focused lifecycle, shared-helper, mux, native-down and project-meta tests pass (267 of 269). The two failures are in native-compose-adoption-local*; they fail the same way on this host at 98978b5b, whose hosted CI was green, so they depend on this host and not on this change. Both e2e suites pass, run one at a time (shared-host-helpers, lifecycle-session-recovery). bun run test:models passes all models and controls.

Not proven here: macOS host behavior (hosted macOS test shards will run the bun tests), installed binaries and releases.

Release intent: feat (optional new config capability).

🤖 Generated with Claude Code

[roodboi]

@codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-03T20:58:00.205562Z	ef80f39	Manual request
🔒 Security Review	✅ Completed 2026-11-03T20:59:13.760982Z	ef80f39	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[linear-code]

HACK-1142

HACK-1849

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: b3d59484a3

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b3d59484a3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[roodboi]

Full-suite follow-up (local Linux x64, no C linker): I reran the 76 files that failed in bun run test one at a time on this head and on the base 31b497cf. Both give 844 failures, identical file by file, almost all native/macOS VM suites that need host-native prerequisites. The other 6 of the original 850 passed when rerun in isolation, so they are load-related. No failure is introduced by this PR. Hosted CI is the authoritative gate.

[roodboi]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8d97f19d90

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: 8d97f19d90

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[roodboi]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: 535a94de16

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: 535a94de16

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[roodboi]

Merged origin/next into the branch (normal merge commit, no rebase or force-push). New head: 41af91279b92bb8f11c792da5363748840935689. The merge had no conflicts. It brings in 4 commits from next (#557, #337, #419, #545). On the merged head: bun run typecheck and bun run check pass; bun test on the shared-helper, shared-host library, config, config-schema, test-budget and lifecycle-json files gives 84 pass, 0 fail; e2e shared-host-helpers and lifecycle-session-recovery pass. Hosted CI is running on the new head.

[roodboi]

New head: b8779909fb754f5f9d1a8bf60603b4ef85648931. This fixes the three findings from the independent Codex Astra review at 535a94de, on top of the clean merge of next (41af9127).

1. [P1] Same-instance down under a successful up. hack down and hack restart now mark the instance as stopping under the instance lock before Compose shutdown, and release clears the instance's operation record. hack up checks that it is still the current operation (a) right before any container starts, through a new runtime-backend beforeStart hook that runs between up --no-start and up -d (or before an attached up, and at the end of native preparation), and (b) again after a successful start. A superseded up fails with E_LIFECYCLE_FAILED, runs its lifecycle cleanup and launches nothing.
   • CLI regression (e2e "down during a paused up"): hack up is gated in Compose image preparation after its helpers are ready. hack down completes and stops the helper. The resumed up exits non-zero with E_LIFECYCLE_FAILED, and the fake Docker log shows no up -d.
   • Negative controls: A1 (no beforeStart check) and A5 (check always passes) each fail this CLI regression. A4 (stopping mark writes nothing) does not fail it: a completed down also deletes the operation record, so the paused up is still refused. A4 is caught by the module test "a down that marks the instance stopping, or releases it, supersedes an in-flight start". (Corrected after review: this line first credited A4 to the CLI regression.)
2. [P2] Removed or changed helper entry strands its holder. Each instance now records the identity (name and port) of every helper it acquires, written before each ensure in shared-helpers/.instances/<holder>.acquired.json. Down releases that record plus the current config and keeps only entries whose release failed.
   • Coverage: e2e "entry removed after start", plus module tests for removal and a port change (the original holder disappears and the owned helper stops).
   • Negative control A2 (ignore the record) fails them.
3. [P2] Incomplete helper release reported as a successful down. stopLifecycleProcessesBestEffort keeps process cleanup best-effort but now returns helper-release failures instead of swallowing them. hack down and hack restart turn them into E_LIFECYCLE_FAILED (non-zero, helper names in detail.sharedHelpers) with the claim kept. The signal-cleanup path stays non-throwing.
   • CLI regression (e2e "unreleased helper"): an unreadable claim makes down exit non-zero with the structured failure; the claim and helper are kept, and after the claim is restored the next down stops the helper.
   • Negative control A3 fails it.

Locally on b8779909: typecheck and lint pass; 138 tests across 11 lifecycle, config, compose-startup and native down/lifecycle files pass; e2e shared-host-helpers and lifecycle-session-recovery pass. Hosted CI is running.

[roodboi]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b8779909fb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: b8779909fb

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[roodboi]

New head 2b8f05ed36c93fe5f09e8d43ed8adbb798920f6e fixes Codex's two findings at b8779909: only a shutdown (the stopping mark or a release) now supersedes a start, so a newer start of the same instance no longer triggers the earlier start's cleanup; and an unreadable acquired record or a held instance lock now fails hack down even when no helper is configured. Both have regression tests and negative controls (B1, B2); both threads are answered and resolved. No merge with next was needed (not behind).

[roodboi]

@codex review

[roodboi]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 30595cbc89

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: 30595cbc89

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[roodboi]

New head: dc030562. next is unchanged, so there was no merge.

The m5 reviewer's restart P2 and the two Codex threads from 30595cb are fixed, and the threads are resolved:

• A preserved-runtime restart released its helpers (3f305510). Container outcomes are now explicit (stopped, unconfirmed or kept). Restart's preserved runtime is kept: the holders stay, nothing is reported as a failure, and the up phase reuses the helpers.
• A post-start failure released helpers under running containers (f0a70b8b). Once a detached up or restart has started the containers, keepSharedHelpers makes later cleanup stop only the lifecycle processes and keep the holders.
• Tests: both have e2e regressions through the real CLI (runRetainedHelperPhases: restart keeps the same helper; a failing up.after keeps it), plus unit tests. All three negative controls are caught. docs/lifecycle.md is updated.

Checks at dc030562:

• bun run typecheck, bun run check and bun run docs:check pass.
• 279 focused tests pass.
• Both e2e suites pass, run one at a time.
• bun run test:models passes: 135 verified.

CI: Candidate core (macos-latest) still fails at the Zig 0.15.2 download (404 from every mirror, also on other branches). I'll rerun that job if it fails on this head.

[roodboi]

@codex review

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: dc030562ec

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dc030562ec

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[roodboi]

New head: b05a6634. next is unchanged, so there was no merge.

The m5 reviewer and Codex (on dc030562) both found the same P2: a partially failed Compose start released helpers under the services it had started. Fixed in a0ba8d0c:

• After an unsuccessful start (a non-zero or timed-out up, a failed restart repair, or an error after the start), the helpers are kept unless docker compose ps -a confirms no container of the project may run.
• A failed ps counts as unknown, so the helpers are kept.
• A Compose failure that started nothing still rolls back.
• Regressions: an e2e partial start through the real CLI, the restart repair ordering, and the decision for each probe outcome. All three negative controls are caught. docs/lifecycle.md is updated (b05a6634).

Checks at b05a6634:

• bun run typecheck, bun run check and bun run docs:check pass.
• 281 focused tests pass.
• Both e2e suites pass, run one at a time.
• bun run test:models passes: 135 verified.

[roodboi]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

hack/src/commands/project.ts

Lines 6257 to 6259 in b05a663

	const signalCleanup =
	lifecycleSignalCleanup ??
	installLifecycleSignalCleanup({ cleanup: lifecycleCleanup });

Preserve helper holders during interrupted Compose startup

If SIGINT/SIGTERM arrives during a detached Compose start after some containers have started, this handler invokes lifecycleCleanup directly while the combined cleanup's containersRunning flag is still false; keepSharedHelpers is only called after Compose returns successfully. With no retained lifecycle session, cleanup therefore releases newly added holders and can stop the last-held helper underneath those containers. Unlike the corrected nonzero-result path, this signal callback bypasses retainHelpersUnlessContainersAbsent entirely. Apply container-retention protection to signal cleanup as well, including the corresponding restart handler, before allowing helper rollback.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: b05a663458

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[roodboi]

New head: 6f4cf0d7. next is unchanged, so there was no merge.

The m5 reviewer and Codex's review of b05a663 ("Preserve helper holders during interrupted Compose startup", review 5758858584, a review-body finding with no thread) found the same P2. The SIGINT/SIGTERM cleanup for hack up and hack restart called the combined cleanup directly. A signal that arrived while docker compose up was still starting services, after some had started, therefore released the helpers.

Fixed in 467712aa:

• containerStartBegun is set right before the guarded Compose up, in both up and restart.
• From then on, the installed signal cleanup (signalCleanupKeepingStartedHelpers) keeps the helpers before cleaning up, so only the lifecycle processes stop. There's no probe here, because a start still in progress can start services after any snapshot.
• Regressions: an e2e where SIGTERM hits a real hack up paused inside docker compose up (the helper and its claim survive until hack down), plus a unit test of the handler. Negative controls (flag never set; handler ignores it): both caught.
• docs/lifecycle.md is updated (6f4cf0d7).

Checks at 6f4cf0d7:

• bun run typecheck, bun run check and bun run docs:check pass.
• 282 focused tests pass.
• Both e2e suites pass, run one at a time.
• bun run test:models passes: 135 verified.

[roodboi]

@codex review

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: 6f4cf0d786

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[roodboi]

New head: ef80f399, a normal merge of origin/next (12c0b35e, #554 HACK-1341). The merge was clean.

Astra r13 (full review at 6f4cf0d7) found one P2: an interrupted stopping mark could release helpers under started containers. A down publishes its shutdown generation and then its operation record as two separate writes. A down interrupted between them, or whose record write failed, left the up's operation record in place. A superseded up's post-start rollback then released the last holder.

Fixed in d4130919:

• Rollback now also requires the shutdown generation the start captured. Once any down has advanced it, the holders are kept for the next down.
• Regression in tests/project-shared-helpers.test.ts: an interrupted mark, then the post-start supersession check and rollback. The helper and its claim survive, and a later down releases them. Negative control (rollback ignoring the generation): caught.
• docs/lifecycle.md is updated (bca00ae7).

Codex's review of 6f4cf0d reported findings in its summary but posted no review, thread or comment for that head. There are no unresolved threads.

Checks at ef80f399:

• bun run typecheck, bun run check and bun run docs:check pass.
• 351 focused tests pass, including next's new route-claim and batch-inspect tests.
• Both e2e suites pass, run one at a time.
• bun run test:models passes: 135 verified.

[roodboi]

@codex review

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: ef80f39952

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.