|
| 1 | +# Detached lifecycle handoff |
| 2 | + |
| 3 | +A lifecycle action that stops or replaces T3 (install, update, restart) cannot be |
| 4 | +performed by an agent running *inside* T3: the action kills the agent that is |
| 5 | +executing it, so the last step — reporting back — never runs. A **detached |
| 6 | +handoff** moves the action to an OS-owned helper whose lifetime is independent of |
| 7 | +T3, and gives that helper enough state to relaunch T3 and report the result into |
| 8 | +the thread that requested it. |
| 9 | + |
| 10 | +Implementation lives in [`scripts/lifecycle-handoff/`](../../scripts/lifecycle-handoff/README.md). |
| 11 | + |
| 12 | +## Execution model |
| 13 | + |
| 14 | +``` |
| 15 | +initiating agent (inside T3) |
| 16 | + ├─ writes a user-private envelope PREPARED |
| 17 | + ├─ registers a transient OS job DETACHED |
| 18 | + └─ proves the helper is OS-owned, then quits T3 |
| 19 | + │ |
| 20 | +OS-owned supervisor (launchd / Task Scheduler) |
| 21 | + ├─ verifies its own ancestry |
| 22 | + ├─ waits for the initiating pid to exit WAITING_FOR_EXIT |
| 23 | + ├─ runs the lifecycle command APPLYING |
| 24 | + ├─ relaunches T3 RELAUNCHING |
| 25 | + ├─ waits for readiness WAITING_FOR_T3 |
| 26 | + ├─ runs an optional identity probe |
| 27 | + ├─ delivers the callback + writes the result CALLBACK_PENDING |
| 28 | + ├─ writes the terminal result envelope COMPLETE / FAILED |
| 29 | + └─ removes its own job registration |
| 30 | +``` |
| 31 | + |
| 32 | +The supervisor never force-kills a process. If the waited-for pid is still alive |
| 33 | +when its bound expires, the handoff fails with `FAILED` and durable evidence |
| 34 | +rather than killing active work. |
| 35 | + |
| 36 | +## Supervisor mechanism |
| 37 | + |
| 38 | +**macOS** — a transient, per-handoff LaunchAgent in `~/Library/LaunchAgents` |
| 39 | +(`RunAtLoad`, `KeepAlive=false`, `ProcessType=Background`, log to the handoff |
| 40 | +directory). `launchctl bootstrap gui/<uid> <plist>` starts it; its direct parent |
| 41 | +is launchd (pid 1), so T3/Electron job-object teardown cannot reach it. It removes |
| 42 | +its own plist and `launchctl bootout`s itself as its last step. |
| 43 | + |
| 44 | +**Windows** — a transient current-user Scheduled Task created from an XML task |
| 45 | +definition (`InteractiveToken`, `LeastPrivilege`, one `TimeTrigger`, |
| 46 | +`StartWhenAvailable`). The Task Scheduler service owns the process, so it is not |
| 47 | +an Electron job-object child. `schtasks /Delete` removes it at the end. This path |
| 48 | +is implemented but **has not been executed on a Windows host** (see "Validation"). |
| 49 | + |
| 50 | +`nohup`, `Start-Process`, and terminal detachment are deliberately not used: |
| 51 | +neither reliably escapes the parent job object on the platforms that matter. |
| 52 | + |
| 53 | +## Independence proof |
| 54 | + |
| 55 | +Before the initiating agent may quit T3 it must show the helper cannot be killed |
| 56 | +with T3. `handoff.mjs prepare` polls `launchctl print gui/<uid>/<label>` for the |
| 57 | +job pid, then walks the process parent chain: |
| 58 | + |
| 59 | +- `directParent === 1` (launchd) is required; |
| 60 | +- none of the helper's ancestors may be the initiator or its parent. |
| 61 | + |
| 62 | +The proof is stored in the handoff state file. If it fails, `prepare` boots the |
| 63 | +job out and throws — T3 is never stopped on an unproven helper. |
| 64 | + |
| 65 | +## Handoff envelope |
| 66 | + |
| 67 | +Written to `paths.dir/<handoffId>.envelope.json`, mode `0600`, in a `0700` |
| 68 | +directory (default `~/.t3/userdata/lifecycle-handoff`). Required fields: |
| 69 | + |
| 70 | +| Field | Meaning | |
| 71 | +| --- | --- | |
| 72 | +| `handoffId` | unique id; also the idempotency key | |
| 73 | +| `originating.threadId` / `projectId` / `machine` / `platform` | where to return | |
| 74 | +| `task.description` / `operation` | what is being done | |
| 75 | +| `command.argv` / `cwd` / `timeoutMs` | the lifecycle command | |
| 76 | +| `waitFor.pid` / `timeoutMs` | the process whose exit gates the command | |
| 77 | +| `relaunch.argv` | how to bring T3 back (empty = no relaunch) | |
| 78 | +| `readiness` | `none` \| `file` \| `pid` \| `tcp` \| `http` | |
| 79 | +| `identity.before` / `after` / `afterCommand` | expected and independently observed identity | |
| 80 | +| `callback` | `none` \| `github` \| `http` | |
| 81 | +| `paths` / `supervisor` | state, log, result, node and script paths | |
| 82 | + |
| 83 | +Credentials are rejected at write time: any key matching |
| 84 | +`token|secret|password|credential|bearer|api-key|private-key|cookie`, and any value |
| 85 | +shaped like a GitHub/Slack/OpenAI/JWT/PEM credential, fails the write. |
| 86 | + |
| 87 | +## Callback contract |
| 88 | + |
| 89 | +The supervisor always writes a terminal result envelope to `paths.result`. The |
| 90 | +callback is a best-effort *notification* layered on top: |
| 91 | + |
| 92 | +- `none` — result envelope only. |
| 93 | +- `github` — `gh issue comment <issue> --repo <repo> --body-file -` with a short |
| 94 | + message. This is the durable cross-machine receipt when no T3 callback exists. |
| 95 | +- `http` — `POST` JSON `{handoffId, state, message}`. |
| 96 | + |
| 97 | +Message shape: |
| 98 | + |
| 99 | +``` |
| 100 | +DETACHED HANDOFF COMPLETE <id>. |
| 101 | +Operation: <op> (exit=0). |
| 102 | +Before: {"version":"0.0.43"} |
| 103 | +After: "0.0.44" |
| 104 | +Result: <result path> |
| 105 | +``` |
| 106 | + |
| 107 | +**Supported T3 callback: not available today.** T3 exposes no CLI or REST command |
| 108 | +that appends a message / starts a turn. The only supported mutation transport is |
| 109 | +the authenticated `/ws` `orchestration.dispatchCommand` (`thread.turn.start`), |
| 110 | +which needs an environment-session credential. The supervisor therefore does |
| 111 | +**not** touch `state.sqlite`, does not fabricate orchestration events, and does not |
| 112 | +copy auth tokens; it uses the result envelope + GitHub receipt fallback. When a |
| 113 | +supported callback endpoint exists, it slots in behind `callback.kind = "http"` |
| 114 | +without changing the lifecycle logic. |
| 115 | + |
| 116 | +## Security model |
| 117 | + |
| 118 | +- Envelope, state, log, and result files are owner-private (`0600`) in a `0700` |
| 119 | + directory; the plist/task XML is `0600`. |
| 120 | +- No secrets in the envelope, argv, or logs; credential-shaped values are refused. |
| 121 | +- No root/SYSTEM task; the Windows task is `LeastPrivilege`, InteractiveToken. |
| 122 | +- No database access and no orchestration-event fabrication. |
| 123 | +- `KeepAlive=false` and a single-run claim (`<handoffId>.lock`) mean a crash cannot |
| 124 | + become an endless restart loop. |
| 125 | +- The callback is attempted only after the result is durable, so a failed receipt |
| 126 | + still leaves local evidence. |
| 127 | + |
| 128 | +## Recovery procedure |
| 129 | + |
| 130 | +1. `node scripts/lifecycle-handoff/handoff.mjs status --dir <dir> --id <id>` — read |
| 131 | + `state` and `result`. |
| 132 | +2. Read `<dir>/<id>.log` and `<id>.state.json` — every transition is timestamped. |
| 133 | +3. `FAILED` results carry `failure.reason`; `command.stdoutTail/stderrTail` |
| 134 | + preserve the command's own evidence. |
| 135 | +4. A terminal result means the destructive command will **not** run again; re-running |
| 136 | + the same handoff id is a no-op. To retry deliberately, start a new handoff id. |
| 137 | + |
| 138 | +## Validation |
| 139 | + |
| 140 | +- Harmless fixture on macOS (real launchd): fake parent → prepare → parent exits → |
| 141 | + supervisor survives → harmless command runs → fake service returns → callback |
| 142 | + delivered exactly once → job unregistered → idempotent replay is a no-op. |
| 143 | +- Windows: implemented, not executed (no Windows host here). |
| 144 | +- A real-T3 restart smoke is intentionally **not** run from an active initiating |
| 145 | + session, because it would terminate that session. The mechanism to do so is |
| 146 | + proven by the fixture; run the real smoke only from an idle T3 with a bounded, |
| 147 | + non-mutating command. |
0 commit comments