relay-codex 0.5.3 → 0.6.1

package/README.md

@@ -65,6 +65,14 @@ relay attach --takeover SESSION_ID
 Accounts show their saved email addresses. The watch view updates only when local
 status changes; it uses no model allowance. The menu bar uses an icon and opens
 at Mac login. `relay menubar --no-startup --configure-only` disables login startup.
+Use a session's menu to switch accounts after its work finishes. Account menus can
+enable or disable future routing without stopping current tasks. Actions show
+their result, and stopped workers offer a restart.
+
+For tab completion in Zsh, run `source <(relay completion zsh)` after `compinit`.
+Bash users can run `source <(relay completion bash)`. Add the same line to your
+shell's startup file to keep it enabled. Relay completes its own commands and
+saved account/session names; arguments after `relay run --` use Codex's completion.
 
 ## What happens when something stops?
 

package/bin/relay.cjs

@@ -91,8 +91,9 @@ async function withSetupLock(state, operation) {
   finally { fs.rmSync(lock, { recursive: true, force: true }); }
 }
 
-function run(command, args) {
-  const result = spawnSync(command, args, { stdio: 'inherit' });
+function runSetup(command, args) {
+  // Setup chatter must not contaminate JSON or generated completion on stdout.
+  const result = spawnSync(command, args, { stdio: ['inherit', 2, 'inherit'] });
   if (result.error || result.status !== 0) throw new Error('Setup did not finish. Run Relay again to retry.');
 }
 
@@ -114,8 +115,8 @@ async function prepare(state) {
     }
     console.error('Preparing Relay for this Mac. This only happens on first use or after an update.');
     // Always retry dependency installation if a previous setup was interrupted.
-    run(python, ['-m', 'venv', path.join(destination, '.venv')]);
-    run(interpreter, ['-m', 'pip', 'install', '--disable-pip-version-check', '-r', path.join(destination, 'requirements.lock')]);
+    runSetup(python, ['-m', 'venv', path.join(destination, '.venv')]);
+    runSetup(interpreter, ['-m', 'pip', 'install', '--disable-pip-version-check', '-r', path.join(destination, 'requirements.lock')]);
     fs.writeFileSync(marker, JSON.stringify({ version: pkg.version }), { mode: 0o600 });
     return { interpreter, router: path.join(destination, 'router.py') };
   });
@@ -144,5 +145,5 @@ async function main() {
   process.off('SIGHUP', terminate);
 }
 
-module.exports = { stateDirectory, fingerprint, ownerAlive, withSetupLock, prepare };
+module.exports = { stateDirectory, fingerprint, ownerAlive, withSetupLock, prepare, runSetup };
 if (require.main === module) main().catch(error => { console.error(`relay: ${error.message}`); process.exitCode = 1; });

package/docs/commands.md

@@ -9,11 +9,21 @@ relay help workspace
 relay run --help
 relay run -- exec --help
 relay help codex resume
+relay completion zsh
+relay completion bash
 ```
 
 `relay run --help` shows the installed Codex command and flag list, followed by
 Relay's launch options. Put native arguments after `relay run --`.
 
+Enable tab completion with `source <(relay completion zsh)` after Zsh's `compinit`,
+or `source <(relay completion bash)` in Bash. Put that line in `.zshrc` or `.bashrc`
+to load it in new shells. Management choices come from Relay's parser and local
+saved metadata, including account labels/emails, sessions, profiles and workspaces.
+Native arguments use the installed Codex completion, loaded once per shell on
+first use; start a new shell after updating Codex to load its new completion.
+Completion does not read Keychain credentials, fetch allowance, or start a task.
+
 ## Accounts
 
 ```sh
@@ -99,6 +109,20 @@ allowance and does not fetch account allowance. `refresh` explicitly checks it.
 The menu uses one local status stream, a template icon, and native session actions.
 Opening it reads a fresh local snapshot, and visible rows update in place.
 Short-window and weekly allowance are labeled separately.
+Accounts assigned to live Relay sessions have a checkmark and an “In use” label;
+shared accounts also show their session count. To switch, open the Relay icon,
+then your session, then **Switch account**, and choose the account email. The
+current choice is marked **Current**. The menu tracks tasks started through Relay.
+Each session menu can switch to another enabled account after work and approvals
+finish. The worker checks allowance and session capacity before switching, then
+checks again that the session is idle before changing its login. Rejected actions
+show their reason. Pending menu actions cannot be submitted twice, and results
+remain visible until dismissed or another action starts. Stopped workers offer
+Restart; restarting retains any review hold.
+
+Account menus can disable or enable future routing. Disabling an account does not
+interrupt work already using it. The account chooser marks the current account
+and disables accounts excluded by their saved routing/model settings.
 It opens at Mac login after `relay menubar`; disable that in its menu or with
 `relay menubar --no-startup --configure-only`.
 

package/docs/publishing.md

@@ -8,8 +8,8 @@ Friends can run `npx relay-codex` or install it with `npm install -g relay-codex
 The GitHub repository is enough for friends to install or try Relay:
 
 ```sh
-npm install -g github:blackspider-ops/relay#v0.5.3
-npx --yes github:blackspider-ops/relay#v0.5.3 --version
+npm install -g github:blackspider-ops/relay#v0.6.1
+npx --yes github:blackspider-ops/relay#v0.6.1 --version
 ```
 
 `npx` runs packages; it is not a separate publishing service. Publishing

package/docs/troubleshooting.md

@@ -42,6 +42,20 @@ Check `relay --version` and update Relay. Watch now prints only meaningful chang
 from local state, without using model allowance. Earlier enrolled accounts can be
 identified with `relay account identify`; this reads saved login metadata locally.
 
+**Switching accounts says the task is busy.**
+
+Wait for its current work, tools and approvals to finish, then switch again.
+Relay rechecks this after checking the target account, so work starting during
+that check also prevents switching. A rejected menu action keeps its explanation
+visible. Use Restart for a stopped worker rather than sending it live controls.
+
+**Tab completion is missing.**
+
+Load `source <(relay completion zsh)` after `compinit`, or use
+`source <(relay completion bash)`. Put native arguments after `relay run --`.
+Native completion has the same choices and limitations as Codex's own generated
+completion. Start a new shell after a Codex update to reload those choices.
+
 **Why does npm ask for authentication?**
 
 That verification protects package publishing. Installing and running the public

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-codex",
-  "version": "0.5.3",
+  "version": "0.6.1",
   "description": "Keep your Codex sessions moving between your own accounts.",
   "license": "MIT",
   "author": "blackspider-ops",

package/python/Menu.swift

@@ -6,6 +6,9 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
     var buffer = Data()
     var current: [String: Any] = [:]
     var message: String?
+    var actionNotice: String?
+    var actionFailed = false
+    var actionRunning = false
     var reconnect: DispatchWorkItem?
     var stopping = false
     var snapshotInFlight = false
@@ -122,10 +125,12 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
         let entry = NSMenuItem(title: title, action: nil, keyEquivalent: "")
         entry.isEnabled = false; menu.addItem(entry)
     }
-    func action(_ title: String, args: [String], into menu: NSMenu) {
+    @discardableResult func action(_ title: String, args: [String], into menu: NSMenu) -> NSMenuItem {
         let entry = NSMenuItem(title: title, action: #selector(runAction(_:)), keyEquivalent: "")
         entry.target = self; entry.representedObject = args
+        entry.isEnabled = !actionRunning || args.first == "copy"
         entry.identifier = NSUserInterfaceItemIdentifier("action:" + args.joined(separator: "|")); menu.addItem(entry)
+        return entry
     }
     struct TimingRow {
         let title: String
@@ -170,15 +175,33 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
     func render() {
         let sessions = current["sessions"] as? [[String: Any]] ?? []
         let accounts = current["accounts"] as? [[String: Any]] ?? []
-        let attention = message != nil || sessions.contains { ($0["state"] as? String) == "needs_attention" }
+        let attention = message != nil || actionFailed || sessions.contains { ($0["state"] as? String) == "needs_attention" }
         updateIcon(attention: attention)
         item.button?.toolTip = "Relay · \(sessions.count) sessions · \(accounts.count) accounts"
+        let menu = makeMenu()
+        updateTimes(menu)
+        if let visible = item.menu { MenuController.synchronise(visible, with: menu) }
+        else { item.menu = menu }
+    }
+    func makeMenu() -> NSMenu {
+        let sessions = current["sessions"] as? [[String: Any]] ?? []
+        let accounts = current["accounts"] as? [[String: Any]] ?? []
+        let liveSessions = sessions.filter { $0["running"] as? Bool ?? true }
         let menu = NSMenu(); menu.delegate = self
+        menu.autoenablesItems = false
         text("Relay · \(sessions.count) sessions", into: menu)
         if let message = message { text(message, into: menu) }
+        if let notice = actionNotice {
+            text(notice, into: menu)
+            if !actionRunning { action("Dismiss message", args: ["dismiss"], into: menu) }
+        }
         if accounts.isEmpty { text("Add an account with relay setup in Terminal.", into: menu) }
+        if liveSessions.isEmpty && !accounts.isEmpty { text("No Relay sessions running. Start with relay run.", into: menu) }
         for account in accounts {
             let name = account["name"] as? String ?? "Account"
+            let accountID = account["id"] as? String ?? ""
+            let assigned = liveSessions.filter { $0["account"] as? String == accountID }
+            let inUse = assigned.isEmpty ? "" : assigned.count == 1 ? " · In use" : " · In use by \(assigned.count) sessions"
             let primary = account["primary"] as? [String: Any]
             let short = account["short_remaining"] as? String ?? (primary?["usedPercent"] as? NSNumber).map { "\(max(0, 100 - $0.intValue))%" } ?? "?"
             let remaining = short == "?" ? "allowance unknown" : short + " left"
@@ -186,7 +209,15 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
             let weekly = account["weekly_remaining"] as? String ?? (secondary?["usedPercent"] as? NSNumber).map { "\(max(0, 100 - $0.intValue))%" } ?? "?"
             let label = (account["enabled"] as? Bool ?? true) ? "Short \(short) · Week \(weekly)" : "disabled"
             let submenu = NSMenu()
+            submenu.autoenablesItems = false
             if let email = account["email"] as? String { text(email, into: submenu) }
+            if !assigned.isEmpty {
+                for session in assigned {
+                    let sessionName = session["name"] as? String ?? String((session["id"] as? String ?? "").prefix(10))
+                    text("In use by: \(sessionName)", into: submenu)
+                }
+                text("To switch: open that session → Switch account.", into: submenu)
+            }
             text("Short window: \(remaining)", into: submenu)
             if weekly != "?" { text("Weekly window: \(weekly) left", into: submenu) }
             for row in MenuController.accountTimingRows(account) {
@@ -195,7 +226,14 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
             }
             let lastChecked = MenuController.timestamp(account["usage_checked_at"]).map { date($0) } ?? "Not checked yet"
             text("Last checked: \(lastChecked)", into: submenu)
-            let entry = NSMenuItem(title: "\(name) · \(label)", action: nil, keyEquivalent: "")
+            if let id = account["id"] as? String {
+                submenu.addItem(.separator())
+                let enabled = account["enabled"] as? Bool ?? true
+                action(enabled ? "Disable for future routing" : "Enable for routing", args: ["account", enabled ? "disable" : "enable", id], into: submenu)
+                text("Current tasks keep running.", into: submenu)
+            }
+            let entry = NSMenuItem(title: "\(name)\(inUse) · \(label)", action: nil, keyEquivalent: "")
+            entry.state = assigned.isEmpty ? .off : .on
             entry.identifier = NSUserInterfaceItemIdentifier("account:" + (account["id"] as? String ?? name))
             entry.submenu = submenu; menu.addItem(entry)
         }
@@ -205,14 +243,37 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
             let name = session["name"] as? String ?? String(id.prefix(10))
             let status = (session["state"] as? String ?? "unknown").replacingOccurrences(of: "_", with: " ")
             let submenu = NSMenu()
+            submenu.autoenablesItems = false
             text("Account: \(session["account_name"] as? String ?? session["account"] as? String ?? "unknown")", into: submenu)
             text("Model: \(session["model"] as? String ?? "unknown")", into: submenu)
             if let next = MenuController.timestamp(session["next_wake"]) { countdown("Next action", value: next, into: submenu) }
             if let reason = session["reason"] as? String { text(reason.replacingOccurrences(of: "_", with: " "), into: submenu) }
             action("Copy reconnect command", args: ["copy", "relay attach " + id], into: submenu)
-            action("Pause recovery", args: ["pause", id, "--wait"], into: submenu)
-            action("Resume recovery", args: ["unpause", id, "--wait"], into: submenu)
-            action("Review and retry…", args: ["confirm-retry", id], into: submenu)
+            if session["running"] as? Bool ?? true {
+                let paused = session["paused"] as? Bool ?? false
+                action(paused ? "Resume recovery" : "Pause recovery", args: [paused ? "unpause" : "pause", id, "--wait"], into: submenu)
+                let choices = NSMenu(); choices.autoenablesItems = false
+                for account in accounts {
+                    guard let accountID = account["id"] as? String else { continue }
+                    let selected = accountID == session["account"] as? String
+                    let models = account["models"] as? [String] ?? []
+                    let model = session["model"] as? String
+                    let modelAllowed = models.isEmpty || model == nil || models.contains(model!)
+                    let available = (account["enabled"] as? Bool ?? true) && !(account["maintenance"] as? Bool ?? false) && modelAllowed
+                    let name = account["name"] as? String ?? accountID
+                    let choice = action(name + (selected ? " · Current" : available ? "" : " · unavailable"), args: ["switch", id, "--account", accountID, "--wait"], into: choices)
+                    choice.state = selected ? .on : .off
+                    choice.isEnabled = !selected && available && !actionRunning
+                }
+                text("Switch after current work and approvals finish.", into: choices)
+                let switchItem = NSMenuItem(title: "Switch account", action: nil, keyEquivalent: "")
+                switchItem.identifier = NSUserInterfaceItemIdentifier("switch:" + id)
+                switchItem.submenu = choices; submenu.addItem(switchItem)
+                action("Review and retry…", args: ["confirm-retry", id], into: submenu)
+            } else {
+                text("Worker stopped. Restart to reconnect; review holds are retained.", into: submenu)
+                action("Restart session", args: ["restart", id, "--if-stopped"], into: submenu)
+            }
             let entry = NSMenuItem(title: "\(name) · \(status)", action: nil, keyEquivalent: "")
             entry.identifier = NSUserInterfaceItemIdentifier("session:" + id)
             entry.submenu = submenu; menu.addItem(entry)
@@ -221,12 +282,11 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
         action("Copy dashboard command", args: ["copy", "relay status --watch"], into: menu)
         action("Check allowance now", args: ["refresh"], into: menu)
         let login = NSMenuItem(title: "Open at login", action: #selector(toggleLogin), keyEquivalent: ""); login.target = self
+        login.isEnabled = !actionRunning
         login.state = FileManager.default.fileExists(atPath: NSHomeDirectory() + "/Library/LaunchAgents/local.relay.menu.plist") ? .on : .off
         menu.addItem(login)
         let quit = NSMenuItem(title: "Quit Relay menu", action: #selector(quitMenu), keyEquivalent: "q"); quit.target = self; menu.addItem(quit)
-        updateTimes(menu)
-        if let visible = item.menu { MenuController.synchronise(visible, with: menu) }
-        else { item.menu = menu }
+        return menu
     }
     func menuWillOpen(_ menu: NSMenu) {
         refreshSnapshot()
@@ -238,6 +298,8 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
     @objc func runAction(_ sender: NSMenuItem) {
         guard var args = sender.representedObject as? [String], !args.isEmpty else { return }
         if args[0] == "copy" { NSPasteboard.general.clearContents(); NSPasteboard.general.setString(args[1], forType: .string); return }
+        if args[0] == "dismiss" { actionNotice = nil; actionFailed = false; render(); return }
+        guard !actionRunning else { return }
         if args[0] == "confirm-retry" {
             let alert = NSAlert(); alert.messageText = "Continue this task?"; alert.informativeText = "Review any interrupted command or external action in the conversation before continuing."
             alert.addButton(withTitle: "Continue task"); alert.addButton(withTitle: "Cancel")
@@ -245,19 +307,39 @@ final class MenuController: NSObject, NSApplicationDelegate, NSMenuDelegate {
             guard alert.runModal() == .alertFirstButtonReturn else { return }
             args = ["retry", args[1], "--wait"]
         }
+        actionRunning = true; actionFailed = false; actionNotice = "Applying change…"; render()
         let proc = process(args); let pipe = Pipe(); proc.standardOutput = FileHandle.nullDevice; proc.standardError = pipe
         DispatchQueue.global(qos: .utility).async { [weak self] in
             do {
                 try proc.run(); let bytes = pipe.fileHandleForReading.readDataToEndOfFile(); proc.waitUntilExit()
-                if proc.terminationStatus != 0 { DispatchQueue.main.async { self?.message = String(data: bytes, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? "Action failed. Check relay events."; self?.render() } }
-            } catch { DispatchQueue.main.async { self?.message = "Could not run that action."; self?.render() } }
+                let failed = proc.terminationStatus != 0
+                let detail = String(data: bytes, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+                DispatchQueue.main.async {
+                    self?.actionRunning = false; self?.actionFailed = failed
+                    self?.actionNotice = failed ? (detail.isEmpty ? "Action failed. Check relay events." : detail) : MenuController.successMessage(args)
+                    self?.render(); self?.refreshSnapshot()
+                }
+            } catch { DispatchQueue.main.async { self?.actionRunning = false; self?.actionFailed = true; self?.actionNotice = "Could not run that action."; self?.render() } }
+        }
+    }
+    static func successMessage(_ args: [String]) -> String {
+        switch args.first {
+        case "switch": return "Account switched."
+        case "pause": return "Recovery paused. Current work can finish."
+        case "unpause": return "Recovery resumed."
+        case "retry": return "Task allowed to continue."
+        case "restart": return "Session restarted."
+        case "refresh": return "Allowance check finished. See each account’s last checked time."
+        case "account": return args.dropFirst().first == "disable" ? "Account disabled for future routing." : "Account enabled for routing."
+        default: return "Change applied."
         }
     }
     @objc func toggleLogin() {
         let enabled = FileManager.default.fileExists(atPath: NSHomeDirectory() + "/Library/LaunchAgents/local.relay.menu.plist")
-        runCommand(enabled ? ["menubar", "--no-startup", "--configure-only"] : ["menubar", "--configure-only"])
+        let sender = NSMenuItem()
+        sender.representedObject = enabled ? ["menubar", "--no-startup", "--configure-only"] : ["menubar", "--configure-only"]
+        runAction(sender)
     }
-    func runCommand(_ args: [String]) { let proc = process(args); proc.standardOutput = FileHandle.nullDevice; proc.standardError = FileHandle.nullDevice; try? proc.run() }
     @objc func quitMenu() { stopping = true; reconnect?.cancel(); stream?.terminate(); NSApp.terminate(nil) }
     func applicationWillTerminate(_ notification: Notification) { stopping = true; stream?.terminate() }
 }
@@ -281,7 +363,43 @@ if CommandLine.arguments.contains("--self-check") {
     let scheduled = MenuController.accountTimingRows(["next_check": 2000200000.0])
     let correctTiming = timing.map { $0.title } == ["Short reset", "Weekly reset", "Allowance checked when needed"] && scheduled.first?.title == "Next allowance check" && scheduled.first?.at == 2000200000.0
     print("Empty retry schedule handled: \(correctTiming)")
-    exit(normal != nil && attention != nil && liveUpdate && safeIdentity && correctTiming ? 0 : 1)
+    func findAction(_ args: [String], in menu: NSMenu) -> NSMenuItem? {
+        for entry in menu.items {
+            if entry.representedObject as? [String] == args { return entry }
+            if let child = entry.submenu, let found = findAction(args, in: child) { return found }
+        }
+        return nil
+    }
+    let controller = MenuController()
+    controller.current = ["accounts": [["id": "one", "name": "One"], ["id": "two", "name": "Two"], ["id": "off", "enabled": false]], "sessions": [["id": "live", "account": "one", "running": true], ["id": "stopped", "running": false]]]
+    let controls = controller.makeMenu()
+    let switchArgs = ["switch", "live", "--account", "two", "--wait"]
+    let correctChoices = findAction(switchArgs, in: controls)?.isEnabled == true && findAction(["switch", "live", "--account", "one", "--wait"], in: controls)?.state == .on && findAction(["switch", "live", "--account", "off", "--wait"], in: controls)?.isEnabled == false
+    let stoppedControls = findAction(["restart", "stopped", "--if-stopped"], in: controls) != nil && findAction(["pause", "stopped", "--wait"], in: controls) == nil
+    let activeMarker = controls.items.first { $0.identifier?.rawValue == "account:one" }
+    let currentChoice = findAction(["switch", "live", "--account", "one", "--wait"], in: controls)
+    let correctMarker = activeMarker?.state == .on && activeMarker?.title.contains("In use") == true && currentChoice?.title.contains("Current") == true
+    let originalSessions = controller.current["sessions"]
+    controller.current["sessions"] = [["id": "a", "account": "one", "running": true], ["id": "b", "account": "one", "running": true], ["id": "c", "account": "two", "running": true], ["id": "d", "account": "off", "running": false]]
+    let multiple = controller.makeMenu()
+    let one = multiple.items.first { $0.identifier?.rawValue == "account:one" }
+    let two = multiple.items.first { $0.identifier?.rawValue == "account:two" }
+    let off = multiple.items.first { $0.identifier?.rawValue == "account:off" }
+    let correctMultiple = one?.title.contains("In use by 2 sessions") == true && two?.state == .on && off?.state == .off
+    controller.current["sessions"] = [["id": "stopped", "account": "one", "running": false]]
+    let empty = controller.makeMenu()
+    let correctEmpty = empty.items.contains { $0.title.contains("No Relay sessions running") } && empty.items.first { $0.identifier?.rawValue == "account:one" }?.state == .off
+    controller.current["sessions"] = originalSessions
+    controller.actionRunning = true; controller.actionNotice = "Applying change…"
+    let pending = controller.makeMenu()
+    let correctPending = findAction(switchArgs, in: pending)?.isEnabled == false && findAction(["refresh"], in: pending)?.isEnabled == false && findAction(["copy", "relay attach live"], in: pending)?.isEnabled == true
+    controller.actionRunning = false; controller.actionNotice = "Task is busy."
+    controller.current["at"] = 2000000001.0
+    let retainedResult = controller.makeMenu().items.contains { $0.title == "Task is busy." }
+    print("Account choices and stopped controls correct: \(correctChoices && stoppedControls)")
+    print("Pending action protected and result retained: \(correctPending && retainedResult)")
+    print("In-use accounts and current choice marked: \(correctMarker && correctMultiple && correctEmpty)")
+    exit(normal != nil && attention != nil && liveUpdate && safeIdentity && correctTiming && correctChoices && stoppedControls && correctPending && retainedResult && correctMarker && correctMultiple && correctEmpty ? 0 : 1)
 } else {
     let app = NSApplication.shared
     let delegate = MenuController(); app.delegate = delegate; app.run()

package/python/commands.py

@@ -103,6 +103,7 @@ def snapshot(state, include_inactive=False):
                     "enabled": options.get("enabled", True),
                     "priority": options.get("priority", 0),
                     "max_sessions": options.get("max_sessions", 0),
+                    "models": options.get("models", []),
                     "sessions": sum(s["account"] == label for s in sessions),
                     "primary": windows.get("primary"),
                     "secondary": windows.get("secondary"),
@@ -119,6 +120,7 @@ def snapshot(state, include_inactive=False):
             )
         with pool.db() as db:
             for session in sessions:
+                session["running"] = True
                 account = next(
                     (a for a in accounts if a["id"] == session.get("account")), {}
                 )
@@ -154,6 +156,8 @@ def snapshot(state, include_inactive=False):
             if not include_inactive and job.get("state") != "needs_attention":
                 continue
             prior = saved.get(ident, {})
+            account_id = prior.get("account") or job.get("first") or ""
+            account = next((a for a in accounts if a["id"] == account_id), {})
             sessions.append(
                 {
                     "id": ident,
@@ -161,7 +165,9 @@ def snapshot(state, include_inactive=False):
                     "name": job.get("name", ident[:10]),
                     "cwd": job.get("cwd"),
                     "thread": job.get("resume"),
-                    "account": prior.get("account") or job.get("first") or "",
+                    "account": account_id,
+                    "account_name": account.get("name", account_id),
+                    "account_email": account.get("email"),
                     "model": prior.get("model"),
                     "state": job.get("state", "unknown"),
                     "paused": prior.get("paused", False),
@@ -558,6 +564,13 @@ async def group(args, state, binary):
 
 
 def add_parsers(sub):
+    completion = sub.add_parser(
+        "completion",
+        help="Generate shell completion for Relay and native Codex arguments",
+    )
+    completion.add_argument("shell", choices=["zsh", "bash"])
+    complete = sub.add_parser("_complete", help=__import__("argparse").SUPPRESS)
+    complete.add_argument("words", nargs="...")
     preview = sub.add_parser(
         "explain", help="Preview a native Codex launch without starting a task"
     )

package/python/completion.py

@@ -0,0 +1,248 @@
+"""Shell adapters and local completion. Never start Codex or read credentials here."""
+
+import argparse
+import json
+from pathlib import Path
+import sqlite3
+import tomllib
+
+
+def document(path):
+    try:
+        value = (
+            tomllib.loads(path.read_text())
+            if path.suffix == ".toml"
+            else json.loads(path.read_text())
+        )
+        return value if isinstance(value, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def rows(state, query):
+    path = state / "pool.sqlite"
+    if not path.exists():
+        return []
+    try:
+        db = sqlite3.connect(
+            path.resolve().as_uri() + "?mode=ro", uri=True, timeout=0.15
+        )
+        try:
+            return db.execute(query).fetchall()
+        finally:
+            db.close()
+    except sqlite3.Error:
+        return []
+
+
+def values(action, context, chosen, state):
+    from router import labels
+    from commands import account_identity
+    from settings import DEFAULTS
+
+    if action.choices is not None and not isinstance(
+        action, argparse._SubParsersAction
+    ):
+        return list(action.choices)
+    name = action.dest
+    if name in {"first", "account", "label"}:
+        if name == "label" and context[-1:] == ["add"]:
+            return []
+        accounts = labels(state)
+        aliases = [account_identity(state, label).get("email") for label in accounts]
+        for label, raw in rows(state, "SELECT label,options FROM account_options"):
+            if label in accounts:
+                try:
+                    aliases.append(json.loads(raw).get("name"))
+                except ValueError:
+                    pass
+        # Do not offer an ambiguous email/display name.
+        return accounts + [
+            a for a in aliases if isinstance(a, str) and aliases.count(a) == 1
+        ]
+    if name in {"session", "target", "sessions"}:
+        from pool import Pool
+
+        live = [
+            ident
+            for ident, pid in rows(state, "SELECT id,pid FROM sessions")
+            if Pool.alive(pid)
+        ]
+        if name == "target":
+            return live + ["all"]
+        saved = [
+            p.name.removesuffix(".job.json")
+            for p in (state / "services").glob("*.job.json")
+        ]
+        return live if name == "sessions" else live + saved
+    if name == "profile":
+        result = []
+        for path in [
+            state / "settings.json",
+            Path.cwd() / ".relay.toml",
+            Path.cwd() / ".codex-accounts.toml",
+        ]:
+            profiles = document(path).get("profiles", {})
+            if isinstance(profiles, dict):
+                result.extend(profiles)
+        return result
+    if name == "key" and context[:1] == ["config"]:
+        return list(DEFAULTS)
+    if name == "value" and context[:1] == ["config"]:
+        key = chosen.get("key")
+        if key == "routing":
+            return ["balanced", "quota", "priority", "round-robin"]
+        if isinstance(DEFAULTS.get(key), bool):
+            return ["true", "false"]
+    if (
+        name == "name"
+        and context[:1] in (["workspace"], ["group"])
+        and context[-1:] != ["save"]
+    ):
+        return list(
+            document(
+                state
+                / ("workspaces.json" if context[0] == "workspace" else "groups.json")
+            )
+        )
+    if name == "topic":
+        from router import parser
+
+        sub = next(
+            a for a in parser()._actions if isinstance(a, argparse._SubParsersAction)
+        )
+        return [k for k in sub.choices if not k.startswith("_")] + ["codex"]
+    return []
+
+
+def candidates(arguments, state):
+    """Last word is the word being completed. @codex:N delegates after N words."""
+    from router import parser
+
+    arguments = list(arguments) or [""]
+    prefix, previous = arguments[-1], arguments[:-1]
+    current = parser()
+    context, chosen = [], {}
+    pending = None
+    positional = 0
+    options = True
+    for index, word in enumerate(previous):
+        if pending is not None:
+            chosen[pending.dest] = word
+            pending = None
+            continue
+        positionals = [a for a in current._actions if not a.option_strings]
+        action = positionals[positional] if positional < len(positionals) else None
+        if options and word == "--":
+            if action is not None and action.nargs == argparse.REMAINDER:
+                return [f"@codex:{index + 1}"]
+            options = False
+            continue
+        if options and word.startswith("-"):
+            flag, equal, value = word.partition("=")
+            option = current._option_string_actions.get(flag)
+            if option is None:
+                return []
+            if option.nargs != 0:
+                if equal:
+                    chosen[option.dest] = value
+                else:
+                    pending = option
+            continue
+        if isinstance(action, argparse._SubParsersAction):
+            if word not in action.choices or word.startswith("_"):
+                return []
+            context.append(word)
+            current = action.choices[word]
+            positional = 0
+        elif action is not None:
+            if action.nargs == argparse.REMAINDER:
+                return [f"@codex:{index}"]
+            chosen[action.dest] = word
+            if action.nargs not in {"*", "+"}:
+                positional += 1
+    if pending is not None:
+        result = values(pending, context, chosen, state)
+    elif options and prefix.startswith("-"):
+        flag, equal, value = prefix.partition("=")
+        action = current._option_string_actions.get(flag)
+        if equal and action is not None and action.nargs != 0:
+            return sorted(
+                {
+                    flag + "=" + item
+                    for item in values(action, context, chosen, state)
+                    if item.startswith(value) and "\n" not in item and "\r" not in item
+                }
+            )
+        result = list(current._option_string_actions)
+    else:
+        positionals = [a for a in current._actions if not a.option_strings]
+        action = positionals[positional] if positional < len(positionals) else None
+        if isinstance(action, argparse._SubParsersAction):
+            result = [k for k in action.choices if not k.startswith("_")]
+        elif action is not None and action.nargs == argparse.REMAINDER:
+            # Show wrapper flags until the user enters native arguments or --.
+            result = list(current._option_string_actions)
+            if not prefix:
+                result.append("--")
+            else:
+                return [f"@codex:{len(previous)}"]
+        else:
+            result = values(action, context, chosen, state) if action else []
+    return sorted(
+        {
+            str(item)
+            for item in result
+            if isinstance(item, str)
+            and item.startswith(prefix)
+            and "\n" not in item
+            and "\r" not in item
+        }
+    )
+
+
+def script(shell):
+    if shell == "zsh":
+        return r"""# Relay completion. Load after compinit: source <(relay completion zsh)
+_relay() {
+    local -a replies
+    replies=("${(@f)$(command relay _complete -- "${words[@]:1:$((CURRENT - 1))}")}")
+    if [[ ${replies[1]} == @codex:<-> ]]; then
+        local skip=${replies[1]#@codex:}
+        if (( ! $+functions[_codex] )); then
+            local native
+            native=$(command codex completion zsh 2>/dev/null) || { _files; return; }
+            eval "$native"
+        fi
+        local -a words=(codex "${words[@]:$((skip + 1))}")
+        local CURRENT=$((CURRENT - skip))
+        _codex
+        return
+    fi
+    [[ -n ${replies[1]} ]] && compadd -a replies || _files
+}
+compdef _relay relay"""
+    if shell == "bash":
+        return r"""# Relay completion: source <(relay completion bash)
+_relay() {
+    local item skip native cur="${COMP_WORDS[COMP_CWORD]}"
+    local -a replies=()
+    while IFS= read -r item; do
+        [[ -n "$item" ]] && replies+=("$item")
+    done < <(command relay _complete -- "${COMP_WORDS[@]:1:COMP_CWORD}")
+    if [[ ${replies[0]} == @codex:* ]]; then
+        skip=${replies[0]#@codex:}
+        [[ "$skip" =~ ^[0-9]+$ ]] || return
+        if ! declare -F _codex >/dev/null; then
+            native=$(command codex completion bash 2>/dev/null) || return
+            eval "$native"
+        fi
+        local -a COMP_WORDS=(codex "${COMP_WORDS[@]:$((skip + 1))}")
+        local COMP_CWORD=$((COMP_CWORD - skip))
+        _codex codex "$cur" "${COMP_WORDS[COMP_CWORD-1]}"
+        return
+    fi
+    COMPREPLY=("${replies[@]}")
+}
+complete -o default -F _relay relay"""
+    raise ValueError("Choose zsh or bash")

package/python/pool.py

@@ -377,9 +377,20 @@ class Pool:
                 )
         return [(r[0], r[1], json.loads(r[2])) for r in rows]
 
-    def ack(self, command, status):
+    def ack(self, command, status, *, reason=None):
         with self.db() as db:
             db.execute("UPDATE commands SET status=? WHERE id=?", (status, command))
+            if reason is not None:
+                row = db.execute(
+                    "SELECT details FROM commands WHERE id=?", (command,)
+                ).fetchone()
+                if row:
+                    details = json.loads(row[0])
+                    details["_rejection"] = reason
+                    db.execute(
+                        "UPDATE commands SET details=? WHERE id=?",
+                        (json.dumps(details), command),
+                    )
 
     def claim(self, thread):
         with self.db() as db:

package/python/router.py

@@ -24,7 +24,7 @@ from pool import Pool, blocked, reset_time, failure_kind, file_lock
 from launch import translate, RESUME_FIELDS
 import settings
 
-VERSION = "0.5.3"
+VERSION = "0.6.1"
 _support = Path.home() / "Library/Application Support"
 _legacy = _support / "Codex Accounts"
 _default_state = _legacy if (_legacy / "accounts").exists() else _support / "Relay"
@@ -45,6 +45,21 @@ class RouterError(Exception):
     """A message safe to display; never include a server error or credential."""
 
 
+CONTROL_REJECTIONS = {
+    "unknown_account": "That account is no longer enrolled. Check relay list.",
+    "busy": "Session is busy; switch after its current work and approvals finish.",
+    "account_unavailable": "Account is disabled, under maintenance, or unavailable for this model.",
+    "allowance_exhausted": "Account allowance is exhausted. Choose another account or wait for its reset.",
+    "account_full": "Account session capacity is full or its routing settings changed.",
+}
+
+
+class ControlRejected(RouterError):
+    def __init__(self, reason):
+        self.reason = reason
+        super().__init__(CONTROL_REJECTIONS[reason])
+
+
 class RecoveryTransition(Exception):
     """Return to the recovery driver without growing the Python call stack."""
 
@@ -682,9 +697,12 @@ class Controller:
                     try:
                         await self.control(op, params)
                         self.pool.ack(command, "done")
-                    except Exception:
-                        self.pool.ack(command, "failed")
-                        self.note("control_failed", operation=op)
+                    except Exception as error:
+                        reason = (
+                            error.reason if isinstance(error, ControlRejected) else None
+                        )
+                        self.pool.ack(command, "failed", reason=reason)
+                        self.pool.record("control_failed", operation=op, reason=reason)
             if self.lifecycle_check:
                 await self.lifecycle_check()
                 if self.stopping.is_set():
@@ -781,9 +799,9 @@ class Controller:
                 (i for i, a in enumerate(self.accounts) if a.label == label), None
             )
             if index is None:
-                raise RouterError("Unknown account")
+                raise ControlRejected("unknown_account")
             if self.active_threads or self.active_items or self.server_requests:
-                raise RouterError("Session is busy; switch at an idle boundary")
+                raise ControlRejected("busy")
             options = self.pool.options(label) if self.pool else {}
             model = self.model_for(thread) if thread else None
             if (
@@ -793,19 +811,17 @@ class Controller:
                 and model
                 and model not in options["models"]
             ):
-                raise RouterError(
-                    "Account is disabled, under maintenance, or unavailable for this model"
-                )
+                raise ControlRejected("account_unavailable")
             if limited(await self.accounts[index].usage(force=True), model):
-                raise RouterError("Account allowance is exhausted")
+                raise ControlRejected("allowance_exhausted")
             if self.pool and not self.pool.reserve(
                 label,
                 limit=options.get("max_sessions")
                 or self.preferences["max_sessions_per_account"],
             ):
-                raise RouterError("Account capacity is full or maintenance has started")
+                raise ControlRejected("account_full")
             try:
-                await self.login(index)
+                await self.login(index, idle_only=True)
             finally:
                 if self.pool:
                     self.pool.release_reservation()
@@ -910,19 +926,39 @@ class Controller:
     def account(self):
         return self.accounts[self.index]
 
-    async def login(self, index):
+    async def login(self, index, *, idle_only=False):
         # A sent login cannot be undone by cancelling its waiter. Complete the
         # state transition before allowing a new user turn to use this backend.
-        task = asyncio.create_task(self._login(index))
+        task = asyncio.create_task(self._login(index, idle_only=idle_only))
         try:
             return await asyncio.shield(task)
         except asyncio.CancelledError:
             await task
             raise
 
-    async def _login(self, index):
+    async def _login(self, index, *, idle_only=False):
         async with self.login_lock:
             credentials = await self.accounts[index].credentials()
+            # An allowance or credential read can outlast the idle boundary.
+            # User turns use this same lock; validate again before sending tokens.
+            if idle_only and (
+                self.active_threads or self.active_items or self.server_requests
+            ):
+                raise ControlRejected("busy")
+            if idle_only and self.pool:
+                options = self.pool.options(self.accounts[index].label)
+                thread = next(reversed(self.last_turn), None)
+                model = self.model_for(thread) if thread else None
+                if (
+                    not options.get("enabled", True)
+                    or options.get("maintenance")
+                    or (
+                        options.get("models")
+                        and model
+                        and model not in options["models"]
+                    )
+                ):
+                    raise ControlRejected("account_unavailable")
             await self.backend.call(
                 "account/login/start", {"type": "chatgptAuthTokens", **credentials}
             )
@@ -1174,10 +1210,28 @@ class Controller:
                 params[key] = self.thread_settings[thread][key]
         params["clientUserMessageId"] = str(uuid.uuid4())
         baseline = self.turn_ids.get(thread) or "__unknown_before_submission__"
-        self.pending_intents[thread] = {"baseline": baseline, "accepted": False}
-        self.persist(thread, accepted=False, state="submitting", baseline=baseline)
         try:
-            result = await self.backend.call("turn/start", params)
+            while True:
+                async with self.login_lock:
+                    if not self.can_continue(thread, generation):
+                        return
+                    if not (
+                        self.active_threads or self.active_items or self.server_requests
+                    ):
+                        self.pending_intents[thread] = {
+                            "baseline": baseline,
+                            "accepted": False,
+                        }
+                        self.persist(
+                            thread,
+                            accepted=False,
+                            state="submitting",
+                            baseline=baseline,
+                        )
+                        result = await self.backend.call("turn/start", params)
+                        break
+                if not await self.wait_idle(generation):
+                    return
             turn = result.get("turn", {})
             if turn.get("id"):
                 self.turn_ids[thread] = turn["id"]
@@ -2242,6 +2296,18 @@ def selected_binary(args, state):
 def main():
     os.umask(0o077)
     argv = sys.argv[1:]
+    if argv[:1] == ["completion"]:
+        import completion
+
+        args = parser().parse_args(argv)
+        print(completion.script(args.shell))
+        return 0
+    if argv[:1] == ["_complete"]:
+        import completion
+
+        words = argv[2:] if argv[1:2] == ["--"] else argv[1:]
+        print("\n".join(completion.candidates(words, STATE)))
+        return 0
     if argv[:2] == ["help", "run"]:
         argv = ["run", "--help"]
     before_separator = argv[: argv.index("--")] if "--" in argv else argv

package/python/service.py

@@ -784,19 +784,22 @@ async def _serve(state, ident, binary):
 
 
 async def wait_control(pool, command, timeout=15):
-    from router import RouterError
+    from router import RouterError, CONTROL_REJECTIONS
 
     deadline = time.monotonic() + timeout
     while time.monotonic() < deadline:
         with pool.db() as db:
             row = db.execute(
-                "SELECT status FROM commands WHERE id=?", (command,)
+                "SELECT status,details FROM commands WHERE id=?", (command,)
             ).fetchone()
         if row and row[0] == "done":
             return
         if row and row[0] == "failed":
             raise RouterError(
-                "Session rejected that action. Check status and events; no change was assumed."
+                CONTROL_REJECTIONS.get(
+                    json.loads(row[1]).get("_rejection"),
+                    "Session rejected that action. Check status and events; no change was assumed.",
+                )
             )
         await asyncio.sleep(0.1)
     raise RouterError("Session control timed out; check status before retrying.")

package/tests/test_usability.py

@@ -0,0 +1,287 @@
+"""Offline checks for completion and account controls across idle boundaries."""
+
+import asyncio
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+import unittest
+from unittest.mock import patch
+
+import commands
+import completion
+from pool import Pool
+from router import Controller, ControlRejected, RouterError
+import service
+from settings import atomic_json
+from test_router import FakeAccount, FakeBackend, FakeClient
+
+
+class SwitchBoundaries(unittest.IsolatedAsyncioTestCase):
+    async def test_target_disabled_during_credentials_is_not_selected(self):
+        with tempfile.TemporaryDirectory() as folder:
+            pool = Pool(Path(folder))
+            pool.assign("one")
+            target = FakeAccount("two")
+            original = target.credentials
+
+            async def credentials(*args, **kwargs):
+                pool.set_options("two", enabled=False)
+                return await original(*args, **kwargs)
+
+            target.credentials = credentials
+            c = Controller([FakeAccount("one"), target], FakeBackend(), pool=pool)
+            try:
+                with self.assertRaisesRegex(ControlRejected, "disabled"):
+                    await c.control("switch", {"account": "two"})
+                self.assertEqual(c.index, 0)
+                self.assertFalse(c.backend.calls)
+            finally:
+                pool.close()
+
+    async def test_running_worker_returns_reason_without_replacing_its_work_status(
+        self,
+    ):
+        from test_services import ServiceTests, wait_for
+
+        case = ServiceTests("test_background_work_completes_without_frontend")
+        await case.asyncSetUp()
+        pool = Pool(case.state)
+        try:
+            await wait_for(lambda: json.loads(case.job.read_text()).get("resume"))
+            command = pool.command(case.ident, "switch", {"account": "not-enrolled"})
+            with self.assertRaisesRegex(RouterError, "no longer enrolled"):
+                await service.wait_control(pool, command, timeout=5)
+            self.assertNotEqual(pool.detail()[0].get("state"), "control_failed")
+        finally:
+            pool.close()
+            await case.asyncTearDown()
+
+    async def test_work_arriving_during_allowance_or_credentials_prevents_switch(self):
+        for operation in ("usage", "credentials"):
+            for field, marker in (
+                ("active_threads", "thread"),
+                ("active_items", "tool"),
+                ("server_requests", 7),
+            ):
+                with (
+                    self.subTest(operation=operation, field=field),
+                    tempfile.TemporaryDirectory() as folder,
+                ):
+                    pool = Pool(Path(folder))
+                    pool.assign("one")
+                    account = FakeAccount("two")
+                    original = getattr(account, operation)
+                    entered, release = asyncio.Event(), asyncio.Event()
+
+                    async def delayed(*args, **kwargs):
+                        entered.set()
+                        await release.wait()
+                        return await original(*args, **kwargs)
+
+                    setattr(account, operation, delayed)
+                    backend = FakeBackend()
+                    c = Controller([FakeAccount("one"), account], backend, pool=pool)
+                    task = asyncio.create_task(c.control("switch", {"account": "two"}))
+                    try:
+                        await asyncio.wait_for(entered.wait(), 1)
+                        getattr(c, field).add(marker)
+                        release.set()
+                        with self.assertRaisesRegex(ControlRejected, "busy"):
+                            await asyncio.wait_for(task, 1)
+                        self.assertEqual(c.account.label, "one")
+                        self.assertFalse(
+                            any(m == "account/login/start" for m, _ in backend.calls)
+                        )
+                        with pool.db() as db:
+                            self.assertEqual(
+                                db.execute(
+                                    "SELECT count(*) FROM reservations"
+                                ).fetchone()[0],
+                                0,
+                            )
+                    finally:
+                        task.cancel()
+                        await asyncio.gather(task, return_exceptions=True)
+                        pool.close()
+
+    async def test_switch_rechecks_after_waiting_for_login_lock(self):
+        c = Controller([FakeAccount("one"), FakeAccount("two")], FakeBackend())
+        await c.login_lock.acquire()
+        task = asyncio.create_task(c.control("switch", {"account": "two"}))
+        await asyncio.sleep(0)
+        c.active_threads.add("new-work")
+        c.login_lock.release()
+        with self.assertRaises(ControlRejected):
+            await asyncio.wait_for(task, 1)
+        self.assertEqual(c.index, 0)
+
+    async def test_automatic_continuation_waits_for_account_transition(self):
+        c = Controller([FakeAccount("one")], FakeBackend())
+        c.client = FakeClient()
+        await c.login_lock.acquire()
+        task = asyncio.create_task(c.continue_thread("thread", 0))
+        await asyncio.sleep(0)
+        self.assertFalse(any(m == "turn/start" for m, _ in c.backend.calls))
+        c.login_lock.release()
+        await asyncio.wait_for(task, 1)
+        self.assertEqual(sum(m == "turn/start" for m, _ in c.backend.calls), 1)
+
+    async def test_control_rejection_is_specific_but_unknown_details_are_not_echoed(
+        self,
+    ):
+        with tempfile.TemporaryDirectory() as folder:
+            pool = Pool(Path(folder))
+            for reason, expected in (
+                ("busy", "Session is busy"),
+                ("PRIVATE_TEST_SECRET", "Session rejected"),
+                (None, "Session rejected"),
+            ):
+                command = pool.command("worker", "switch", {"account": "two"})
+                pool.ack(command, "failed", reason=reason)
+                with self.assertRaisesRegex(RouterError, expected) as error:
+                    await service.wait_control(pool, command)
+                self.assertNotIn("PRIVATE_TEST_SECRET", str(error.exception))
+            pool.close()
+
+
+class CompletionTests(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self.tmp.name)
+        self.state = self.root / "state"
+        home = self.state / "accounts" / "personal"
+        home.mkdir(parents=True)
+        atomic_json(home / "enrolled", {})
+        atomic_json(home / "identity.json", {"email": "person@example.invalid"})
+        atomic_json(self.state / "workspaces.json", {"daily work": ["saved"]})
+        atomic_json(self.state / "settings.json", {"profiles": {"quiet": {}}})
+        atomic_json(
+            self.state / "services" / "saved.job.json",
+            {"id": "saved", "first": "personal", "state": "needs_attention"},
+        )
+        self.pool = Pool(self.state)
+        self.pool.session = "live-test"
+        self.pool.assign("personal")
+
+    def tearDown(self):
+        self.pool.close()
+        self.tmp.cleanup()
+
+    def complete(self, *args):
+        with (
+            patch(
+                "router.read_keychain",
+                side_effect=AssertionError("No credential reads"),
+            ),
+            patch("router.codex_path", side_effect=AssertionError("No native process")),
+        ):
+            return completion.candidates(args, self.state)
+
+    def test_parser_commands_options_and_dynamic_values(self):
+        self.assertIn("completion", self.complete(""))
+        self.assertFalse(any(x.startswith("_") for x in self.complete("")))
+        self.assertIn("reauth", self.complete("account", "re"))
+        self.assertEqual(self.complete("completion", "z"), ["zsh"])
+        self.assertEqual(
+            self.complete("switch", "--account", "pe"),
+            ["person@example.invalid", "personal"],
+        )
+        self.assertEqual(
+            self.complete("switch", "--account=pers"),
+            ["--account=person@example.invalid", "--account=personal"],
+        )
+        self.assertEqual(self.complete("run", "--profile", ""), ["quiet"])
+        self.assertEqual(self.complete("workspace", "restore", ""), ["daily work"])
+        self.assertEqual(self.complete("pause", "live"), ["live-test"])
+        self.assertIn("saved", self.complete("restart", ""))
+        self.assertEqual(
+            self.complete("config", "notifications", ""), ["false", "true"]
+        )
+
+    def test_native_boundaries_consume_wrapper_values(self):
+        for args, skip in (
+            (["run", "--", "resume", "--la"], 2),
+            (["run", "--name", "--", "--", "resume", ""], 4),
+            (["run", "resume", ""], 1),
+            (["attach", "saved", "--", ""], 3),
+            (["explain", "--", ""], 2),
+        ):
+            self.assertEqual(self.complete(*args), [f"@codex:{skip}"])
+        self.assertIn("--require-recovery", self.complete("run", "--"))
+
+    def test_stopped_sessions_keep_account_identity_and_correct_liveness(self):
+        value = commands.snapshot(self.state)
+        saved = next(s for s in value["sessions"] if s["id"] == "saved")
+        self.assertFalse(saved["running"])
+        self.assertEqual(saved["account_name"], "person@example.invalid")
+        self.assertTrue(
+            next(s for s in value["sessions"] if s["id"] == "live-test")["running"]
+        )
+
+    def test_real_shell_adapters_preserve_spaces_and_delegate_native_arguments(self):
+        bin_dir = self.root / "bin"
+        bin_dir.mkdir()
+        relay = bin_dir / "relay"
+        relay.write_text(
+            "#!"
+            + sys.executable
+            + "\nimport sys\nfrom pathlib import Path\nfrom completion import candidates\nprint('\\n'.join(candidates(sys.argv[3:], Path("
+            + repr(str(self.state))
+            + "))))\n"
+        )
+        relay.chmod(0o700)
+        env = {
+            **os.environ,
+            "PATH": str(bin_dir) + os.pathsep + os.environ.get("PATH", ""),
+            "PYTHONPATH": str(Path(__file__).resolve().parent.parent / "python"),
+        }
+        for shell in ("bash", "zsh"):
+            script = self.root / ("completion." + shell)
+            script.write_text(completion.script(shell))
+            if shell == "bash":
+                command = """source "$1"
+COMP_WORDS=(relay workspace restore ""); COMP_CWORD=3
+_relay; printf '%s\n' "${COMPREPLY[@]}"
+_codex() { COMPREPLY=("native:${COMP_WORDS[*]}:${COMP_CWORD}"); }
+COMP_WORDS=(relay run -- resume --la); COMP_CWORD=4
+_relay; printf '%s\n' "${COMPREPLY[@]}"
+"""
+            else:
+                command = """autoload -Uz compinit; compinit -D
+source "$1"
+_files() { return 1; }
+compadd() { local -a result; result=("${(@P)2}"); printf '%s\n' "${result[@]}"; }
+words=(relay workspace restore ""); CURRENT=4; _relay
+_codex() { print -r -- "native:${words[*]}:${CURRENT}"; }
+words=(relay run -- resume --la); CURRENT=5; _relay
+"""
+            result = subprocess.run(
+                [
+                    "/bin/" + shell,
+                    "-f" if shell == "zsh" else "--noprofile",
+                    "-c",
+                    command,
+                    "test",
+                    str(script),
+                ],
+                capture_output=True,
+                text=True,
+                env=env,
+            )
+            self.assertEqual(result.returncode, 0, result.stderr)
+            self.assertEqual(
+                result.stdout.splitlines(),
+                [
+                    "daily work",
+                    "native:codex resume --la:2"
+                    if shell == "bash"
+                    else "native:codex resume --la:3",
+                ],
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()