Skip to content

feat(lifecycle): opt into built-in host process supervision - #811

Merged
roodboi merged 85 commits into
nextfrom
feat/lifecycle-supervisor-opt-in
Nov 15, 2026
Merged

roodboi merged 85 commits into
nextfrom
feat/lifecycle-supervisor-opt-in

Conversation

@roodboi

@roodboi roodboi commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Add lifecycle.runner: "supervisor" for Compose host lifecycle processes; omitted settings keep mux. Persistent hooks retain their order, logs keep the existing private TSV path, and down/restart follow the recorded runner.

Depends on #802 and its pending native recovery/resource fixes. Packaging is a separate slice. Before hooks or ownership publication, the CLI verifies the sibling executable's permissions and exact version/capability handshake. Compiled installations ignore the executable override; source development and tests may select an explicit binary. Doctor reports its resolved path and version.

Launch, adoption and cleanup ownership

Ownership and recovery:

  • Environment travels only over framed stdin, never argv or payload files. Native IPC lives outside checkout mounts and checks host peers.
  • Canonical project paths key native roots; ownership records their absolute location. A changed HOME or symlink spelling does not relocate running work. A missing root after dispatch is unconfirmed and retains ownership; it never proves processes stopped.
  • A durable launch-not-attempted marker permits down/doctor cleanup without the binary only when no PID or process was published. An uncertain launch retains ownership. Adoption advances the cleanup epoch; doctor holds the controller lock throughout retirement.
  • Initial and later serve requests wait for retiring owners within bounds. Lost incremental replies publish verified late commands before reporting failure.

Default mux compatibility changes are explicit: state mutations serialize on state.lock and publish atomically at mode 0600. Empty or unparsable JSON from older non-atomic mux writes is preserved in a timestamped sibling, explained once and treated as empty. After supervisor ownership has been published, a durable marker disables this fallback. Unsafe links/foreign ownership and semantically invalid records continue to refuse; global observers keep that project unknown and continue. Run hack down before downgrading or switching CLI builds, since older parsers cannot preserve supervisor ownership.

Validation on Linux:

  • 50 Rust tests pass; Clippy with warnings denied and formatting pass.
  • 56 focused Bun tests pass; an additional definition-replacement regression passes with all 14 real-native controller cases. CLI typecheck/check, changed-file lint, privacy scan and actionlint pass.
  • Compiled CLI recovery and real-Docker host-process scenarios pass under both runners, no skips or fixture networks left. The compiled missing-companion regression verifies no ownership is published and down remains usable; a production override cannot redirect it.
  • The controller model remains 21 states; its coverage document distinguishes the finite ownership abstraction from executable, filesystem and platform regressions.
  • Hosted exact-head CI and second-family review remain pending. No completed local full-repository suite pass is claimed. The native source prerequisite still has lead-required fixes in progress; this PR is not ready to merge.

macOS arm64 and Intel jobs are intentional: native identity, Unix sockets, descriptor handling and peer credentials require real Mac execution. Workflow filters now include dependent CLI sources and every executed test; controller checks use the built release executable. Docker shard 4 runs both lifecycle scenarios under the supervisor runner.

Release intent: optional capability (feat), with the state compatibility corrections above. No lifecycle default change, zellij removal, PTY, log rotation or support for deliberately escaping sessions in this slice.

@vercel

vercel Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
hack-docs Ready Ready Preview Nov 15, 2026 9:10am UTC

Request Review

@roodboi

roodboi commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

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

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-15T09:17:32.034536Z 897cb3e Manual request
🔒 Security Review ✅ Completed 2026-11-15T09:20:01.694343Z 897cb3e Manual request

Security findings

Advisory findings (1)

ℹ️ 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.

@roodboi

roodboi commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4b3d1ae0ce

ℹ️ 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".

Comment thread src/lib/project-lifecycle-hygiene.ts Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛡️ Codex Security Review · Automatically triggered

Here are some automated security review suggestions for this pull request.

Reviewed commit: 4b3d1ae0ce

ℹ️ 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.

Comment thread src/lib/lifecycle-supervisor.ts Resolved
…or-opt-in

# Conflicts:
#	docs/reference/v5-model-coverage.md
#	scripts/lib/tla-runtime-models.ts
@roodboi

roodboi commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b5b9860f40

ℹ️ 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

roodboi commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

@codex review

@roodboi

roodboi commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: c2bc1ff15c

ℹ️ 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

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. 👍

Reviewed commit: dc1408ec84

ℹ️ 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

Copy link
Copy Markdown

🛡️ Codex Security Review · Automatically triggered

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

Reviewed commit: dc1408ec84

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.

…isor

# Conflicts:
#	docs/reference/v5-model-coverage.md
#	scripts/lib/tla-runtime-models.ts
…or-opt-in

# Conflicts:
#	docs/reference/v5-model-coverage.md
@roodboi

roodboi commented Nov 15, 2026

Copy link
Copy Markdown
Contributor Author

@codex review

@roodboi

roodboi commented Nov 15, 2026

Copy link
Copy Markdown
Contributor Author

Ready for lead: 8ffd3c0

A normal merge of #802 at eb47cc8 (which carries next bf74aaf) into 88f8546 (the previous Ready head). One conflict, docs/reference/v5-model-coverage.md: kept #811's lifecycle-controller row and next's env-migration row. src/lib/project.ts and scripts/lib/tla-runtime-models.ts auto-merged; all three model contracts are present. Merge after #802, then merge next here if it moves again.

What I ran (Linux 6.8 x86_64): tests/sync-spawn-bound.test.ts and tests/tla-runtime-models.test.ts (182 pass; #811's new tests pass the bounded-spawn lint); root typecheck; build, config compiler and all 8 check:native-plan-cli acceptance scripts. Rust: fmt, all-feature Clippy, 14 unit, 52 fake-caller, 18 incremental and 2 crash-checkpoint tests. 306 lifecycle Bun tests (21 skipped) against the release binary. lifecycle-session-recovery e2e passes under both the mux and supervisor runners.

Where the tests ran: locally on Linux 6.8.0. Hosted at the previous head 88f8546: Supervisor jobs on macOS 15.8.2 (arm64), macOS 15.7.9 (Intel) and Ubuntu 26.04.1; Candidate core on macOS 26.7.2; Docker e2e on Ubuntu 24.04.5 (all green). At this head, hosted CI was still queued at note time (8 pass, 22 pending, 0 failed); I did not wait for the macOS jobs. computer pr review-status: CLEAR at 8ffd3c0.

Review: the persistent Codex reviewer is CLEAN at this head (it checked the project.ts auto-merge against #797/#795 and the bounded-spawn lint). The Codex GitHub bot was re-requested.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. 🎉

Reviewed commit: 8ffd3c0f6e

ℹ️ 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

Copy link
Copy Markdown

🛡️ Codex Security Review · Automatically triggered

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

Reviewed commit: 8ffd3c0f6e

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 and others added 5 commits November 15, 2026 06:38
…on a sibling

Every guard took a blocking flock on the shared lifecycle.log around each
record. A guard stopped (SIGSTOP, a debugger, a hung write) while holding
it stalled every sibling guard's loop in flock: no output, no exit
detection, no stop handling. Captured on macOS as the 9/100 failure of
expired_target_does_not_abandon_other_recovery (worker guard blocked in
Lines::flush -> flock while the frozen blocked guard held the lock).

Each record is now one write on the O_APPEND descriptor with no lock. The
kernel places each append atomically, so whole records from different
guards never interleave on a local file system; only a short write (for
example a full disk) can split one. The unused flock retry helper and its
unit test are removed.

Regressions: held_log_lock_never_stalls_a_guard holds the log flock from
outside for the whole run and requires output to reach the log and stop
to answer stopped within the normal bound (fails with the old lock);
concurrent_guards_append_whole_records_without_a_lock checks two guards
bursting 64 KiB records leave only whole, unmixed records. Docs state the
log's ordering and integrity and list every lock, who can hold it across
a blocking call, and the bound.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…hort-write causes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…or-opt-in

# Conflicts:
#	docs/versions/v5/getting-started.md
…sor lock table

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@roodboi

roodboi commented Nov 15, 2026

Copy link
Copy Markdown
Contributor Author

@codex review

@roodboi

roodboi commented Nov 15, 2026

Copy link
Copy Markdown
Contributor Author

Ready for lead: a9bc571

Merge after #802, then merge next here if it has moved. This head is #802 b2b8d53 (next 345dc0d plus round 6's unlocked log appends) merged into 8ffd3c0, plus one docs commit.

Merge resolution: one conflict, docs/versions/v5/getting-started.md, where I kept both added paragraphs (supervisor runner, and next's project JSON rows). src/lib/runtime-projects.ts auto-merged.

Generated files: regenerated, with no diff: docs:cli-reference, scripts/generate-machine-output-reference.ts and generate:agent-plugins (which includes the diagnose skill's references). #811 adds no new --json command, and tests/machine-output-contract.test.ts passes.

Docs: the "Locks and waits" table now lists #811's waits, verified against the code by the reviewer:

  • run/serve wait 10 s for the instance lock.
  • serve holds .stop.lock until ready, and add holds it while it admits a command.
  • status waits up to 16 s only on an existing stop lock, with a framed stop-lock-wait-expired on expiry.
  • The add forwarder reads its reply within 26 s.

What I ran (Linux 6.8.0 x86_64):

  • Machine-output contract, sync-spawn-bound and tla-runtime-models tests: 269 pass.
  • Typecheck.
  • Build, config compiler and all 8 acceptance scripts.
  • Rust: fmt; all-feature Clippy with warnings denied on Linux, aarch64-apple-darwin and x86_64-apple-darwin; 13 unit, 54 fake-caller, 18 incremental and 2 crash-checkpoint tests.
  • 306 lifecycle Bun tests against the release binary.
  • lifecycle-session-recovery e2e under both the mux and supervisor runners.
  • computer pr review-status: CLEAR at a9bc571.

Hosted CI: 9 pass and 21 pending at note time; I did not wait for the macOS jobs. Hosted OS coverage at the previous green head is in the earlier note: macOS 15.8.2 arm64, macOS 15.7.9 Intel, Ubuntu 26.04.1, and Ubuntu 24.04.5 for Docker e2e.

Reviews: the persistent Codex reviewer is CLEAN at this head. I re-requested the Codex GitHub bot.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: a9bc571ee1

ℹ️ 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

Copy link
Copy Markdown

🛡️ Codex Security Review · Automatically triggered

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

Reviewed commit: a9bc571ee1

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.

…isor-opt-in

# Conflicts:
#	.github/workflows/lifecycle-supervisor.yml
#	docs/lifecycle-supervisor.md
#	docs/lifecycle.md
#	docs/reference/v5-model-coverage.md
#	packages/lifecycle-supervisor/Cargo.toml
#	packages/lifecycle-supervisor/README.md
#	packages/lifecycle-supervisor/src/main.rs
#	packages/lifecycle-supervisor/src/os.rs
#	packages/lifecycle-supervisor/src/protocol.rs
#	packages/lifecycle-supervisor/src/storage.rs
#	packages/lifecycle-supervisor/src/supervisor.rs
#	packages/lifecycle-supervisor/tests/fake_caller.rs
#	scripts/lib/tla-runtime-models.ts
@roodboi

roodboi commented Nov 15, 2026

Copy link
Copy Markdown
Contributor Author

@codex review

@roodboi

roodboi commented Nov 15, 2026

Copy link
Copy Markdown
Contributor Author

Ready for lead: 897cb3e

A normal merge of next at 34b5053 (#802 squashed as 870ca12, #860, #818) into a9bc571, the previous Ready head.

Squash resolution: 13 conflicts, all in files #802 touched (the crate, the supervisor docs, the model registry and coverage doc, the workflow).

Generated files: I regenerated them; none changed. That covers docs:cli-reference, scripts/generate-machine-output-reference.ts and generate:agent-plugins (the diagnose skill's error-code reference). The v5 model-coverage doc has no generator, and it matches #811's reviewed copy.

What I ran (Linux 6.8 x86_64):

  • Tests: tests/machine-output-contract.test.ts, tests/sync-spawn-bound.test.ts and tests/tla-runtime-models.test.ts, 269 pass.
  • Typecheck; build, config compiler and all 8 check:native-plan-cli acceptance scripts.
  • Rust: fmt; all-feature Clippy with warnings denied for Linux, aarch64-apple-darwin and x86_64-apple-darwin; 13 unit, 54 fake-caller, 18 incremental and 2 crash-checkpoint tests.
  • 306 lifecycle Bun tests against the release binary.
  • lifecycle-session-recovery e2e under both the mux and supervisor runners.
  • computer pr review-status: CLEAR at 897cb3e.

Hosted CI: 8 pass and 22 pending at note time. I did not wait for the queued macOS jobs.

Review: the persistent Codex reviewer is CLEAN at this head. It verified the patch-equivalence proof and checked #860/#818 for interactions. I re-requested the Codex GitHub bot.

Next: #821 follows once this lands (it merges next again). I'm starting the follow-up PR for the open review findings (rounds 4 to 6) now.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: 897cb3e149

ℹ️ 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

Copy link
Copy Markdown

🛡️ Codex Security Review · Automatically triggered

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

Reviewed commit: 897cb3e149

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
roodboi merged commit 3ed2644 into next Nov 15, 2026
33 checks passed
@roodboi
roodboi deleted the feat/lifecycle-supervisor-opt-in branch November 15, 2026 14:07
roodboi added a commit that referenced this pull request Nov 15, 2026
…econcile

Brings in next at 081a526 (#811 supervisor opt-in runner, #863 candidate launcher names HACK-2251, #808 desktop Logs tab). No conflicts. The CLI reference, machine-output table and error-code reference regenerate unchanged; E_DAEMON_SERVICE kept.

#863 changes which launcher printed commands name and the candidate update refusal; it does not change the executing-CLI identity, the service program checks, durability or the post-update binding, and a candidate install is still refused before any install or reconcile. #811's supervisor reads process identities through process-tree.ts and runs its own sibling binary; it does not use this PR's ps/lsof helpers, process-ancestry or the orphan sweep.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
roodboi added a commit that referenced this pull request Nov 15, 2026
Resolve conflicts with #811: scripts/lib/tla-runtime-models.ts keeps both the
autostart-start-stop and lifecycle-controller contracts; getting-started keeps
both paragraphs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
roodboi added a commit that referenced this pull request Nov 15, 2026
…nner

#811's opt-in `lifecycle.runner: "supervisor"` runs its companion binary
even with no hooks or processes, so a runner-only project passed admission
and the login child executed the supervisor preflight. Refuse any runner
other than the default "mux" at admission, before a claim or dispatch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant