From 59bfaabcb52b5fc4e77228efdd2aaad97ae45ab5 Mon Sep 17 00:00:00 2001
From: nullStack65 <nullStack65@users.noreply.github.com>
Date: Thu, 1 Oct 2026 07:14:55 -0400
Subject: [PATCH] feat(lifecycle): detached handoff supervisor with OS-owned
 callback

An agent running inside T3 cannot upgrade T3: the lifecycle action kills the
agent before it can report back. This adds a detached handoff that moves the
action to an OS-owned supervisor whose lifetime is independent of T3.

- handwritten envelope (owner-private, credentials refused) describing the
  originating thread, command, wait target, relaunch, readiness and callback;
- macOS: transient per-handoff LaunchAgent; Windows: transient current-user
  Scheduled Task (InteractiveToken, LeastPrivilege, one-shot);
- explicit state machine PREPARED..COMPLETE/FAILED, single-run claim, and
  terminal-result idempotency that refuses to re-run the destructive command;
- independence proof (direct parent pid 1, no initiator ancestor) required
  before the initiator may stop T3;
- callback contract: local result envelope + GitHub receipt; no state.sqlite
  writes, no fabricated orchestration events, no copied credentials.

Zero-dependency ESM under scripts/lifecycle-handoff with unit tests and a real
launchd fixture (fake parent exits, supervisor survives, runs a harmless
command, relaunches a fake service, calls back once, unregisters itself).

Non-overlapping with the Windows SCM lifecycle work on PR #10.
---
 docs/internals/lifecycle-handoff.md           | 147 ++++++++
 scripts/lifecycle-handoff/README.md           |  69 ++++
 scripts/lifecycle-handoff/fixtures/apply.mjs  |   3 +
 .../fixtures/fake-parent.mjs                  |  44 +++
 .../fixtures/fake-service.mjs                 |   4 +
 scripts/lifecycle-handoff/handoff.mjs         | 225 ++++++++++++
 scripts/lifecycle-handoff/lib/envelope.mjs    | 194 ++++++++++
 scripts/lifecycle-handoff/lib/platform.mjs    | 206 +++++++++++
 scripts/lifecycle-handoff/lib/process.mjs     |  78 ++++
 scripts/lifecycle-handoff/lib/run.mjs         | 334 ++++++++++++++++++
 scripts/lifecycle-handoff/lib/state.mjs       |  69 ++++
 scripts/lifecycle-handoff/supervisor.mjs      |  90 +++++
 .../lifecycle-handoff/test/envelope.test.mjs  |  60 ++++
 .../test/fixture.integration.test.mjs         | 106 ++++++
 scripts/lifecycle-handoff/test/run.test.mjs   | 122 +++++++
 15 files changed, 1751 insertions(+)
 create mode 100644 docs/internals/lifecycle-handoff.md
 create mode 100644 scripts/lifecycle-handoff/README.md
 create mode 100644 scripts/lifecycle-handoff/fixtures/apply.mjs
 create mode 100644 scripts/lifecycle-handoff/fixtures/fake-parent.mjs
 create mode 100644 scripts/lifecycle-handoff/fixtures/fake-service.mjs
 create mode 100755 scripts/lifecycle-handoff/handoff.mjs
 create mode 100644 scripts/lifecycle-handoff/lib/envelope.mjs
 create mode 100644 scripts/lifecycle-handoff/lib/platform.mjs
 create mode 100644 scripts/lifecycle-handoff/lib/process.mjs
 create mode 100644 scripts/lifecycle-handoff/lib/run.mjs
 create mode 100644 scripts/lifecycle-handoff/lib/state.mjs
 create mode 100755 scripts/lifecycle-handoff/supervisor.mjs
 create mode 100644 scripts/lifecycle-handoff/test/envelope.test.mjs
 create mode 100644 scripts/lifecycle-handoff/test/fixture.integration.test.mjs
 create mode 100644 scripts/lifecycle-handoff/test/run.test.mjs

diff --git a/docs/internals/lifecycle-handoff.md b/docs/internals/lifecycle-handoff.md
new file mode 100644
index 000000000000..8706524a3c78
--- /dev/null
+++ b/docs/internals/lifecycle-handoff.md
@@ -0,0 +1,147 @@
+# Detached lifecycle handoff
+
+A lifecycle action that stops or replaces T3 (install, update, restart) cannot be
+performed by an agent running *inside* T3: the action kills the agent that is
+executing it, so the last step — reporting back — never runs. A **detached
+handoff** moves the action to an OS-owned helper whose lifetime is independent of
+T3, and gives that helper enough state to relaunch T3 and report the result into
+the thread that requested it.
+
+Implementation lives in [`scripts/lifecycle-handoff/`](../../scripts/lifecycle-handoff/README.md).
+
+## Execution model
+
+```
+initiating agent (inside T3)
+  ├─ writes a user-private envelope            PREPARED
+  ├─ registers a transient OS job              DETACHED
+  └─ proves the helper is OS-owned, then quits T3
+                     │
+OS-owned supervisor (launchd / Task Scheduler)
+  ├─ verifies its own ancestry
+  ├─ waits for the initiating pid to exit      WAITING_FOR_EXIT
+  ├─ runs the lifecycle command                APPLYING
+  ├─ relaunches T3                             RELAUNCHING
+  ├─ waits for readiness                       WAITING_FOR_T3
+  ├─ runs an optional identity probe
+  ├─ delivers the callback + writes the result CALLBACK_PENDING
+  ├─ writes the terminal result envelope       COMPLETE / FAILED
+  └─ removes its own job registration
+```
+
+The supervisor never force-kills a process. If the waited-for pid is still alive
+when its bound expires, the handoff fails with `FAILED` and durable evidence
+rather than killing active work.
+
+## Supervisor mechanism
+
+**macOS** — a transient, per-handoff LaunchAgent in `~/Library/LaunchAgents`
+(`RunAtLoad`, `KeepAlive=false`, `ProcessType=Background`, log to the handoff
+directory). `launchctl bootstrap gui/<uid> <plist>` starts it; its direct parent
+is launchd (pid 1), so T3/Electron job-object teardown cannot reach it. It removes
+its own plist and `launchctl bootout`s itself as its last step.
+
+**Windows** — a transient current-user Scheduled Task created from an XML task
+definition (`InteractiveToken`, `LeastPrivilege`, one `TimeTrigger`,
+`StartWhenAvailable`). The Task Scheduler service owns the process, so it is not
+an Electron job-object child. `schtasks /Delete` removes it at the end. This path
+is implemented but **has not been executed on a Windows host** (see "Validation").
+
+`nohup`, `Start-Process`, and terminal detachment are deliberately not used:
+neither reliably escapes the parent job object on the platforms that matter.
+
+## Independence proof
+
+Before the initiating agent may quit T3 it must show the helper cannot be killed
+with T3. `handoff.mjs prepare` polls `launchctl print gui/<uid>/<label>` for the
+job pid, then walks the process parent chain:
+
+- `directParent === 1` (launchd) is required;
+- none of the helper's ancestors may be the initiator or its parent.
+
+The proof is stored in the handoff state file. If it fails, `prepare` boots the
+job out and throws — T3 is never stopped on an unproven helper.
+
+## Handoff envelope
+
+Written to `paths.dir/<handoffId>.envelope.json`, mode `0600`, in a `0700`
+directory (default `~/.t3/userdata/lifecycle-handoff`). Required fields:
+
+| Field | Meaning |
+| --- | --- |
+| `handoffId` | unique id; also the idempotency key |
+| `originating.threadId` / `projectId` / `machine` / `platform` | where to return |
+| `task.description` / `operation` | what is being done |
+| `command.argv` / `cwd` / `timeoutMs` | the lifecycle command |
+| `waitFor.pid` / `timeoutMs` | the process whose exit gates the command |
+| `relaunch.argv` | how to bring T3 back (empty = no relaunch) |
+| `readiness` | `none` \| `file` \| `pid` \| `tcp` \| `http` |
+| `identity.before` / `after` / `afterCommand` | expected and independently observed identity |
+| `callback` | `none` \| `github` \| `http` |
+| `paths` / `supervisor` | state, log, result, node and script paths |
+
+Credentials are rejected at write time: any key matching
+`token|secret|password|credential|bearer|api-key|private-key|cookie`, and any value
+shaped like a GitHub/Slack/OpenAI/JWT/PEM credential, fails the write.
+
+## Callback contract
+
+The supervisor always writes a terminal result envelope to `paths.result`. The
+callback is a best-effort *notification* layered on top:
+
+- `none` — result envelope only.
+- `github` — `gh issue comment <issue> --repo <repo> --body-file -` with a short
+  message. This is the durable cross-machine receipt when no T3 callback exists.
+- `http` — `POST` JSON `{handoffId, state, message}`.
+
+Message shape:
+
+```
+DETACHED HANDOFF COMPLETE <id>.
+Operation: <op> (exit=0).
+Before: {"version":"0.0.43"}
+After: "0.0.44"
+Result: <result path>
+```
+
+**Supported T3 callback: not available today.** T3 exposes no CLI or REST command
+that appends a message / starts a turn. The only supported mutation transport is
+the authenticated `/ws` `orchestration.dispatchCommand` (`thread.turn.start`),
+which needs an environment-session credential. The supervisor therefore does
+**not** touch `state.sqlite`, does not fabricate orchestration events, and does not
+copy auth tokens; it uses the result envelope + GitHub receipt fallback. When a
+supported callback endpoint exists, it slots in behind `callback.kind = "http"`
+without changing the lifecycle logic.
+
+## Security model
+
+- Envelope, state, log, and result files are owner-private (`0600`) in a `0700`
+  directory; the plist/task XML is `0600`.
+- No secrets in the envelope, argv, or logs; credential-shaped values are refused.
+- No root/SYSTEM task; the Windows task is `LeastPrivilege`, InteractiveToken.
+- No database access and no orchestration-event fabrication.
+- `KeepAlive=false` and a single-run claim (`<handoffId>.lock`) mean a crash cannot
+  become an endless restart loop.
+- The callback is attempted only after the result is durable, so a failed receipt
+  still leaves local evidence.
+
+## Recovery procedure
+
+1. `node scripts/lifecycle-handoff/handoff.mjs status --dir <dir> --id <id>` — read
+   `state` and `result`.
+2. Read `<dir>/<id>.log` and `<id>.state.json` — every transition is timestamped.
+3. `FAILED` results carry `failure.reason`; `command.stdoutTail/stderrTail`
+   preserve the command's own evidence.
+4. A terminal result means the destructive command will **not** run again; re-running
+   the same handoff id is a no-op. To retry deliberately, start a new handoff id.
+
+## Validation
+
+- Harmless fixture on macOS (real launchd): fake parent → prepare → parent exits →
+  supervisor survives → harmless command runs → fake service returns → callback
+  delivered exactly once → job unregistered → idempotent replay is a no-op.
+- Windows: implemented, not executed (no Windows host here).
+- A real-T3 restart smoke is intentionally **not** run from an active initiating
+  session, because it would terminate that session. The mechanism to do so is
+  proven by the fixture; run the real smoke only from an idle T3 with a bounded,
+  non-mutating command.
diff --git a/scripts/lifecycle-handoff/README.md b/scripts/lifecycle-handoff/README.md
new file mode 100644
index 000000000000..85e6f4ea7cda
--- /dev/null
+++ b/scripts/lifecycle-handoff/README.md
@@ -0,0 +1,69 @@
+# Detached lifecycle handoff
+
+Move a T3-stopping lifecycle action (install / update / restart) to an OS-owned
+supervisor that survives T3 exiting, then report the outcome back. Design and
+security model: [`docs/internals/lifecycle-handoff.md`](../../docs/internals/lifecycle-handoff.md).
+
+Zero dependencies; runs on the Node that is already present.
+
+## How an agent invokes it
+
+1. Write a request JSON (`command.argv` is the lifecycle command; `waitPid` is the
+   pid that must exit first — normally the T3 server):
+
+```json
+{
+  "threadId": "<t3 thread id>",
+  "projectId": "<project id>",
+  "operation": "update",
+  "description": "upgrade T3 to the next released build",
+  "agentPid": 1234,
+  "waitPid": 5678,
+  "command": { "argv": ["/path/to/t3", "update"], "timeoutMs": 900000 },
+  "relaunch": { "argv": ["open", "-a", "/Applications/T3 Code (Alpha).app"] },
+  "readiness": { "kind": "http", "url": "http://127.0.0.1:3773/health" },
+  "identity": { "before": { "version": "0.0.43" }, "afterCommand": { "argv": ["/path/to/t3", "--version"] } },
+  "callback": { "kind": "github", "github": { "repo": "nullStack65/t3code", "issue": 10 } }
+}
+```
+
+2. Prepare and verify independence. **Only quit T3 if this exits 0:**
+
+```bash
+node scripts/lifecycle-handoff/handoff.mjs prepare --request request.json
+```
+
+It prints the handoff id and the independence proof
+(`registration.proof.independent === true`, `directParent === 1`). If it fails, it
+has already unregistered the job — do not stop T3.
+
+3. Read progress:
+
+```bash
+node scripts/lifecycle-handoff/handoff.mjs status --dir <dir> --id <handoffId>
+```
+
+## Layout
+
+| File | Purpose |
+| --- | --- |
+| `handoff.mjs` | initiating-agent CLI (`prepare` / `status` / `verify`) |
+| `supervisor.mjs` | detached entry point started by launchd / Task Scheduler |
+| `lib/envelope.mjs` | envelope schema, secret refusal, state names |
+| `lib/process.mjs` | liveness and parent-chain independence proof |
+| `lib/platform.mjs` | LaunchAgent and Scheduled Task rendering + registration |
+| `lib/state.mjs` | atomic owner-only state writes, single-run claim |
+| `lib/run.mjs` | the state machine + readiness + callback |
+| `fixtures/` | harmless fake parent / command / service for the fixture test |
+
+## Tests
+
+```bash
+node --test test/envelope.test.mjs test/run.test.mjs          # unit
+node --test test/fixture.integration.test.mjs                 # real launchd (macOS)
+```
+
+The integration test runs a real LaunchAgent: a fake parent prepares a handoff,
+exits, and the detached supervisor is asserted to survive, run a harmless command,
+relaunch a fake service, call back exactly once, unregister itself, and refuse to
+re-run the destructive command on replay.
diff --git a/scripts/lifecycle-handoff/fixtures/apply.mjs b/scripts/lifecycle-handoff/fixtures/apply.mjs
new file mode 100644
index 000000000000..292d0b2ff575
--- /dev/null
+++ b/scripts/lifecycle-handoff/fixtures/apply.mjs
@@ -0,0 +1,3 @@
+// Harmless stand-in for the real lifecycle command.
+import { writeFileSync } from "node:fs";
+writeFileSync(process.argv[2], `applied:${new Date().toISOString()}\n`);
diff --git a/scripts/lifecycle-handoff/fixtures/fake-parent.mjs b/scripts/lifecycle-handoff/fixtures/fake-parent.mjs
new file mode 100644
index 000000000000..04de63718e83
--- /dev/null
+++ b/scripts/lifecycle-handoff/fixtures/fake-parent.mjs
@@ -0,0 +1,44 @@
+// Fake initiating agent. It prepares a real detached handoff for a harmless
+// command, then exits — exactly the moment the real agent would quit T3.
+import { spawnSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const [dir, port] = process.argv.slice(2);
+const here = dirname(fileURLToPath(import.meta.url));
+const handoffCli = join(here, "..", "handoff.mjs");
+mkdirSync(dir, { recursive: true });
+
+const request = {
+  threadId: "fixture-thread",
+  projectId: "fixture-project",
+  machine: "fixture-machine",
+  operation: "fixture-restart",
+  description: "harmless detached handoff fixture",
+  agentPid: process.pid,
+  waitPid: process.pid,
+  waitTimeoutMs: 30_000,
+  command: { argv: [process.execPath, join(here, "apply.mjs"), join(dir, "applied.marker")] },
+  relaunch: { argv: [process.execPath, join(here, "fake-service.mjs"), join(dir, "service-ready.marker")] },
+  readiness: { kind: "file", path: join(dir, "service-ready.marker"), timeoutMs: 30_000, pollMs: 200 },
+  identity: {
+    before: { version: "0.0.43" },
+    after: { version: "0.0.44" },
+    afterCommand: { argv: [process.execPath, "-e", "process.stdout.write('0.0.44')"] },
+  },
+  callback: { kind: "http", url: `http://127.0.0.1:${port}/callback` },
+};
+
+const requestPath = join(dir, "request.json");
+writeFileSync(requestPath, JSON.stringify(request, null, 2));
+const outcome = spawnSync(process.execPath, [handoffCli, "prepare", "--request", requestPath, "--dir", dir], {
+  encoding: "utf8",
+});
+process.stderr.write(outcome.stderr ?? "");
+if (outcome.status !== 0) {
+  process.stderr.write(`prepare failed: ${outcome.stdout}\n`);
+  process.exit(outcome.status ?? 1);
+}
+writeFileSync(join(dir, "parent-prepared.json"), outcome.stdout ?? "");
+// Exiting here releases the supervisor's wait, mirroring an agent quitting T3.
diff --git a/scripts/lifecycle-handoff/fixtures/fake-service.mjs b/scripts/lifecycle-handoff/fixtures/fake-service.mjs
new file mode 100644
index 000000000000..64d06517599f
--- /dev/null
+++ b/scripts/lifecycle-handoff/fixtures/fake-service.mjs
@@ -0,0 +1,4 @@
+// Harmless stand-in for relaunching T3: the "service" comes back and writes a
+// readiness marker the supervisor can observe.
+import { writeFileSync } from "node:fs";
+writeFileSync(process.argv[2], `ready:${process.pid}\n`);
diff --git a/scripts/lifecycle-handoff/handoff.mjs b/scripts/lifecycle-handoff/handoff.mjs
new file mode 100755
index 000000000000..06fcbc14fdc5
--- /dev/null
+++ b/scripts/lifecycle-handoff/handoff.mjs
@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+// Initiating-agent CLI for detached T3 lifecycle handoffs.
+//
+//   node handoff.mjs prepare --request <request.json> [--dir <dir>] [--no-register]
+//   node handoff.mjs status  --dir <dir> --id <handoffId>
+//   node handoff.mjs verify  --id <handoffId> --pid <pid>
+//
+// `prepare` writes the envelope, registers the OS-owned one-shot supervisor and
+// proves the supervisor is NOT a descendant of this process before returning.
+// Only after that proof may the caller quit T3.
+
+import { randomUUID } from "node:crypto";
+import { chmodSync, writeFileSync } from "node:fs";
+import { homedir, hostname, platform as osPlatform } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { parseEnvelope, SCHEMA_VERSION } from "./lib/envelope.mjs";
+import {
+  bootstrapLaunchd,
+  bootoutLaunchd,
+  launchdJobPid,
+  macPlistPath,
+  renderLaunchdPlist,
+  renderScheduledTaskXml,
+  registerWindowsTask,
+  runWindowsTask,
+  windowsTaskName,
+  shortId,
+  macLabel,
+} from "./lib/platform.mjs";
+import { independence } from "./lib/process.mjs";
+import { ensureDir, readJson, writeJsonPrivate } from "./lib/state.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export function defaultHandoffDir(baseDir = join(homedir(), ".t3", "userdata")) {
+  return join(baseDir, "lifecycle-handoff");
+}
+
+function parseFlags(argv) {
+  const flags = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) continue;
+    const key = token.slice(2);
+    const next = argv[index + 1];
+    if (next === undefined || next.startsWith("--")) {
+      flags[key] = true;
+    } else {
+      flags[key] = next;
+      index += 1;
+    }
+  }
+  return flags;
+}
+
+function newHandoffId() {
+  return `hlh-${new Date().toISOString().replace(/[^0-9]/g, "").slice(0, 14)}-${randomUUID().slice(0, 8)}`;
+}
+
+export function buildEnvelope({ request, handoffId = newHandoffId(), dir }) {
+  const paths = {
+    dir,
+    state: join(dir, `${handoffId}.state.json`),
+    log: join(dir, `${handoffId}.log`),
+    result: join(dir, `${handoffId}.result.json`),
+    ...(request.originating?.fromThread ? { fromThread: request.originating.fromThread } : {}),
+  };
+  const envelope = {
+    schemaVersion: SCHEMA_VERSION,
+    handoffId,
+    createdAt: new Date().toISOString(),
+    originating: {
+      threadId: request.threadId,
+      projectId: request.projectId,
+      machine: request.machine ?? hostname(),
+      platform: osPlatform(),
+      ...(Number.isInteger(request.agentPid) ? { agentPid: request.agentPid } : {}),
+    },
+    task: { description: request.description, operation: request.operation },
+    command: request.command,
+    waitFor: {
+      pid: Number.isInteger(request.waitPid) ? request.waitPid : process.ppid,
+      timeoutMs: request.waitTimeoutMs ?? 5 * 60 * 1000,
+      pollMs: request.waitPollMs ?? 500,
+    },
+    behavior: request.behavior ?? {},
+    relaunch: request.relaunch ?? { argv: [] },
+    readiness: request.readiness ?? { kind: "none" },
+    identity: request.identity ?? {},
+    callback: request.callback ?? { kind: "none" },
+    paths,
+    supervisor: { nodePath: process.execPath, scriptPath: join(HERE, "supervisor.mjs") },
+  };
+  return parseEnvelope(envelope);
+}
+
+async function registerMac(envelope, log) {
+  const uid = process.getuid();
+  const label = macLabel(envelope.handoffId);
+  const plistPath = macPlistPath(envelope.handoffId);
+  const plist = renderLaunchdPlist({
+    label,
+    nodePath: envelope.supervisor.nodePath,
+    scriptPath: envelope.supervisor.scriptPath,
+    envelopePath: join(envelope.paths.dir, `${envelope.handoffId}.envelope.json`),
+    logPath: envelope.paths.log,
+  });
+  writeFileSync(plistPath, plist, { mode: 0o600 });
+  chmodSync(plistPath, 0o600);
+  bootstrapLaunchd({ plistPath, uid });
+  log(`registered LaunchAgent ${label}`);
+
+  // Wait for launchd to actually place the job, then prove independence.
+  const deadline = Date.now() + 10_000;
+  let proof = null;
+  while (Date.now() < deadline) {
+    const pid = launchdJobPid({ label, uid });
+    if (Number.isInteger(pid)) {
+      proof = independence(pid, { forbiddenPids: [process.pid, process.ppid] });
+      if (proof.independent) return { mechanism: "launchd", proof, plistPath, uid };
+    }
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  bootoutLaunchd({ label, uid, plistPath });
+  throw new Error(`supervisor is not launchd-owned/independent: ${JSON.stringify(proof)}`);
+}
+
+async function registerWindows(envelope, log) {
+  const taskName = windowsTaskName(envelope.handoffId);
+  const xmlPath = join(envelope.paths.dir, `${envelope.handoffId}.task.xml`);
+  const xml = renderScheduledTaskXml({
+    taskName,
+    nodePath: envelope.supervisor.nodePath,
+    scriptPath: envelope.supervisor.scriptPath,
+    envelopePath: join(envelope.paths.dir, `${envelope.handoffId}.envelope.json`),
+    startBoundary: new Date(Date.now() + 60_000).toISOString(),
+  });
+  writeFileSync(xmlPath, xml, { mode: 0o600 });
+  registerWindowsTask({ taskName, xmlPath });
+  runWindowsTask({ taskName });
+  log(`registered scheduled task ${taskName}`);
+  return { mechanism: "schtasks", taskName, xmlPath };
+}
+
+async function prepare(flags) {
+  if (!flags.request) throw new Error("prepare requires --request <request.json>");
+  const request = readJson(flags.request);
+  if (!request) throw new Error(`request not found: ${flags.request}`);
+  const dir = flags.dir ? resolve(String(flags.dir)) : defaultHandoffDir();
+  ensureDir(dir);
+
+  const envelope = buildEnvelope({ request, dir, ...(flags.id ? { handoffId: String(flags.id) } : {}) });
+  const envelopePath = join(dir, `${envelope.handoffId}.envelope.json`);
+  writeJsonPrivate(envelopePath, envelope);
+  writeJsonPrivate(envelope.paths.state, {
+    handoffId: envelope.handoffId,
+    state: "PREPARED",
+    updatedAt: new Date().toISOString(),
+    transitions: [{ state: "PREPARED", at: new Date().toISOString() }],
+  });
+
+  const log = (line) => process.stderr.write(`[handoff] ${line}\n`);
+  if (flags["no-register"]) {
+    return { handoffId: envelope.handoffId, dir, envelopePath, registered: false };
+  }
+
+  const platform = envelope.originating.platform;
+  const registration =
+    platform === "darwin"
+      ? await registerMac(envelope, log)
+      : platform === "win32"
+        ? await registerWindows(envelope, log)
+        : (() => {
+            throw new Error(`detached handoff is unsupported on '${platform}'`);
+          })();
+
+  // Record the independence proof where a human/manager can read it.
+  const state = readJson(envelope.paths.state) ?? { handoffId: envelope.handoffId };
+  writeJsonPrivate(envelope.paths.state, { ...state, registration });
+  return { handoffId: envelope.handoffId, dir, envelopePath, registered: true, registration };
+}
+
+function status(flags) {
+  if (!flags.dir || !flags.id) throw new Error("status requires --dir and --id");
+  const dir = resolve(String(flags.dir));
+  const state = readJson(join(dir, `${flags.id}.state.json`));
+  const result = readJson(join(dir, `${flags.id}.result.json`));
+  process.stdout.write(`${JSON.stringify({ state, result }, null, 2)}\n`);
+}
+
+function verify(flags) {
+  if (!flags.id || !flags.pid) throw new Error("verify requires --id and --pid");
+  const proof = independence(Number.parseInt(String(flags.pid), 10), {
+    forbiddenPids: [process.pid, process.ppid],
+  });
+  process.stdout.write(`${JSON.stringify(proof, null, 2)}\n`);
+  if (!proof.independent) process.exitCode = 2;
+}
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  const flags = parseFlags(rest);
+  if (command === "prepare") {
+    const outcome = await prepare(flags);
+    process.stdout.write(`${JSON.stringify(outcome, null, 2)}\n`);
+    return;
+  }
+  if (command === "status") return status(flags);
+  if (command === "verify") return verify(flags);
+  process.stderr.write(
+    "usage: handoff.mjs <prepare|status|verify> [--request f] [--dir d] [--id i] [--pid p] [--no-register]\n",
+  );
+  process.exitCode = 1;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    process.stderr.write(`handoff failed: ${error?.stack ?? error}\n`);
+    process.exitCode = 1;
+  });
+}
+
+export { shortId };
diff --git a/scripts/lifecycle-handoff/lib/envelope.mjs b/scripts/lifecycle-handoff/lib/envelope.mjs
new file mode 100644
index 000000000000..a0b41a310a56
--- /dev/null
+++ b/scripts/lifecycle-handoff/lib/envelope.mjs
@@ -0,0 +1,194 @@
+// Handoff envelope: the complete, self-describing record an initiating agent
+// hands to an OS-owned detached supervisor. It deliberately carries identifiers
+// and commands only — never provider, browser, or API credentials.
+//
+// The schema is intentionally flat JSON so an operator or a future manager can
+// read a stalled handoff without any tooling.
+
+export const SCHEMA_VERSION = 1;
+
+/** Lifecycle states. Terminal states are COMPLETE and FAILED. */
+export const STATES = Object.freeze([
+  "PREPARED",
+  "DETACHED",
+  "WAITING_FOR_EXIT",
+  "APPLYING",
+  "RELAUNCHING",
+  "WAITING_FOR_T3",
+  "CALLBACK_PENDING",
+  "COMPLETE",
+  "FAILED",
+]);
+
+export const TERMINAL_STATES = Object.freeze(["COMPLETE", "FAILED"]);
+
+export class EnvelopeError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EnvelopeError";
+  }
+}
+
+// Key names that must never appear anywhere in an envelope.
+const FORBIDDEN_KEY =
+  /(token|secret|password|passwd|credential|bearer|api[-_]?key|private[-_]?key|cookie|session[-_]?key)/i;
+
+// Value shapes that are almost certainly credentials, regardless of key name.
+const SECRET_VALUE_PATTERNS = Object.freeze([
+  /\bgh[pousr]_[A-Za-z0-9]{16,}/,
+  /\bsk-[A-Za-z0-9_-]{16,}/,
+  /\bxox[abprs]-[A-Za-z0-9-]{10,}/,
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+  /\bBearer\s+[A-Za-z0-9._~+/-]{20,}=*/,
+  /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/, // JWT
+]);
+
+/** Recursively reject forbidden keys and credential-shaped values. */
+export function assertNoSecrets(value, at = "envelope") {
+  if (value === null || value === undefined) return;
+  if (typeof value === "string") {
+    for (const pattern of SECRET_VALUE_PATTERNS) {
+      if (pattern.test(value)) {
+        throw new EnvelopeError(`refusing to persist credential-shaped value at ${at}`);
+      }
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertNoSecrets(item, `${at}[${index}]`));
+    return;
+  }
+  if (typeof value === "object") {
+    for (const [key, child] of Object.entries(value)) {
+      if (FORBIDDEN_KEY.test(key)) {
+        throw new EnvelopeError(`refusing to persist forbidden key '${key}' at ${at}`);
+      }
+      assertNoSecrets(child, `${at}.${key}`);
+    }
+  }
+}
+
+function requireString(value, field) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new EnvelopeError(`${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+function requireArgv(value, field) {
+  if (!Array.isArray(value) || value.length === 0 || value.some((part) => typeof part !== "string")) {
+    throw new EnvelopeError(`${field} must be a non-empty array of strings`);
+  }
+  return value;
+}
+
+/** Like requireArgv but an empty list is valid (an optional step). */
+function optionalArgv(value, field) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value) || value.some((part) => typeof part !== "string")) {
+    throw new EnvelopeError(`${field} must be an array of strings`);
+  }
+  return value;
+}
+
+/**
+ * Validate the parts the supervisor actually depends on. Returns a frozen copy so
+ * a mutating caller cannot change a running plan.
+ */
+export function parseEnvelope(input) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    throw new EnvelopeError("envelope must be a JSON object");
+  }
+  if (input.schemaVersion !== SCHEMA_VERSION) {
+    throw new EnvelopeError(`unsupported envelope schemaVersion ${String(input.schemaVersion)}`);
+  }
+  assertNoSecrets(input);
+
+  const originating = input.originating ?? {};
+  const waitFor = input.waitFor ?? {};
+  const behavior = input.behavior ?? {};
+  const relaunch = input.relaunch ?? {};
+  const readiness = input.readiness ?? { kind: "none" };
+  const callback = input.callback ?? { kind: "none" };
+  const paths = input.paths ?? {};
+  const command = input.command ?? {};
+
+  const envelope = {
+    schemaVersion: SCHEMA_VERSION,
+    handoffId: requireString(input.handoffId, "handoffId"),
+    createdAt: requireString(input.createdAt, "createdAt"),
+    originating: {
+      threadId: requireString(originating.threadId, "originating.threadId"),
+      projectId: requireString(originating.projectId, "originating.projectId"),
+      machine: requireString(originating.machine, "originating.machine"),
+      platform: requireString(originating.platform, "originating.platform"),
+      ...(originating.agentPid === undefined ? {} : { agentPid: originating.agentPid }),
+    },
+    task: {
+      description: requireString(input.task?.description, "task.description"),
+      operation: requireString(input.task?.operation, "task.operation"),
+    },
+    command: {
+      argv: requireArgv(command.argv, "command.argv"),
+      ...(typeof command.cwd === "string" ? { cwd: command.cwd } : {}),
+      timeoutMs: Number.isFinite(command.timeoutMs) ? command.timeoutMs : 30 * 60 * 1000,
+    },
+    waitFor: {
+      pid: Number.isInteger(waitFor.pid) ? waitFor.pid : null,
+      timeoutMs: Number.isFinite(waitFor.timeoutMs) ? waitFor.timeoutMs : 5 * 60 * 1000,
+      pollMs: Number.isFinite(waitFor.pollMs) ? waitFor.pollMs : 500,
+    },
+    behavior: {
+      allowForceKill: behavior.allowForceKill === true,
+      maxRelaunchAttempts: Number.isInteger(behavior.maxRelaunchAttempts)
+        ? behavior.maxRelaunchAttempts
+        : 1,
+    },
+    relaunch: {
+      argv: optionalArgv(relaunch.argv, "relaunch.argv"),
+      timeoutMs: Number.isFinite(relaunch.timeoutMs) ? relaunch.timeoutMs : 60 * 1000,
+    },
+    readiness: {
+      kind: requireString(readiness.kind, "readiness.kind"),
+      timeoutMs: Number.isFinite(readiness.timeoutMs) ? readiness.timeoutMs : 3 * 60 * 1000,
+      pollMs: Number.isFinite(readiness.pollMs) ? readiness.pollMs : 1000,
+      ...(readiness.url !== undefined ? { url: readiness.url } : {}),
+      ...(readiness.host !== undefined ? { host: readiness.host } : {}),
+      ...(readiness.port !== undefined ? { port: readiness.port } : {}),
+      ...(readiness.path !== undefined ? { path: readiness.path } : {}),
+      ...(readiness.pidFile !== undefined ? { pidFile: readiness.pidFile } : {}),
+    },
+    identity: {
+      ...(input.identity?.before !== undefined ? { before: input.identity.before } : {}),
+      ...(input.identity?.after !== undefined ? { after: input.identity.after } : {}),
+      ...(input.identity?.afterCommand === undefined
+        ? {}
+        : {
+            afterCommand: {
+              argv: requireArgv(input.identity.afterCommand.argv, "identity.afterCommand.argv"),
+              timeoutMs: Number.isFinite(input.identity.afterCommand.timeoutMs)
+                ? input.identity.afterCommand.timeoutMs
+                : 30_000,
+            },
+          }),
+    },
+    callback: {
+      kind: requireString(callback.kind, "callback.kind"),
+      ...(callback.url !== undefined ? { url: callback.url } : {}),
+      ...(callback.github !== undefined ? { github: callback.github } : {}),
+      ...(callback.message !== undefined ? { message: callback.message } : {}),
+    },
+    paths: {
+      dir: requireString(paths.dir, "paths.dir"),
+      state: requireString(paths.state, "paths.state"),
+      log: requireString(paths.log, "paths.log"),
+      result: requireString(paths.result, "paths.result"),
+      ...(paths.fromThread !== undefined ? { fromThread: paths.fromThread } : {}),
+    },
+    supervisor: {
+      nodePath: requireString(input.supervisor?.nodePath, "supervisor.nodePath"),
+      scriptPath: requireString(input.supervisor?.scriptPath, "supervisor.scriptPath"),
+    },
+  };
+  return Object.freeze(envelope);
+}
diff --git a/scripts/lifecycle-handoff/lib/platform.mjs b/scripts/lifecycle-handoff/lib/platform.mjs
new file mode 100644
index 000000000000..141fc3a63971
--- /dev/null
+++ b/scripts/lifecycle-handoff/lib/platform.mjs
@@ -0,0 +1,206 @@
+// OS-owned supervisor registration.
+//
+// macOS  : a transient per-handoff LaunchAgent (launchd owns the process; its
+//          parent is pid 1, so T3/Electron job-object teardown cannot reach it).
+// Windows: a transient current-user Scheduled Task (InteractiveToken, no
+//          elevation, run once), which is a Task Scheduler-owned process rather
+//          than an Electron job-object child.
+//
+// `nohup`/`Start-Process` are deliberately NOT used: neither escapes the parent
+// job object on the platforms that matter.
+
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export class PlatformError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PlatformError";
+  }
+}
+
+function run(command, args) {
+  return execFileSync(command, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+}
+
+function runQuiet(command, args) {
+  try {
+    return { ok: true, stdout: run(command, args) };
+  } catch (error) {
+    return { ok: false, stdout: error.stdout ?? "", stderr: error.stderr ?? String(error) };
+  }
+}
+
+const SHORT_ID = /[^a-zA-Z0-9]/g;
+
+export function shortId(handoffId) {
+  return handoffId.replace(SHORT_ID, "").slice(0, 24);
+}
+
+/** XML-escape a value for a plist <string>. */
+function xml(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
+// ---------------------------------------------------------------------------
+// macOS / launchd
+// ---------------------------------------------------------------------------
+
+export const MAC_LABEL_PREFIX = "ai.closura.t3.handoff";
+
+export function macLabel(handoffId) {
+  return `${MAC_LABEL_PREFIX}.${shortId(handoffId)}`;
+}
+
+export function launchAgentsDir() {
+  return join(homedir(), "Library", "LaunchAgents");
+}
+
+export function macPlistPath(handoffId) {
+  return join(launchAgentsDir(), `${macLabel(handoffId)}.plist`);
+}
+
+export function renderLaunchdPlist({ label, nodePath, scriptPath, envelopePath, logPath }) {
+  const args = [nodePath, scriptPath, "--envelope", envelopePath];
+  return [
+    `<?xml version="1.0" encoding="UTF-8"?>`,
+    `<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">`,
+    `<plist version="1.0">`,
+    `<dict>`,
+    `  <key>Label</key>`,
+    `  <string>${xml(label)}</string>`,
+    `  <key>ProgramArguments</key>`,
+    `  <array>`,
+    ...args.map((arg) => `    <string>${xml(arg)}</string>`),
+    `  </array>`,
+    // Run once at bootstrap. Not KeepAlive: this is a one-shot supervisor, and a
+    // crash loop must not become an endless restart loop.
+    `  <key>RunAtLoad</key>`,
+    `  <true/>`,
+    `  <key>KeepAlive</key>`,
+    `  <false/>`,
+    `  <key>ProcessType</key>`,
+    `  <string>Background</string>`,
+    `  <key>ThrottleInterval</key>`,
+    `  <integer>10</integer>`,
+    `  <key>StandardOutPath</key>`,
+    `  <string>${xml(logPath)}</string>`,
+    `  <key>StandardErrorPath</key>`,
+    `  <string>${xml(logPath)}</string>`,
+    `</dict>`,
+    `</plist>`,
+    ``,
+  ].join("\n");
+}
+
+export function bootstrapLaunchd({ plistPath, uid }) {
+  const result = runQuiet("/bin/launchctl", ["bootstrap", `gui/${uid}`, plistPath]);
+  if (!result.ok) {
+    throw new PlatformError(`launchctl bootstrap failed: ${result.stderr?.trim() || result.stdout}`);
+  }
+  return result.stdout.trim();
+}
+
+/**
+ * The pid launchd reports for the job, or null if it is not currently running.
+ * Used to prove independence from the initiating process before T3 is stopped.
+ */
+export function launchdJobPid({ label, uid }) {
+  const result = runQuiet("/bin/launchctl", ["print", `gui/${uid}/${label}`]);
+  if (!result.ok) return null;
+  const match = /(?:^|\n)\s*pid\s*=\s*(\d+)\s*(?:\n|$)/.exec(result.stdout);
+  return match ? Number.parseInt(match[1], 10) : null;
+}
+
+export function bootoutLaunchd({ label, uid, plistPath }) {
+  runQuiet("/bin/launchctl", ["bootout", `gui/${uid}`, plistPath]);
+  runQuiet("/bin/launchctl", ["bootout", `gui/${uid}/${label}`]);
+}
+
+// ---------------------------------------------------------------------------
+// Windows / Task Scheduler
+// ---------------------------------------------------------------------------
+
+export const WIN_TASK_PREFIX = "ClosuraT3Handoff";
+
+export function windowsTaskName(handoffId) {
+  return `${WIN_TASK_PREFIX}-${shortId(handoffId)}`;
+}
+
+/**
+ * One-shot, current-user, non-elevated task. `<LogonType>InteractiveToken</LogonType>`
+ * runs the helper in the user's own session; the Task Scheduler service, not the
+ * Electron job object, owns its lifetime.
+ */
+export function renderScheduledTaskXml({ taskName, nodePath, scriptPath, envelopePath, startBoundary }) {
+  const command = `"${nodePath}" "${scriptPath}" --envelope "${envelopePath}"`;
+  return [
+    `<?xml version="1.0" encoding="UTF-16"?>`,
+    `<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">`,
+    `  <RegistrationInfo>`,
+    `    <Description>Transient T3 lifecycle handoff supervisor (one-shot)</Description>`,
+    `  </RegistrationInfo>`,
+    `  <Triggers>`,
+    `    <TimeTrigger>`,
+    `      <StartBoundary>${xml(startBoundary)}</StartBoundary>`,
+    `      <Enabled>true</Enabled>`,
+    `    </TimeTrigger>`,
+    `  </Triggers>`,
+    `  <Principals>`,
+    `    <Principal id="Author">`,
+    `      <LogonType>InteractiveToken</LogonType>`,
+    `      <RunLevel>LeastPrivilege</RunLevel>`,
+    `    </Principal>`,
+    `  </Principals>`,
+    `  <Settings>`,
+    `    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>`,
+    `    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>`,
+    `    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>`,
+    `    <AllowHardTerminate>true</AllowHardTerminate>`,
+    `    <StartWhenAvailable>true</StartWhenAvailable>`,
+    `    <ExecutionTimeLimit>PT2H</ExecutionTimeLimit>`,
+    `    <Enabled>true</Enabled>`,
+    `  </Settings>`,
+    `  <Actions Context="Author">`,
+    `    <Exec>`,
+    `      <Command>${xml(nodePath)}</Command>`,
+    `      <Arguments>"${xml(scriptPath)}" --envelope "${xml(envelopePath)}"</Arguments>`,
+    `    </Exec>`,
+    `  </Actions>`,
+    `</Task>`,
+    ``,
+  ].join("\r\n");
+}
+
+export function registerWindowsTask({ taskName, xmlPath }) {
+  const result = runQuiet("schtasks.exe", ["/Create", "/TN", taskName, "/XML", xmlPath, "/F"]);
+  if (!result.ok) {
+    throw new PlatformError(`schtasks /Create failed: ${result.stderr?.trim() || result.stdout}`);
+  }
+  return result.stdout.trim();
+}
+
+export function runWindowsTask({ taskName }) {
+  const result = runQuiet("schtasks.exe", ["/Run", "/TN", taskName]);
+  if (!result.ok) {
+    throw new PlatformError(`schtasks /Run failed: ${result.stderr?.trim() || result.stdout}`);
+  }
+  return result.stdout.trim();
+}
+
+export function deleteWindowsTask({ taskName }) {
+  runQuiet("schtasks.exe", ["/Delete", "/TN", taskName, "/F"]);
+}
+
+// ---------------------------------------------------------------------------
+
+/** Resolve the platform adapter for a Node-style platform string. */
+export function platformAdapter(platform) {
+  if (platform === "darwin") return "launchd";
+  if (platform === "win32") return "schtasks";
+  return undefined;
+}
diff --git a/scripts/lifecycle-handoff/lib/process.mjs b/scripts/lifecycle-handoff/lib/process.mjs
new file mode 100644
index 000000000000..5eb0b57672ad
--- /dev/null
+++ b/scripts/lifecycle-handoff/lib/process.mjs
@@ -0,0 +1,78 @@
+// Process liveness and parent-chain inspection. The whole point of the detached
+// handoff is that the helper's ancestry is independent of T3, so these helpers
+// exist to *prove* that rather than assume it.
+
+import { execFileSync } from "node:child_process";
+
+/** True when the pid exists and is signalable by this user. */
+export function isAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means the process exists but is owned by another user.
+    return error && error.code === "EPERM";
+  }
+}
+
+/** Parent pid of `pid`, or null when it is gone / unobtainable. */
+export function parentPid(pid) {
+  try {
+    const out = execFileSync("/bin/ps", ["-o", "ppid=", "-p", String(pid)], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const parsed = Number.parseInt(out.trim(), 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ancestor chain of `pid`, nearest first, stopping at pid 1 / launchd or when a
+ * loop or missing parent is seen.
+ */
+export function ancestry(pid) {
+  const chain = [];
+  const seen = new Set();
+  let current = pid;
+  while (Number.isInteger(current) && current > 1 && !seen.has(current)) {
+    seen.add(current);
+    const parent = parentPid(current);
+    if (parent === null) break;
+    chain.push(parent);
+    current = parent;
+  }
+  return chain;
+}
+
+/**
+ * Independent-from evidence for a supervisor the initiator just launched.
+ * `launchd`-owned means the direct parent is pid 1; anything else (a shell, an
+ * agent, an Electron helper) means it can still be inside T3's process tree or
+ * job object and must not be trusted for a lifecycle action.
+ */
+export function independence(pid, { forbiddenPids = [] } = {}) {
+  const chain = ancestry(pid);
+  const directParent = chain[0] ?? null;
+  const forbidden = new Set(forbiddenPids.filter((value) => Number.isInteger(value) && value > 0));
+  const collisions = chain.filter((ancestor) => forbidden.has(ancestor));
+  return {
+    pid,
+    alive: isAlive(pid),
+    directParent,
+    ancestry: chain,
+    /** launchd/systemd/SCM parent, or a short chain we cannot explain. */
+    osOwned: directParent === 1,
+    forbiddenPids: [...forbidden],
+    forbiddenAncestors: collisions,
+    independent: chain.length > 0 && collisions.length === 0 && directParent === 1,
+  };
+}
+
+/** Short human rendering of an ancestry proof for logs. */
+export function describeAncestry(pid) {
+  return `${pid} <- ${ancestry(pid).join(" <- ")}`;
+}
diff --git a/scripts/lifecycle-handoff/lib/run.mjs b/scripts/lifecycle-handoff/lib/run.mjs
new file mode 100644
index 000000000000..b9e93063917b
--- /dev/null
+++ b/scripts/lifecycle-handoff/lib/run.mjs
@@ -0,0 +1,334 @@
+// The supervisor state machine.
+//
+// Dependency-injected so the same code is exercised by unit tests (fake clock,
+// fake spawn) and by the real detached helper (real spawn, real launchd), and so
+// a future supported T3 callback endpoint can replace `deliverCallback` without
+// touching the lifecycle logic.
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { connect } from "node:net";
+
+import { STATES } from "./envelope.mjs";
+import { isAlive as realIsAlive } from "./process.mjs";
+import { claimRun, isTerminalResult, writeJsonPrivate } from "./state.mjs";
+
+const sleepDefault = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const TAIL_LIMIT = 4000;
+
+function tail(text) {
+  if (typeof text !== "string") return "";
+  return text.length <= TAIL_LIMIT ? text : text.slice(text.length - TAIL_LIMIT);
+}
+
+/** Spawn a command to completion with a hard timeout. Never force-kills a peer. */
+export function spawnCommand(argv, { cwd, timeoutMs, stdin } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(argv[0], argv.slice(1), {
+      cwd: cwd ?? process.cwd(),
+      stdio: [stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+    });
+    if (stdin !== undefined) {
+      child.stdin.end(stdin);
+    }
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+    }, timeoutMs ?? 30 * 60 * 1000);
+    child.stdout?.on("data", (chunk) => {
+      stdout = tail(stdout + chunk.toString());
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr = tail(stderr + chunk.toString());
+    });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      resolve({ code: null, signal: null, timedOut, stdout, stderr: tail(`${stderr}${error.message}`) });
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      resolve({ code, signal, timedOut, stdout, stderr });
+    });
+  });
+}
+
+/** Poll a readiness condition until it holds or the bound expires. */
+export async function waitReady(readiness, { isAlive = realIsAlive, sleep = sleepDefault, log } = {}) {
+  const deadline = Date.now() + (readiness.timeoutMs ?? 180_000);
+  const pollMs = readiness.pollMs ?? 1000;
+  for (;;) {
+    if (await probeReadiness(readiness, { isAlive })) return true;
+    if (Date.now() >= deadline) return false;
+    await sleep(pollMs);
+  }
+}
+
+async function probeReadiness(readiness, { isAlive }) {
+  try {
+    switch (readiness.kind) {
+      case "none":
+        return true;
+      case "file":
+        return typeof readiness.path === "string" && existsSync(readiness.path);
+      case "pid":
+        return Number.isInteger(readiness.pid) ? isAlive(readiness.pid) : false;
+      case "tcp":
+        return await probeTcp(readiness.host ?? "127.0.0.1", readiness.port);
+      case "http": {
+        const response = await fetch(readiness.url, { signal: AbortSignal.timeout(3000) });
+        return response.ok;
+      }
+      default:
+        return false;
+    }
+  } catch {
+    return false;
+  }
+}
+
+function probeTcp(host, port) {
+  return new Promise((resolve) => {
+    const socket = connect({ host, port });
+    const done = (ok) => {
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.setTimeout(1500);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+  });
+}
+
+function githubReceipt(callback, result) {
+  const { repo, issue } = callback.github ?? {};
+  const body = renderCallbackMessage(result);
+  return { argv: ["gh", "issue", "comment", String(issue), "--repo", String(repo), "--body-file", "-"], stdin: body };
+}
+
+/** Short, stable callback text. Safe to paste into a thread or a hub comment. */
+export function renderCallbackMessage(result) {
+  const lines = [
+    `DETACHED HANDOFF ${result.state} ${result.handoffId}.`,
+    `Operation: ${result.task.operation} (exit=${result.command?.code ?? "n/a"}${result.command?.timedOut ? ", timed-out" : ""}).`,
+    `Before: ${JSON.stringify(result.identity?.before ?? "unknown")}`,
+    `After: ${JSON.stringify(result.identity?.observedAfter ?? "unknown")}`,
+    `Result: ${result.paths?.result}`,
+  ];
+  if (result.githubReceiptUrl) lines.push(`Receipt: ${result.githubReceiptUrl}`);
+  return lines.join("\n");
+}
+
+/** Default callback: local result envelope (already written) + optional receipt. */
+export async function deliverCallback(envelope, result, deps) {
+  const kind = envelope.callback.kind;
+  if (kind === "none") return { ok: true, detail: "no external callback configured" };
+  if (kind === "github") {
+    const { argv, stdin } = githubReceipt(envelope.callback, result);
+    const outcome = await deps.spawnCommand(argv, { timeoutMs: 30_000, stdin });
+    return {
+      ok: outcome.code === 0,
+      detail: outcome.code === 0 ? "github receipt posted" : `gh exited ${outcome.code}: ${outcome.stderr}`,
+      url: extractUrl(outcome.stdout),
+    };
+  }
+  if (kind === "http") {
+    try {
+      const response = await fetch(envelope.callback.url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ handoffId: result.handoffId, state: result.state, message: renderCallbackMessage(result) }),
+        signal: AbortSignal.timeout(10_000),
+      });
+      return { ok: response.ok, detail: `http ${response.status}` };
+    } catch (error) {
+      return { ok: false, detail: `http callback failed: ${error.message}` };
+    }
+  }
+  return { ok: false, detail: `unsupported callback kind '${kind}'` };
+}
+
+function extractUrl(text) {
+  const match = /https?:\/\/\S+/.exec(text ?? "");
+  return match ? match[0] : undefined;
+}
+
+/**
+ * Run one handoff to a terminal state. Returns the result envelope.
+ *
+ * Ordering guarantees:
+ *  - the destructive command is skipped when a terminal result already exists;
+ *  - the command never runs before the waited-for pid is gone;
+ *  - the result is persisted before the callback is attempted, so an external
+ *    receipt failure still leaves durable local evidence.
+ */
+export async function supervise(envelope, deps = {}) {
+  const isAlive = deps.isAlive ?? realIsAlive;
+  const sleep = deps.sleep ?? sleepDefault;
+  const now = deps.now ?? (() => new Date().toISOString());
+  const spawnCommandFn = deps.spawnCommand ?? spawnCommand;
+  const waitReadyFn = deps.waitReady ?? waitReady;
+  const deliverCallbackFn = deps.deliverCallback ?? deliverCallback;
+  const cleanup = deps.cleanup ?? (async () => {});
+  const log = deps.log ?? (() => {});
+
+  const result = {
+    schemaVersion: envelope.schemaVersion,
+    handoffId: envelope.handoffId,
+    state: "PREPARED",
+    task: envelope.task,
+    originating: envelope.originating,
+    identity: { ...envelope.identity },
+    paths: envelope.paths,
+    startedAt: envelope.createdAt,
+    updatedAt: now(),
+    transitions: [],
+    command: null,
+    relaunch: null,
+    readiness: null,
+    callback: null,
+    githubReceiptUrl: undefined,
+    supervisorPid: process.pid,
+  };
+
+  const persist = (state, extra = {}) => {
+    result.state = state;
+    result.updatedAt = now();
+    result.transitions.push({ state, at: result.updatedAt });
+    Object.assign(result, extra);
+    writeJsonPrivate(envelope.paths.state, result);
+    log(`[${state}] ${envelope.handoffId}`);
+  };
+
+  const fail = async (reason, extra = {}) => {
+    result.failure = { reason, at: now() };
+    persist("FAILED", extra);
+    writeJsonPrivate(envelope.paths.result, result);
+    try {
+      result.callback = await deliverCallbackFn(envelope, result, { spawnCommand: spawnCommandFn });
+    } catch (error) {
+      result.callback = { ok: false, detail: `callback threw: ${error.message}` };
+      writeJsonPrivate(envelope.paths.result, result);
+    }
+    await safeCleanup(cleanup, log);
+    return result;
+  };
+
+  // --- idempotency -----------------------------------------------------------
+  const previous = deps.previousResult;
+  if (isTerminalResult(previous)) {
+    log(`already terminal (${previous.state}); refusing to re-run destructive command`);
+    result.state = previous.state;
+    result.transitions = previous.transitions ?? [];
+    result.skippedBecauseTerminal = true;
+    writeJsonPrivate(envelope.paths.state, result);
+    await safeCleanup(cleanup, log);
+    return result;
+  }
+
+  const claim = claimRun(envelope.paths.dir, envelope.handoffId, { pid: process.pid, isAlive, now });
+  if (!claim.claimed) {
+    log(`another supervisor (pid ${claim.owner?.pid}) owns ${envelope.handoffId}; exiting`);
+    result.state = claim.owner?.state ?? "DETACHED";
+    result.skippedBecauseClaimed = true;
+    writeJsonPrivate(envelope.paths.state, result);
+    return result;
+  }
+
+  persist("DETACHED", { detachment: deps.detachment ?? null });
+
+  // --- wait for the initiating process to exit -------------------------------
+  const waitPid = envelope.waitFor.pid;
+  if (Number.isInteger(waitPid)) {
+    persist("WAITING_FOR_EXIT");
+    const deadline = Date.now() + envelope.waitFor.timeoutMs;
+    while (isAlive(waitPid)) {
+      if (Date.now() >= deadline) {
+        return fail(`initiating pid ${waitPid} still alive after ${envelope.waitFor.timeoutMs}ms (not force-killed)`);
+      }
+      await sleep(envelope.waitFor.pollMs);
+    }
+    log(`initiating pid ${waitPid} exited`);
+  }
+
+  // --- apply the lifecycle command ------------------------------------------
+  persist("APPLYING");
+  const commandOutcome = await spawnCommandFn(envelope.command.argv, {
+    cwd: envelope.command.cwd,
+    timeoutMs: envelope.command.timeoutMs,
+  });
+  result.command = {
+    argv: envelope.command.argv,
+    code: commandOutcome.code,
+    signal: commandOutcome.signal,
+    timedOut: commandOutcome.timedOut,
+    stdoutTail: commandOutcome.stdout,
+    stderrTail: commandOutcome.stderr,
+  };
+  if (commandOutcome.timedOut) return fail("lifecycle command timed out");
+  if (commandOutcome.code !== 0) return fail(`lifecycle command exited ${commandOutcome.code}`);
+
+  // --- relaunch --------------------------------------------------------------
+  if (envelope.relaunch.argv.length > 0) {
+    persist("RELAUNCHING");
+    let attempt = 0;
+    let launched = false;
+    while (attempt < envelope.behavior.maxRelaunchAttempts && !launched) {
+      attempt += 1;
+      const outcome = await spawnCommandFn(envelope.relaunch.argv, { timeoutMs: envelope.relaunch.timeoutMs });
+      result.relaunch = { argv: envelope.relaunch.argv, attempt, code: outcome.code, timedOut: outcome.timedOut, stderrTail: outcome.stderr };
+      if (outcome.code === 0 && !outcome.timedOut) launched = true;
+    }
+    if (!launched) return fail("relaunch command failed within its attempt bound");
+  }
+
+  // --- wait for readiness ----------------------------------------------------
+  persist("WAITING_FOR_T3");
+  const ready = await waitReadyFn(envelope.readiness, { isAlive, sleep, log });
+  result.readiness = { ...envelope.readiness, ready };
+  if (!ready) return fail("T3 did not reach its readiness condition within the bound");
+
+  // --- independently verify the post-identity --------------------------------
+  if (envelope.identity.afterCommand) {
+    const identityOutcome = await spawnCommandFn(envelope.identity.afterCommand.argv, {
+      timeoutMs: envelope.identity.afterCommand.timeoutMs,
+    });
+    result.identity.observedAfter = identityOutcome.stdout?.trim() || identityOutcome.stderr?.trim() || null;
+    result.identity.observedAfterCode = identityOutcome.code;
+  }
+
+  // --- callback --------------------------------------------------------------
+  persist("CALLBACK_PENDING");
+  // The notification describes the finished operation, not the in-flight
+  // callback step, so render the message as the terminal success state while
+  // the durable transition log still records CALLBACK_PENDING -> COMPLETE.
+  const completed = { ...result, state: "COMPLETE" };
+  // Durable pre-callback evidence lives beside the result, never at the result
+  // path itself: the result path is the terminal record readers may trust.
+  writeJsonPrivate(`${envelope.paths.result}.pending`, completed);
+  try {
+    result.callback = await deliverCallbackFn(envelope, completed, { spawnCommand: spawnCommandFn });
+    if (result.callback?.url) result.githubReceiptUrl = result.callback.url;
+  } catch (error) {
+    result.callback = { ok: false, detail: `callback threw: ${error.message}` };
+  }
+
+  persist("COMPLETE");
+  writeJsonPrivate(envelope.paths.result, result);
+  await safeCleanup(cleanup, log);
+  return result;
+}
+
+async function safeCleanup(cleanup, log) {
+  try {
+    await cleanup();
+  } catch (error) {
+    log(`cleanup failed (non-fatal): ${error.message}`);
+  }
+}
+
+export { STATES };
diff --git a/scripts/lifecycle-handoff/lib/state.mjs b/scripts/lifecycle-handoff/lib/state.mjs
new file mode 100644
index 000000000000..5615b7c0ff17
--- /dev/null
+++ b/scripts/lifecycle-handoff/lib/state.mjs
@@ -0,0 +1,69 @@
+// Durable, user-private state for a handoff. Every transition is written before
+// the work it describes, so a manager reading a half-finished handoff can tell
+// exactly where it stopped.
+
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import { STATES, TERMINAL_STATES } from "./envelope.mjs";
+
+export function ensureDir(dir) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+/** Atomic, owner-only JSON write (write temp, fsync, rename, fsync dir). */
+export function writeJsonPrivate(path, value) {
+  ensureDir(dirname(path));
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  const fd = openSync(tmp, "w", 0o600);
+  try {
+    writeFileSync(fd, `${JSON.stringify(value, null, 2)}\n`);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(tmp, path);
+  return path;
+}
+
+export function readJson(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Single-run claim. The first supervisor to create the lock owns the handoff;
+ * a second instance (launchd retry, manual rerun, login reload) refuses. A lock
+ * whose owner pid is gone is stale and may be reclaimed.
+ */
+export function claimRun(dir, handoffId, { pid, isAlive, now }) {
+  ensureDir(dir);
+  const lockPath = `${dir}/${handoffId}.lock`;
+  const existing = readJson(lockPath);
+  if (existing && !TERMINAL_STATES.includes(existing.state)) {
+    if (existing.pid === pid || isAlive(existing.pid)) {
+      return { claimed: false, lockPath, owner: existing };
+    }
+  }
+  try {
+    const fd = openSync(lockPath, "wx", 0o600);
+    closeSync(fd);
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+  }
+  writeJsonPrivate(lockPath, { handoffId, pid, claimedAt: now() });
+  return { claimed: true, lockPath };
+}
+
+export function isTerminalResult(result) {
+  return Boolean(result) && TERMINAL_STATES.includes(result.state);
+}
+
+export function assertKnownState(state) {
+  if (!STATES.includes(state)) throw new Error(`unknown handoff state '${state}'`);
+  return state;
+}
diff --git a/scripts/lifecycle-handoff/supervisor.mjs b/scripts/lifecycle-handoff/supervisor.mjs
new file mode 100755
index 000000000000..2697fc2dce78
--- /dev/null
+++ b/scripts/lifecycle-handoff/supervisor.mjs
@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// Detached handoff supervisor entry point.
+//
+// launchd (macOS) / Task Scheduler (Windows) start this file with the absolute
+// node path recorded in the envelope. It must not import anything from the T3
+// app bundle, must not read credentials, and must keep working after the T3
+// process that prepared the handoff is gone.
+
+import { appendFileSync, existsSync, rmSync } from "node:fs";
+
+import { parseEnvelope } from "./lib/envelope.mjs";
+import {
+  bootoutLaunchd,
+  deleteWindowsTask,
+  macPlistPath,
+  windowsTaskName,
+} from "./lib/platform.mjs";
+import { independence } from "./lib/process.mjs";
+import { supervise } from "./lib/run.mjs";
+import { readJson, writeJsonPrivate } from "./lib/state.mjs";
+
+function parseArgs(argv) {
+  const index = argv.indexOf("--envelope");
+  if (index === -1 || !argv[index + 1]) {
+    throw new Error("usage: supervisor.mjs --envelope <path>");
+  }
+  return { envelopePath: argv[index + 1] };
+}
+
+function makeLogger(logPath) {
+  return (line) => {
+    const stamp = new Date().toISOString();
+    try {
+      appendFileSync(logPath, `${stamp} ${line}\n`);
+    } catch {
+      // A logger failure must never abort the handoff.
+    }
+  };
+}
+
+function cleanupFor(envelope, uid) {
+  return async () => {
+    if (envelope.originating.platform === "darwin") {
+      const plistPath = macPlistPath(envelope.handoffId);
+      // Remove the plist first so a login reload cannot re-run the job; then
+      // ask launchd to unload it (this terminates the current process last).
+      if (existsSync(plistPath)) rmSync(plistPath, { force: true });
+      bootoutLaunchd({ label: macLabelFor(envelope.handoffId), uid, plistPath });
+      return;
+    }
+    if (envelope.originating.platform === "win32") {
+      deleteWindowsTask({ taskName: windowsTaskName(envelope.handoffId) });
+    }
+  };
+}
+
+function macLabelFor(handoffId) {
+  return `ai.closura.t3.handoff.${handoffId.replace(/[^a-zA-Z0-9]/g, "").slice(0, 24)}`;
+}
+
+async function main() {
+  const { envelopePath } = parseArgs(process.argv.slice(2));
+  const raw = readJson(envelopePath);
+  if (!raw) throw new Error(`envelope not found or unreadable: ${envelopePath}`);
+  const envelope = parseEnvelope(raw);
+  const log = makeLogger(envelope.paths.log);
+  const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+
+  log(`supervisor started pid=${process.pid} ancestry=${JSON.stringify(independence(process.pid).ancestry)}`);
+
+  const result = await supervise(envelope, {
+    log,
+    detachment: independence(process.pid, { forbiddenPids: [envelope.originating.agentPid].filter(Boolean) }),
+    previousResult: readJson(envelope.paths.result),
+    cleanup: cleanupFor(envelope, uid),
+  });
+
+  // Durable evidence survives even when the callback and cleanup both fail.
+  writeJsonPrivate(envelope.paths.result, result);
+  log(`supervisor finished state=${result.state}`);
+}
+
+main().catch((error) => {
+  process.exitCode = 1;
+  try {
+    process.stderr.write(`lifecycle-handoff supervisor failed: ${error?.stack ?? error}\n`);
+  } catch {
+    // ignore
+  }
+});
diff --git a/scripts/lifecycle-handoff/test/envelope.test.mjs b/scripts/lifecycle-handoff/test/envelope.test.mjs
new file mode 100644
index 000000000000..f984185766a1
--- /dev/null
+++ b/scripts/lifecycle-handoff/test/envelope.test.mjs
@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { assertNoSecrets, EnvelopeError, parseEnvelope, SCHEMA_VERSION } from "../lib/envelope.mjs";
+
+function validEnvelope(overrides = {}) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    handoffId: "hlh-test-0001",
+    createdAt: "2026-10-01T00:00:00.000Z",
+    originating: { threadId: "t1", projectId: "p1", machine: "mac", platform: "darwin" },
+    task: { description: "restart", operation: "restart" },
+    command: { argv: ["/bin/true"] },
+    waitFor: { pid: 1, timeoutMs: 1000 },
+    behavior: {},
+    relaunch: { argv: [] },
+    readiness: { kind: "none" },
+    identity: {},
+    callback: { kind: "none" },
+    paths: { dir: "/tmp/x", state: "/tmp/x/s.json", log: "/tmp/x/l.log", result: "/tmp/x/r.json" },
+    supervisor: { nodePath: "/usr/bin/node", scriptPath: "/s/supervisor.mjs" },
+    ...overrides,
+  };
+}
+
+test("accepts a minimal valid envelope", () => {
+  const envelope = parseEnvelope(validEnvelope());
+  assert.equal(envelope.handoffId, "hlh-test-0001");
+  assert.deepEqual(envelope.command.argv, ["/bin/true"]);
+});
+
+test("rejects forbidden credential keys anywhere", () => {
+  assert.throws(
+    () => assertNoSecrets({ nested: { authToken: "x" } }),
+    (error) => error instanceof EnvelopeError && /forbidden key/.test(error.message),
+  );
+});
+
+test("rejects credential-shaped values", () => {
+  for (const value of ["ghp_abcdefghijklmnopqrstuvwxyz0123", "Bearer abcdefghijklmnopqrstuvwx", "sk-abcdefghijklmnopqrst"]) {
+    assert.throws(() => assertNoSecrets({ note: value }), EnvelopeError, `expected rejection for ${value.slice(0, 8)}`);
+  }
+});
+
+test("rejects a missing required identifier", () => {
+  const broken = validEnvelope();
+  delete broken.originating.threadId;
+  assert.throws(() => parseEnvelope(broken), /originating.threadId/);
+});
+
+test("rejects an unknown schema version", () => {
+  assert.throws(() => parseEnvelope(validEnvelope({ schemaVersion: 99 })), /unsupported envelope schemaVersion/);
+});
+
+test("keeps an optional afterCommand for independent identity verification", () => {
+  const envelope = parseEnvelope(
+    validEnvelope({ identity: { afterCommand: { argv: ["t3", "--version"] } } }),
+  );
+  assert.deepEqual(envelope.identity.afterCommand.argv, ["t3", "--version"]);
+});
diff --git a/scripts/lifecycle-handoff/test/fixture.integration.test.mjs b/scripts/lifecycle-handoff/test/fixture.integration.test.mjs
new file mode 100644
index 000000000000..850180a26d9f
--- /dev/null
+++ b/scripts/lifecycle-handoff/test/fixture.integration.test.mjs
@@ -0,0 +1,106 @@
+// End-to-end detached-handoff fixture on a real macOS launchd.
+//
+// fake parent prepares a handoff for a harmless command and exits -> the
+// launchd-owned supervisor survives -> runs the harmless command -> "relaunches"
+// a fake service -> observes readiness -> calls back -> cleans up its job.
+
+import assert from "node:assert/strict";
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PARENT = join(HERE, "..", "fixtures", "fake-parent.mjs");
+const SUPERVISOR = join(HERE, "..", "supervisor.mjs");
+
+function runParent(dir, port) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [PARENT, dir, String(port)], { stdio: ["ignore", "pipe", "pipe"] });
+    let stderr = "";
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("close", (code) => resolve({ code, stderr }));
+  });
+}
+
+async function waitFor(predicate, { timeoutMs = 60_000, pollMs = 250 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const value = predicate();
+    if (value) return value;
+    if (Date.now() >= deadline) return null;
+    await new Promise((r) => setTimeout(r, pollMs));
+  }
+}
+
+const macOnly = process.platform === "darwin" ? test : test.skip;
+
+macOnly("survives the initiating process, completes, and calls back", { timeout: 120_000 }, async () => {
+  const dir = mkdtempSync(join(tmpdir(), "hlh-fixture-"));
+  const callbacks = [];
+  const server = createServer((request, response) => {
+    let body = "";
+    request.on("data", (chunk) => {
+      body += chunk.toString();
+    });
+    request.on("end", () => {
+      callbacks.push(body);
+      response.writeHead(200, { "content-type": "application/json" });
+      response.end("{}");
+    });
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const port = server.address().port;
+
+  try {
+    const parent = await runParent(dir, port);
+    assert.equal(parent.code, 0, `fake parent failed: ${parent.stderr}`);
+
+    const prepared = JSON.parse(readFileSync(join(dir, "parent-prepared.json"), "utf8"));
+    assert.equal(prepared.registered, true);
+    assert.equal(prepared.registration.mechanism, "launchd");
+    // The helper is launchd-owned (parent pid 1) and not a descendant of the initiator.
+    assert.equal(prepared.registration.proof.directParent, 1);
+    assert.equal(prepared.registration.proof.independent, true);
+
+    const resultPath = join(dir, `${prepared.handoffId}.result.json`);
+    const result = await waitFor(() => {
+      if (!existsSync(resultPath)) return null;
+      const parsed = JSON.parse(readFileSync(resultPath, "utf8"));
+      return parsed.state === "COMPLETE" || parsed.state === "FAILED" ? parsed : null;
+    });
+    assert.ok(result, "supervisor never produced a terminal result");
+
+    assert.equal(result.state, "COMPLETE", `unexpected failure: ${result.failure?.reason}`);
+    assert.equal(result.command.code, 0);
+    assert.equal(result.readiness.ready, true);
+    assert.equal(result.identity.observedAfter, "0.0.44");
+    assert.equal(result.callback.ok, true, `callback failed: ${result.callback.detail}`);
+    assert.equal(result.detachment.directParent ?? result.registration?.proof?.directParent ?? 1, 1);
+    assert.ok(existsSync(join(dir, "applied.marker")), "harmless lifecycle command never ran");
+    assert.ok(existsSync(join(dir, "service-ready.marker")), "fake service never came back");
+    assert.equal(callbacks.length, 1, "callback was not delivered exactly once");
+    assert.match(callbacks[0], /DETACHED HANDOFF COMPLETE/);
+
+    // The transient job removed its own registration.
+    const plist = join(process.env.HOME ?? "", "Library", "LaunchAgents", `ai.closura.t3.handoff.${prepared.handoffId.replace(/[^a-zA-Z0-9]/g, "").slice(0, 24)}.plist`);
+    const gone = await waitFor(() => !existsSync(plist), { timeoutMs: 15_000, pollMs: 250 });
+    assert.ok(gone, "LaunchAgent plist was not cleaned up");
+
+    // Idempotency: re-running the same handoff must not repeat the destructive command.
+    const markerBefore = readFileSync(join(dir, "applied.marker"), "utf8");
+    const rerun = spawnSync(process.execPath, [SUPERVISOR, "--envelope", join(dir, `${prepared.handoffId}.envelope.json`)], {
+      encoding: "utf8",
+      timeout: 30_000,
+    });
+    assert.equal(rerun.status, 0, rerun.stderr);
+    assert.equal(readFileSync(join(dir, "applied.marker"), "utf8"), markerBefore, "idempotent rerun re-ran the command");
+  } finally {
+    server.close();
+  }
+});
diff --git a/scripts/lifecycle-handoff/test/run.test.mjs b/scripts/lifecycle-handoff/test/run.test.mjs
new file mode 100644
index 000000000000..34c9fd363d29
--- /dev/null
+++ b/scripts/lifecycle-handoff/test/run.test.mjs
@@ -0,0 +1,122 @@
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+
+import { parseEnvelope, SCHEMA_VERSION } from "../lib/envelope.mjs";
+import { supervise } from "../lib/run.mjs";
+import { claimRun } from "../lib/state.mjs";
+
+function makeEnvelope(dir, overrides = {}) {
+  return parseEnvelope({
+    schemaVersion: SCHEMA_VERSION,
+    handoffId: `hlh-unit-${Math.random().toString(36).slice(2, 8)}`,
+    createdAt: new Date().toISOString(),
+    originating: { threadId: "t", projectId: "p", machine: "m", platform: process.platform },
+    task: { description: "unit", operation: "unit-op" },
+    command: { argv: ["node", "-e", "0"] },
+    waitFor: { pid: 4242, timeoutMs: 5000, pollMs: 1 },
+    behavior: {},
+    relaunch: { argv: [] },
+    readiness: { kind: "none" },
+    identity: {},
+    callback: { kind: "none" },
+    paths: {
+      dir,
+      state: join(dir, "state.json"),
+      log: join(dir, "log.log"),
+      result: join(dir, "result.json"),
+    },
+    supervisor: { nodePath: process.execPath, scriptPath: "/s/supervisor.mjs" },
+    ...overrides,
+  });
+}
+
+const noSleep = async () => {};
+
+test("runs the command only after the waited-for pid exits, then completes", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "hlh-unit-"));
+  const envelope = makeEnvelope(dir);
+  const calls = [];
+  let aliveChecks = 0;
+  const result = await supervise(envelope, {
+    isAlive: () => {
+      aliveChecks += 1;
+      return aliveChecks <= 2;
+    },
+    sleep: noSleep,
+    spawnCommand: async (argv) => {
+      calls.push(argv);
+      return { code: 0, stdout: "done", stderr: "", timedOut: false };
+    },
+    waitReady: async () => true,
+    deliverCallback: async () => ({ ok: true, detail: "stub" }),
+    cleanup: async () => {},
+  });
+  assert.equal(result.state, "COMPLETE");
+  assert.equal(result.command.code, 0);
+  assert.equal(calls.length, 1);
+  assert.deepEqual(
+    result.transitions.map((t) => t.state),
+    ["DETACHED", "WAITING_FOR_EXIT", "APPLYING", "WAITING_FOR_T3", "CALLBACK_PENDING", "COMPLETE"],
+  );
+});
+
+test("a terminal previous result prevents re-running the destructive command", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "hlh-unit-"));
+  const envelope = makeEnvelope(dir);
+  let spawned = 0;
+  const result = await supervise(envelope, {
+    isAlive: () => false,
+    sleep: noSleep,
+    previousResult: { state: "COMPLETE", transitions: [] },
+    spawnCommand: async () => {
+      spawned += 1;
+      return { code: 0, stdout: "", stderr: "", timedOut: false };
+    },
+    cleanup: async () => {},
+  });
+  assert.equal(result.skippedBecauseTerminal, true);
+  assert.equal(spawned, 0);
+});
+
+test("a non-zero lifecycle command fails with durable evidence", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "hlh-unit-"));
+  const envelope = makeEnvelope(dir);
+  const result = await supervise(envelope, {
+    isAlive: () => false,
+    sleep: noSleep,
+    spawnCommand: async () => ({ code: 1, stdout: "", stderr: "boom", timedOut: false }),
+    cleanup: async () => {},
+  });
+  assert.equal(result.state, "FAILED");
+  assert.match(result.failure.reason, /exited 1/);
+});
+
+test("an over-running initiating pid fails without force-killing anything", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "hlh-unit-"));
+  const envelope = makeEnvelope(dir, { waitFor: { pid: 4242, timeoutMs: 0, pollMs: 1 } });
+  let spawned = 0;
+  const result = await supervise(envelope, {
+    isAlive: () => true,
+    sleep: noSleep,
+    spawnCommand: async () => {
+      spawned += 1;
+      return { code: 0, stdout: "", stderr: "", timedOut: false };
+    },
+    cleanup: async () => {},
+  });
+  assert.equal(result.state, "FAILED");
+  assert.match(result.failure.reason, /still alive/);
+  assert.equal(spawned, 0);
+});
+
+test("a live claim refuses a second concurrent supervisor", () => {
+  const dir = mkdtempSync(join(tmpdir(), "hlh-unit-"));
+  const now = () => new Date().toISOString();
+  const first = claimRun(dir, "hlh-dup", { pid: process.pid, isAlive: () => true, now });
+  const second = claimRun(dir, "hlh-dup", { pid: 999_999, isAlive: () => true, now });
+  assert.equal(first.claimed, true);
+  assert.equal(second.claimed, false);
+});