conductor-remote 1.116.0 → 1.118.0

package/dist-node/src/writes/system.js

@@ -0,0 +1,81 @@
+import path from 'node:path';
+import { CONDUCTOR_HANDLERS, osaError, RESTART_ATTEMPT_MS } from "./runner.js";
+import { exec, uiTurn } from "./ui-lock.js";
+/**
+ * Press the Wi-Fi menu's row for a personal hotspot — Instant Hotspot, the same
+ * button a human clicks. `networksetup` can only join a network that is
+ * broadcasting, and a personal hotspot usually isn't; the row in Control
+ * Center's Wi-Fi popover is fed by Continuity over Bluetooth, and pressing it
+ * asks the phone to wake its hotspot. The funnel watchdog reaches for this when
+ * a plain join answered "Could not find network".
+ *
+ * The one UI write here that doesn't target Conductor, and it still takes a
+ * uiTurn: the popover steals key focus, so a palette fallback running at the
+ * same moment would type into it. The name travels via a temp file like the
+ * prompt does — same escaping-and-encoding dodge, and hotspot names ("Han
+ * høyes iPhone") are non-ASCII more often than prompts are. Success here means
+ * *pressed*, nothing more: joining takes several seconds of Bluetooth wake +
+ * DHCP, so the caller owns the wait, and it watches `hasDefaultRoute()` — the
+ * one link signal that needs no permission — not this function's word.
+ * Everything else — the lock check, the toggle-aware close, the already-open
+ * abort, the contention story — lives with the handler in src/writes/applescript/hotspot.applescript.
+ */
+export async function joinInstantHotspot(name) {
+    const script = `
+${CONDUCTOR_HANDLERS}
+
+my joinInstantHotspot()`.trim();
+    const os = await import('node:os');
+    const fs = await import('node:fs/promises');
+    const tmp = path.join(os.tmpdir(), `relay-hotspot-${process.pid}-${Date.now()}.txt`);
+    await fs.writeFile(tmp, name, 'utf8');
+    try {
+        await uiTurn(() => exec('osascript', ['-e', script], {
+            env: { ...process.env, RELAY_HOTSPOT_FILE: tmp },
+            timeout: 25_000
+        }));
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: osaError(err, 'the Wi-Fi menu press took too long') };
+    }
+    finally {
+        await fs.rm(tmp, { force: true }).catch(() => undefined);
+    }
+}
+/**
+ * Quit Conductor and start it again because the phone asked — the one write here
+ * whose subject is the app rather than anything inside it.
+ *
+ * The lever already existed and was unreachable. `activateConductor` restarts as its
+ * last resort, but only after a *running* Conductor has drawn no window through
+ * `reopen` and a Dock click, so it answers exactly one failure: a windowless app. The
+ * failure this is for looks healthy from every probe on that ladder — window up,
+ * sidebar drawing, composer taking prompts — while the agent runtime behind it has
+ * stopped producing anything. Measured on this Mac (2026-09-02): the last agent frame
+ * in `session_messages` was 20:47:44 and prompts kept landing as user rows for the
+ * next two and a half hours, each turn flipping `working → idle` having written
+ * nothing. Nothing on the read side can fix that, and "quit it on your Mac" is not
+ * advice a phone can act on.
+ *
+ * Two gates, and neither lives here. The **working chats** are counted from the DB by
+ * src/http/routes/system.ts, which refuses without `stopAgents` — quitting takes every agent mid-turn
+ * down with it, so that has to be said out loud, exactly as it is for archiving. The
+ * **lock screen** is asked by `restartApp` itself, because a relaunch fired behind it
+ * comes up windowless (and once, wedged). What is left for this function is the UI
+ * lock: a restart is not a read, and letting one land while a send is mid-flight would
+ * quit the app between the composer write and the Enter.
+ */
+export async function restartConductorApp() {
+    const script = `
+${CONDUCTOR_HANDLERS}
+
+return my restartApp()`.trim();
+    try {
+        await uiTurn(() => exec('osascript', ['-e', script], { env: { ...process.env }, timeout: RESTART_ATTEMPT_MS }));
+        return { ok: true, strategy: 'applescript' };
+    }
+    catch (err) {
+        return { ok: false, strategy: 'applescript', error: osaError(err, 'Conductor didn’t come back in time') };
+    }
+}

package/dist-node/src/writes/targeting.js

@@ -0,0 +1,121 @@
+import path from 'node:path';
+/**
+ * The URL scheme Conductor registers, which is per *release channel*: the
+ * production build answers `conductor://`, the pre-release ones
+ * `conductor-alpha://`, `conductor-beta://`, `conductor-dev://` and friends.
+ * Everything else in this file addresses `application "Conductor"` by name, so
+ * production is the only channel the write path works against anyway — the
+ * override exists so a channel build needs a variable rather than a patch.
+ */
+export const CONDUCTOR_SCHEME = process.env.RELAY_CONDUCTOR_SCHEME || 'conductor';
+/**
+ * Conductor's own link to a workspace, and optionally to one chat inside it —
+ * exactly what its sidebar row menu copies under "Copy link" (Cmd+Shift+C).
+ *
+ * `conductor://workspace?id=<workspace>&session=<chat>` is the shape that works,
+ * and the near misses all fail *badly*, so this is the one place that builds it:
+ * the parameters sit behind a real `?` (unlike the create-workspace links, which
+ * are flat after the scheme), the workspace id is `id` rather than `workspace`,
+ * and `workspace` must be the URL's **host** — `conductor:///workspace/<id>`,
+ * with the id in the path, falls through to the flat-parameter parser and
+ * **creates a new workspace in the first repo**. A path-shaped link with the
+ * right host (`conductor://workspace/<id>`) is merely ignored.
+ *
+ * `session` is optional and names a chat by `sessions.id`, the same id the relay
+ * already serves; omitted, Conductor opens whichever tab that workspace had.
+ * Current Conductor builds also unhide a session named by this route, through
+ * their own session service. `restoreChat` uses that behavior and confirms the
+ * exact id became visible; older builds may ignore it, so opening is no receipt.
+ *
+ * The https form Conductor copies for sharing —
+ * `https://app.conductor.build/workspace/<id>?session=<chat>` — reaches the same
+ * handler, but only once macOS has decided to hand it to the app; the desktop
+ * build declares no associated domain, so a browser gets it first. Locally the
+ * scheme form is the one that always lands.
+ */
+export function workspaceLink(workspaceId, sessionId) {
+    const params = new URLSearchParams({ id: workspaceId });
+    if (sessionId)
+        params.set('session', sessionId);
+    return `${CONDUCTOR_SCHEME}://workspace?${params.toString()}`;
+}
+/** Conductor's command palette matches workspaces by branch — its unique key. A
+ * looser query (directory name) can match a command like unarchive, so prefer
+ * branch and only fall back when it's absent. */
+export function focusQuery(ws) {
+    return ws.branch || ws.workspace_name || ws.directory_name || '';
+}
+/**
+ * Every title Conductor might be showing for this workspace in the sidebar
+ * (its precedence: manual name → PR title → humanized branch → codename). The
+ * sidebar press tries each and requires a unique row; a miss just means we fall
+ * back to the palette, so this doesn't have to reproduce the precedence exactly.
+ */
+function sidebarTitles(ws) {
+    const slug = ws.branch?.includes('/') ? ws.branch.slice(ws.branch.indexOf('/') + 1) : ws.branch;
+    const humanized = slug?.replace(/[-_]/g, ' ').trim();
+    return [
+        ws.workspace_name,
+        ws.pr_title,
+        humanized ? humanized[0].toUpperCase() + humanized.slice(1) : '',
+        ws.directory_name
+    ].filter((t) => Boolean(t));
+}
+/**
+ * May the actuator restart Conductor to force a window into existence?
+ *
+ * Restarting is the only lever left when a running, windowless Conductor ignores
+ * both `reopen` and a Dock click — it is single-window and single-instance, so
+ * there is nothing else to press. It is also the one step here that can destroy
+ * work: quitting takes any agent mid-turn down with it. "Nothing is running" is a
+ * fact only the read side has, so src/http/services/base.ts wires this to a DB read rather than
+ * src/writes/targeting.ts guessing. Unset → never restart, which is the safe default for any
+ * caller that hasn't opted in.
+ */
+let restartGuard = null;
+export function setRestartGuard(guard) {
+    restartGuard = guard;
+}
+function restartAllowed() {
+    try {
+        return restartGuard?.() ?? false;
+    }
+    catch {
+        return false;
+    }
+}
+/** Fixed targeting values travel in the environment; the three UI labels ride in RELAY_TARGET_FILE. */
+function targetEnv(target) {
+    return {
+        RELAY_ALLOW_RESTART: restartAllowed() ? '1' : '',
+        RELAY_TAB_INDEX: String(target.tab?.index ?? 0),
+        RELAY_TAB_COUNT: String(target.tab?.count ?? 0),
+        RELAY_WS_BRANCH: target.workspace.branch ?? '',
+        RELAY_WS_REPO: target.workspace.repo_name ?? '',
+        RELAY_WS_LINK: workspaceLink(target.workspace.id, target.sessionId)
+    };
+}
+/**
+ * The target file is line-based: tab title, palette query, then sidebar-title candidates. Conductor labels
+ * cannot contain a newline, and `do shell script` reads this file as UTF-8 rather than MacRoman.
+ */
+function targetLines(target) {
+    return [target.tab?.title ?? '', focusQuery(target.workspace), ...sidebarTitles(target.workspace)];
+}
+/**
+ * Give one UI action the three matching labels in a UTF-8 file. `system attribute` decodes text as MacRoman,
+ * but it safely carries the temporary file path.
+ */
+export async function withTargetEnvironment(target, action) {
+    const fs = await import('node:fs/promises');
+    const os = await import('node:os');
+    const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'relay-target-'));
+    const file = path.join(directory, 'text');
+    try {
+        await fs.writeFile(file, targetLines(target).join('\n'), 'utf8');
+        return await action({ ...targetEnv(target), RELAY_TARGET_FILE: file });
+    }
+    finally {
+        await fs.rm(directory, { recursive: true, force: true }).catch(() => undefined);
+    }
+}

package/dist-node/src/writes/types.js

@@ -0,0 +1 @@
+export {};

package/dist-node/src/writes/ui-lock.js

@@ -0,0 +1,229 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { runGatedWorkflowCommand } from "../orchestration/workflow/effect-runner.js";
+const execDirect = promisify(execFile);
+/** Waiting runs past this are refused rather than queued. */
+const MAX_UI_QUEUE = 4;
+const UI_BUSY = "Conductor's UI is busy";
+const uiPriorityScope = new AsyncLocalStorage();
+const uiDispatchScope = new AsyncLocalStorage();
+const uiCommandGateScope = new AsyncLocalStorage();
+const uiLeaseExecutionScope = new AsyncLocalStorage();
+let sharedUiLeaseProvider = null;
+/** Route every subsequent UI turn through a cooperating cross-process lease. */
+export function configureSharedUiLeaseProvider(provider) {
+    sharedUiLeaseProvider = provider;
+}
+/**
+ * Mark one durable effect as dispatched immediately before its first GUI action.
+ * Several UI turns may be needed to configure and send one effect; the shared scope
+ * makes the durable transition exactly once across all of them.
+ */
+export function withUiDispatchHook(hook, fn, actionId) {
+    const context = { hook, actionId, fired: false };
+    return uiDispatchScope.run(context, async () => {
+        try {
+            return await fn();
+        }
+        finally {
+            // The coordinator commits success or ambiguity before its callback settles.
+            // Release here so another process can never enter the window between the GUI
+            // returning and that durable receipt decision.
+            const lease = context.lease;
+            context.lease = undefined;
+            await lease?.release();
+        }
+    });
+}
+/**
+ * Route the first external command executed inside a UI turn through the private
+ * Workflow gate. Read-only probes before the UI turn stay in-process; later UI
+ * turns are already behind a durable may-execute boundary and run normally.
+ */
+export function withGatedUiCommand(onSpawned, fn) {
+    if (uiCommandGateScope.getStore())
+        throw new Error('a gated UI command scope is already active');
+    return uiCommandGateScope.run({ onSpawned }, () => fn(exec));
+}
+function commandEnvironment(environment) {
+    if (!environment)
+        return undefined;
+    return Object.fromEntries(Object.entries(environment).filter((entry) => typeof entry[1] === 'string' && process.env[entry[0]] !== entry[1]));
+}
+/** Execute an external helper, honoring a Workflow's one-shot private command gate. */
+export async function exec(command, args, options = {}) {
+    const gate = uiCommandGateScope.getStore();
+    const execution = uiLeaseExecutionScope.getStore();
+    if (execution && !execution.active)
+        throw new Error('a UI command escaped its shared lease');
+    if (!gate || execution?.gate !== gate)
+        return execDirect(command, args, options);
+    if (execution.commandRunning)
+        throw new Error('gated UI commands must execute sequentially');
+    // Claim synchronously so two accidentally-overlapping commands can never both
+    // obtain a GO descriptor from one durable effect. Sequential commands refresh
+    // the persisted external identity before each new GO.
+    execution.commandRunning = true;
+    try {
+        const result = await runGatedWorkflowCommand({
+            command,
+            args,
+            ...(options.cwd ? { cwd: options.cwd } : {}),
+            ...(options.env ? { env: commandEnvironment(options.env) } : {}),
+            ...(options.timeout === undefined ? {} : { timeoutMs: options.timeout }),
+            ...(options.maxBuffer === undefined ? {} : { maxOutputBytes: options.maxBuffer }),
+            ...(options.signal ? { signal: options.signal } : {}),
+            onSpawned: async (process) => {
+                // Neither commit alone releases the wrapper. GO crosses the pipe only after
+                // both the effect and the cross-process mutex carry this exact identity.
+                await gate.onSpawned(process);
+                await execution.lease?.markMayExecute(process);
+            }
+        });
+        return { stdout: result.stdout, stderr: result.stderr };
+    }
+    finally {
+        execution.commandRunning = false;
+    }
+}
+async function markUiDispatched(context) {
+    if (!context || context.fired)
+        return;
+    if (!context.firing) {
+        context.firing = Promise.resolve()
+            .then(() => context.hook())
+            .then(() => {
+            context.fired = true;
+        });
+    }
+    await context.firing;
+}
+/** Run `fn` with every UI operation it triggers marked at `priority`. */
+export function withUiPriority(priority, fn) {
+    return uiPriorityScope.run(priority, fn);
+}
+export class UiBusyError extends Error {
+    waiting;
+    constructor(waiting) {
+        super(`${UI_BUSY} — ${waiting} operation${waiting === 1 ? '' : 's'} already queued. Try again shortly.`);
+        this.name = 'UiBusyError';
+        this.waiting = waiting;
+    }
+}
+/** Writes stringify `UiBusyError`, so background queues recognize both forms. */
+export function uiBusy(error) {
+    return (error ?? '').startsWith(UI_BUSY);
+}
+let uiRunning = false;
+let uiSeq = 0;
+const uiWaiting = [];
+/** What the UI lock is doing right now — `waiting` excludes the run in flight. */
+export function uiQueueDepth() {
+    return { waiting: uiWaiting.length, busy: uiRunning };
+}
+function pumpUi() {
+    if (uiRunning)
+        return;
+    const next = uiWaiting.shift();
+    if (!next)
+        return;
+    uiRunning = true;
+    next.start();
+}
+/**
+ * Take the lock, run `op`, release it. Exported for `tests/writes/ui-lock.test.ts`,
+ * which is the only way this queue's control flow gets read by anything.
+ */
+export function uiTurn(op) {
+    // High-level Workflow effects hold one cross-process lease through their durable
+    // receipt poll. Existing actuator helpers still call uiTurn internally; reusing
+    // the outer lease keeps that nesting from deadlocking or opening a correlation gap.
+    if (uiLeaseExecutionScope.getStore()?.active)
+        return Promise.resolve().then(op);
+    const rank = uiPriorityScope.getStore() === 'background' ? 1 : 0;
+    // A queued callback is eventually started from the previous owner's async chain,
+    // so capture the effect scope now rather than consulting AsyncLocalStorage later.
+    const dispatch = uiDispatchScope.getStore();
+    const commandGate = uiCommandGateScope.getStore();
+    if (uiWaiting.length >= MAX_UI_QUEUE)
+        return Promise.reject(new UiBusyError(uiWaiting.length));
+    return new Promise((resolve, reject) => {
+        const waiter = {
+            rank,
+            seq: uiSeq++,
+            start: () => {
+                const priority = rank === 1 ? 'background' : 'interactive';
+                const provider = sharedUiLeaseProvider;
+                // Acquire the process-shared lease only after this operation owns the local
+                // priority lock. The dispatch transition follows both locks and precedes the
+                // first instruction in `op`, so a failure before it is provably replayable.
+                const settled = (async () => {
+                    let lease = null;
+                    let releaseHere = true;
+                    try {
+                        lease = dispatch?.lease ?? null;
+                        if (!lease && provider) {
+                            lease = await provider.acquire({
+                                priority,
+                                ...(dispatch?.actionId ? { actionId: dispatch.actionId } : {})
+                            });
+                            if (dispatch)
+                                dispatch.lease = lease;
+                        }
+                        releaseHere = !dispatch;
+                        await markUiDispatched(dispatch);
+                        // An ordinary turn becomes potentially mutating immediately before its
+                        // operation. A Workflow's first external command instead supplies the
+                        // blocked wrapper identity and flips this boundary from inside `exec`.
+                        const pendingGate = commandGate;
+                        if (!pendingGate)
+                            await lease?.markMayExecute();
+                        const execution = {
+                            lease,
+                            commandRunning: false,
+                            active: true,
+                            ...(pendingGate ? { gate: pendingGate } : {})
+                        };
+                        try {
+                            return await uiLeaseExecutionScope.run(execution, op);
+                        }
+                        finally {
+                            execution.active = false;
+                        }
+                    }
+                    finally {
+                        // A lease release participates in the operation's result. In particular, do
+                        // not tell a caller the UI is free while another process still sees us as
+                        // its durable owner.
+                        if (releaseHere)
+                            await lease?.release();
+                    }
+                })();
+                // Release *before* resolving the caller, not after. Settling first and cleaning
+                // up in a chained `.then` frees the lock one microtask late, so code that awaits
+                // a write and then reads `uiQueueDepth()` is told a run is still in flight when
+                // none is — and the next turn starts a tick later than it could.
+                const release = () => {
+                    uiRunning = false;
+                    pumpUi();
+                };
+                settled.then(value => {
+                    release();
+                    resolve(value);
+                }, err => {
+                    release();
+                    reject(err);
+                });
+            }
+        };
+        // Stable insert: by rank, FIFO within a rank. A background run already started
+        // keeps the lock — this decides who is next, never who is interrupted.
+        const at = uiWaiting.findIndex(w => w.rank > rank);
+        if (at < 0)
+            uiWaiting.push(waiter);
+        else
+            uiWaiting.splice(at, 0, waiter);
+        pumpUi();
+    });
+}

package/dist-node/src/writes/workspaces.js

@@ -0,0 +1,233 @@
+import path from 'node:path';
+import { CONDUCTOR_HANDLERS, osaError, SEND_ATTEMPT_MS } from "./runner.js";
+import { CONDUCTOR_SCHEME, focusQuery, withTargetEnvironment } from "./targeting.js";
+import { exec, uiTurn } from "./ui-lock.js";
+/**
+ * Put a workspace away — Conductor's own "Archive workspace" (Command-Shift-A),
+ * pressed on the workspace this run has just focused and asserted.
+ *
+ * The chord acts on whatever the pane is showing, so the assertion is the entire
+ * guard and the branch is required rather than optional, exactly as it is for
+ * `stopTurn`. The damage is worse here than a mis-aimed prompt: archiving deletes
+ * the worktree and takes any agent mid-turn down with it, so a workspace whose pane
+ * cannot be checked is refused instead of guessed at.
+ *
+ * `stopAgents` is what the caller has said about that second half. Conductor draws a
+ * confirmation ("Stop agents and archive") when the workspace still has an agent
+ * working, and the script presses it only with this set; without it the dialog is
+ * dismissed and the run fails, so a tap that meant "archive" can never quietly end
+ * someone else's turn. An idle workspace draws no dialog at all.
+ *
+ * Nothing is confirmed here. `workspaces.state` becoming `archived` is the receipt
+ * and src/http/routes/workspaces.ts waits for it, the same way the stop and the status change do.
+ */
+export async function archiveWorkspace(workspace, stopAgents) {
+    if (!workspace.branch) {
+        return { ok: false, strategy: 'applescript', error: 'workspace has no branch to focus' };
+    }
+    const script = `
+${CONDUCTOR_HANDLERS}
+
+my activateConductor()
+my focusWorkspace()
+my archiveWorkspace()
+return "ok"`.trim();
+    try {
+        await withTargetEnvironment({ workspace, sessionId: null }, targetEnvironment => uiTurn(() => exec('osascript', ['-e', script], {
+            env: { ...process.env, ...targetEnvironment, RELAY_ARCHIVE_AGENTS: stopAgents ? '1' : '' },
+            timeout: SEND_ATTEMPT_MS
+        })));
+        return { ok: true, strategy: 'applescript' };
+    }
+    catch (err) {
+        return { ok: false, strategy: 'applescript', error: osaError(err) };
+    }
+}
+/**
+ * Continue a merged workspace on a new branch through Conductor's own Continue
+ * button. This deliberately does not perform `git checkout` itself: the native
+ * action also updates Conductor's workspace identity, preserves the existing
+ * sessions, clears the merged PR metadata, and stages its Branch continued.md
+ * context in the selected chat. Reproducing only the git half would leave the DB
+ * and UI describing the branch we just moved away from; writing the DB is forbidden.
+ *
+ * The exact chat matters even though every chat survives. Conductor attaches the
+ * continuation note to the selected one, so the target carries the phone's current
+ * session and `selectChatTab` asserts it before the button is found. The button is
+ * available only in Conductor's merged action bar; an absent or ambiguous control
+ * fails closed. src/http/routes/workspaces.ts confirms success from the resulting branch change.
+ */
+export async function continueWorkspace(target) {
+    if (!target.workspace.branch) {
+        return { ok: false, strategy: 'applescript', error: 'workspace has no branch to focus' };
+    }
+    const script = `
+${CONDUCTOR_HANDLERS}
+
+my activateConductor()
+my focusWorkspace()
+my selectChatTab()
+my continueWorkspaceOnNewBranch()
+return "ok"`.trim();
+    try {
+        await withTargetEnvironment(target, targetEnvironment => uiTurn(() => exec('osascript', ['-e', script], {
+            env: { ...process.env, ...targetEnvironment },
+            timeout: SEND_ATTEMPT_MS
+        })));
+        return { ok: true, strategy: 'applescript' };
+    }
+    catch (err) {
+        return { ok: false, strategy: 'applescript', error: osaError(err) };
+    }
+}
+/**
+ * The workspace statuses Conductor's sidebar groups by, mapped from the value it
+ * stores in `workspaces.manual_status` to the label on its own menu. `canceled`
+ * is on the menu but has never been written in this DB, so it's the one spelling
+ * here that is taken from the UI rather than confirmed against stored data — a
+ * mismatch surfaces as a failed confirmation naming what Conductor actually wrote.
+ */
+export const WORKSPACE_STATUS_LABELS = {
+    backlog: 'Backlog',
+    'in-progress': 'In progress',
+    'in-review': 'In review',
+    done: 'Done',
+    canceled: 'Canceled'
+};
+/**
+ * Move a workspace between the sidebar's status groups — the thing a merged PR
+ * that Conductor never linked can't do for itself.
+ *
+ * Unlike every other write here this one never changes what's on screen: it
+ * right-clicks the workspace's *row* (AXShowMenu) and works the menu, so the
+ * workspace you were reading stays open. It does need the row to be rendered, and
+ * a collapsed sidebar section renders none — so the script opens the folded
+ * sections itself, looks again, and folds back exactly the ones it opened. That
+ * costs a second sidebar scan, which is affordable only because that scan reads
+ * every row's name in two Apple events rather than one per row (15s → ~1s on a
+ * 50-workspace sidebar; see findSidebarRow). Measured end to end on 2026-09-01:
+ * 8.2s through a folded section, 5.4s through an open one. The budget is 35s
+ * anyway, because sidebarRowsAndNames falls back to the per-row reads when the
+ * list no longer matches its shape, and that path pays the old 15s twice.
+ */
+export async function setWorkspaceStatus(workspace, status) {
+    const label = WORKSPACE_STATUS_LABELS[status];
+    if (!label)
+        return { ok: false, strategy: 'applescript', error: `unknown status ${status}` };
+    const script = `
+${CONDUCTOR_HANDLERS}
+
+my activateConductor()
+my setWorkspaceStatus()
+return "ok"`.trim();
+    try {
+        await withTargetEnvironment({ workspace, sessionId: null }, targetEnvironment => uiTurn(() => exec('osascript', ['-e', script], {
+            env: {
+                ...process.env,
+                ...targetEnvironment,
+                RELAY_SET_STATUS: label
+            },
+            timeout: 35000
+        })));
+        return { ok: true, strategy: 'applescript' };
+    }
+    catch (err) {
+        return { ok: false, strategy: 'applescript', error: osaError(err) };
+    }
+}
+/**
+ * Create a *new workspace*, optionally with a first prompt, via Conductor's
+ * deep-link scheme (conductor.build/docs/reference/deep-links).
+ *
+ * This is the one write here that touches no UI at all: no Accessibility, no
+ * keystrokes, no focus dependency — macOS hands the URL to Conductor and it
+ * creates the worktree. Nothing to rebreak on an update, unlike every other
+ * path in this file.
+ *
+ * Three things the scheme dictates:
+ *  - Parameters sit *flat* after the scheme (`conductor://prompt=…&path=…`), not
+ *    behind a `?`, and every value must be URL-encoded — which is also what stops
+ *    a prompt containing `&path=` from redirecting the workspace to another repo.
+ *  - **An unmatched (or absent) `path` silently falls back to the first repo**, so
+ *    the caller resolves a real `root_path` first rather than trusting a name.
+ *  - **`prompt` is optional**: a bare `conductor://path=…` opens an empty
+ *    workspace, same as Conductor's own New workspace. That form isn't in the
+ *    docs (every documented route carries a prompt) but is verified against the
+ *    live app — so if it ever stops working, this is the line to suspect.
+ *
+ * The link is fire-and-forget: it reports that Conductor was *handed* the URL,
+ * never that a workspace appeared. The caller watches the DB for that.
+ */
+export async function createWorkspace(prompt, repoPath) {
+    if (!prompt.trim() && !repoPath) {
+        return { ok: false, strategy: 'deeplink', error: 'a new workspace needs a repo or a first prompt' };
+    }
+    const query = [
+        prompt.trim() ? `prompt=${encodeURIComponent(prompt)}` : '',
+        repoPath ? `path=${encodeURIComponent(repoPath)}` : ''
+    ]
+        .filter(Boolean)
+        .join('&');
+    try {
+        // Serialized with the AX writes: creating a workspace pulls Conductor forward and
+        // switches which one is showing, which is precisely what a concurrent send assumes.
+        await uiTurn(() => exec('open', [`${CONDUCTOR_SCHEME}://${query}`], { timeout: 15000 }));
+        return { ok: true, strategy: 'deeplink' };
+    }
+    catch (err) {
+        return { ok: false, strategy: 'deeplink', error: osaError(err) };
+    }
+}
+/**
+ * Start one exact workspace Run task, or stop the running one, through Conductor's toolbar.
+ *
+ * The task stays owned by Conductor — it appears in the Run panel, inherits the
+ * repository's run mode and environment, and Conductor performs its normal
+ * process-group shutdown. A named start selects that item from Conductor's own
+ * Run menu; an unnamed legacy start proceeds only when the live menu contains one
+ * task. Every path focuses and asserts the target workspace before touching it.
+ */
+export async function setRunTask(workspace, running, runTaskName) {
+    if (!focusQuery(workspace))
+        return { ok: false, error: 'workspace has no branch to focus' };
+    const script = `
+${CONDUCTOR_HANDLERS}
+
+set wantRunning to (system attribute "RELAY_RUN_WANTED") is "1"
+set wantedTask to do shell script "cat " & quoted form of (system attribute "RELAY_RUN_TASK_FILE")
+return my setRunTask(wantRunning, wantedTask)`.trim();
+    const os = await import('node:os');
+    const fs = await import('node:fs/promises');
+    const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'relay-run-task-'));
+    const taskFile = path.join(directory, 'name');
+    try {
+        await fs.writeFile(taskFile, runTaskName ?? '', 'utf8');
+        const { stdout } = await withTargetEnvironment({ workspace, sessionId: workspace.active_session_id }, targetEnvironment => uiTurn(() => exec('osascript', ['-e', script], {
+            env: {
+                ...process.env,
+                ...targetEnvironment,
+                RELAY_RUN_WANTED: running ? '1' : '0',
+                RELAY_RUN_TASK_FILE: taskFile
+            },
+            timeout: SEND_ATTEMPT_MS
+        })));
+        const [state, task, changed, rawPorts = '', rawPreviewUrls = ''] = stdout.trim().split('\t');
+        if (state !== 'running' && state !== 'stopped')
+            throw new Error(`unexpected Run state: ${state || 'empty'}`);
+        const ports = rawPorts
+            .split(',')
+            .map(Number)
+            .filter(port => Number.isInteger(port) && port > 0 && port <= 65535);
+        const previewUrls = rawPreviewUrls
+            .split('\x1e')
+            .map(url => url.trim())
+            .filter(Boolean);
+        return { ok: true, state, task, changed: changed === 'true', previewUrls, ports };
+    }
+    catch (err) {
+        return { ok: false, error: osaError(err, 'Conductor took too long to change the Run task') };
+    }
+    finally {
+        await fs.rm(directory, { recursive: true, force: true }).catch(() => undefined);
+    }
+}