Showing the changes to docs/architecture (1 of 12 files). Show all
Unified · Split
| @@ -32,17 +32,17 @@ the mismatch and action disappear. · 31 unmodified lines | ||
| 32 | 32 | |
| 33 | 33 | The server resolves its capability once at startup and publishes it in the environment descriptor. |
| 34 | 34 | |
| 35 | −| Advertised value | Process shape | Client behavior | | |
| 36 | −| ----------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | |
| 37 | −| `boot-service` | Linux server running under the T3-managed systemd user service | Call the update RPC; the service unit is replaced and restarted. | | |
| 38 | −| `respawn` | Published npm CLI running in the foreground on macOS or Linux | Call the update RPC; the process hands off to a detached replacement. | | |
| 39 | −| `desktop-managed` | Backend supervised by the desktop app | Tell the user to update the desktop app on the server machine. | | |
| 40 | −| absent | Older server, development checkout, Windows foreground process, or an unrecognized supervisor | Offer the exact manual relaunch command. | | |
| 35 | +| Advertised value | Process shape | Client behavior | | |
| 36 | +| ----------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | |
| 37 | +| `boot-service` | Server running under the T3-managed systemd user service or macOS LaunchAgent | Call the update RPC; the managed service switches runtime and restarts. | | |
| 38 | +| `respawn` | Published npm CLI running in the foreground on macOS or Linux | Call the update RPC; the process hands off to a detached replacement. | | |
| 39 | +| `desktop-managed` | Backend supervised by the desktop app | Tell the user to update the desktop app on the server machine. | | |
| 40 | +| absent | Older server, development checkout, Windows foreground process, or an unrecognized supervisor | Offer the exact manual relaunch command. | | |
| 41 | 41 | |
| 42 | 42 | Desktop ownership takes precedence over process-shape detection. A desktop-managed backend must |
| 43 | 43 | never spawn a second CLI server beside the app-owned process. Likewise, a process launched by an |
| 44 | −unrecognized systemd unit does not claim the foreground respawn path because its supervisor could | |
| 45 | −bring the old version back. | |
| 44 | +unrecognized systemd unit or marked LaunchAgent does not claim the foreground respawn path because | |
| 45 | +its supervisor could bring the old version back. | |
| 46 | 46 | |
| 47 | 47 | ## Update Flow |
| 48 | 48 | |
| @@ -56,7 +56,7 @@ flowchart TD · 7 unmodified lines | ||
| 56 | 56 | F --> G[Run version preflight] |
| 57 | 57 | G -->|fails| H[Remove failed runtime and keep current server] |
| 58 | 58 | G -->|passes| I{Handoff method} |
| 59 | − I -->|boot-service| J[Rewrite and restart T3 systemd unit] | |
| 59 | + I -->|boot-service| J[Switch runtime and restart managed service] | |
| 60 | 60 | I -->|respawn| K[Start delayed replacement and exit current process] |
| 61 | 61 | J --> L[Client reconnects] |
| 62 | 62 | K --> L |
| @@ -77,10 +77,11 @@ preflight also removes the candidate runtime so retrying the same version perfor · 14 unmodified lines | ||
| 77 | 77 | |
| 78 | 78 | ## Host Service Lifecycle |
| 79 | 79 | |
| 80 | −The systemd user service is a host lifecycle concern, not a T3 Connect resource. The standalone | |
| 81 | −`t3 service install`, `uninstall`, `update`, and `status` commands own it. Install and update both | |
| 82 | −reconcile the unit through `BootService`; running `npx t3@latest service update` therefore pins and | |
| 83 | −activates the latest CLI release without requiring a connected client. | |
| 80 | +The systemd user service or macOS LaunchAgent is a host lifecycle concern, not a T3 Connect | |
| 81 | +resource. The standalone `t3 service install`, `uninstall`, `update`, and `status` commands own it. | |
| 82 | +Install and update both reconcile the unit through `BootService`; running | |
| 83 | +`npx t3@latest service update` therefore pins and activates the latest CLI release without requiring | |
| 84 | +a connected client. | |
| 84 | 85 | |
| 85 | 86 | The `t3 connect` onboarding flow may offer service installation, but it calls the same reconciliation |
| 86 | 87 | operation as `t3 service install`. Connect logout only disables cloud access and clears its |
| @@ -88,9 +89,13 @@ authorization; it does not uninstall the host service. · 1 unmodified line | ||
| 88 | 89 | |
| 89 | 90 | ## Process Handoff |
| 90 | 91 | |
| 91 | −For `boot-service`, the server atomically rewrites the T3-managed user unit to point at the verified | |
| 92 | −runtime, reloads systemd, and restarts the unit. Reload and restart failures restore the previous | |
| 93 | −unit before returning an error. | |
| 92 | +For a systemd `boot-service`, the server atomically rewrites the T3-managed user unit to point at | |
| 93 | +the verified runtime, reloads systemd, and restarts the unit. Reload and restart failures restore | |
| 94 | +the previous unit before returning an error. | |
| 95 | + | |
| 96 | +For a macOS `boot-service`, the LaunchAgent always starts a stable entry path. The server atomically | |
| 97 | +switches that path to the verified runtime and asks launchd to restart the job. A rejected restart | |
| 98 | +restores the previous runtime link before returning an error. | |
| 94 | 99 | |
| 95 | 100 | For `respawn`, the server starts a detached, delayed replacement that replays the original CLI |
| 96 | 101 | arguments. It then acknowledges the request and schedules the current process to exit. The delays |