@detergent-software/conductor 1.0.0-dev.17 → 1.0.0-dev.19

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 Releases are tagged `conductor-v<version>` and staged on npm by `atk-conductor-release` (`pipelines/release-conductor.yml`), which writes each section below. `scripts/check-changelog.mjs` fails when a tag has no section here.
 
+## [1.0.0-dev.19](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTconductor-v1.0.0-dev.18&targetVersion=GTconductor-v1.0.0-dev.19) (2026-10-11)
+
+### Features
+
+* **conductor:** show the broker's locks in conduct status (ATK-372) ([77a3f54](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/77a3f547e15a653a9e4dbc8a1308e5118ac5492d))
+
+### Bug Fixes
+
+* **conductor:** keep the daemon's reason when GET /locks fails (ATK-372) ([79f3e69](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/79f3e6979c2475612ff6b4a8780cb1dd01fa9718))
+
+## [1.0.0-dev.18](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTconductor-v1.0.0-dev.17&targetVersion=GTconductor-v1.0.0-dev.18) (2026-10-11)
+
+### Features
+
+* **conductor:** port broker and shared locks across projects (ATK-318) ([90a46d0](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/90a46d0827dd805668fc98c11b4082487f9bd806))
+
+### Bug Fixes
+
+* **conductor:** review fixes for the port broker (ATK-318) ([db0bf0d](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/db0bf0de8d0404d155ad2d95ac32923ab5d0fb7f))
+
 ## [1.0.0-dev.17](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTconductor-v1.0.0-dev.16&targetVersion=GTconductor-v1.0.0-dev.17) (2026-10-11)
 
 ### Features

package/README.md

@@ -1,6 +1,6 @@
 # Conductor
 
-`@detergent-software/conductor`: the local daemon that runs the work loop for every conducted project on this machine, and its `conduct` CLI. The design, decisions and build order are in the Linear document *Conductor: design note* (project *Conductor daemon*). This package has build step 1, the skeleton (ATK-308), step 2, the session manager (ATK-309), step 3, the watchers and `conduct wait` (ATK-310), the daemon's side of step 4, worker protocol v1's `conduct note` (ATK-311), step 5, the inbox with `conduct approve` / `revise` (ATK-312), step 6, the notifier (ATK-313), step 9, the conductor mod for Claude Code in `mod/` (ATK-265), step 8, the scheduler, settings and rules (ATK-315), and the daemon's side of step 7, the console (ATK-314).
+`@detergent-software/conductor`: the local daemon that runs the work loop for every conducted project on this machine, and its `conduct` CLI. The design, decisions and build order are in the Linear document *Conductor: design note* (project *Conductor daemon*). This package has build step 1, the skeleton (ATK-308), step 2, the session manager (ATK-309), step 3, the watchers and `conduct wait` (ATK-310), the daemon's side of step 4, worker protocol v1's `conduct note` (ATK-311), step 5, the inbox with `conduct approve` / `revise` (ATK-312), step 6, the notifier (ATK-313), step 9, the conductor mod for Claude Code in `mod/` (ATK-265), step 8, the scheduler, settings and rules (ATK-315), the daemon's side of step 7, the console (ATK-314), and step 12, the port broker (ATK-318).
 
 ## Commands
 
@@ -8,7 +8,7 @@
 conduct serve                     run the daemon in this process (one per machine)
 conduct start                     start the daemon detached and wait until it answers (see Console)
 conduct stop                      stop the running daemon
-conduct status [--json]           the daemon's pid, port, projects and workers
+conduct status [--json]           the daemon's pid, port, projects, workers and held locks
 conduct project add <path>        register the project whose checkout holds .claude/conductor.json
 conduct project list [--json]     the registered projects
 conduct launch <item>             start a worker: worktree, background session, tab
@@ -48,6 +48,10 @@ conduct rules test <file> [--json]
 conduct note <item> <file>        post a phase note on the item and record its phase (see Notes)
     [--worker <worker>]
 conduct wait <condition>          wait for an outside event (see Waits)
+conduct ports [<path>] [--prefer <slot>] [--json]
+                                  a checkout's dev ports from the port broker, or every worktree's (see Broker)
+conduct lock acquire|release|status <name> [--owner <id>] [--wait <minutes>]
+                                  a lock every project shares, such as chrome (see Broker)
 conduct events [--since <id>] [--follow]
                                   the event log, one JSON event per line (see API)
 conduct install-startup           start the daemon at logon (Windows Task Scheduler)
@@ -254,6 +258,29 @@ A worker waits by posting its note, running `conduct wait …` and ending the tu
 
 **Watchers.** One per API: Linear (GraphQL with `LINEAR_API_KEY` or the `atk-conductor-linear` credential, ported from conduct-atk), Azure DevOps (REST with the `az login` token), GitHub (`gh api`), npm (the registry's dist-tags, no cache) and `/health`. Time waits are the session manager's sweep. An API is asked nothing while no wait needs it. Otherwise it's asked once per `watchers.<api>.intervalSeconds`, within `perMinute` requests in any rolling minute shared by every project. Each pass covers all of that API's waits in as few requests as it can; Linear's is one request, filtered on `updatedAt` (with a 2-minute overlap) after the first. A pass that runs out of budget stops, and the next one starts a wait further on. A failing API waits twice as long each time (up to 10 minutes) and logs `watcher.failed` once, then `watcher.recovered`. A wait that can't be checked logs `wait.check-failed` once and stays open. Every `watchers.statsMinutes` (10) in which anything waited, a `watcher.stats` event records each API's passes, requests, budget skips, failures and waits.
 
+## Broker
+
+The broker shares what every project on the machine uses (ATK-318).
+
+**Ports.** Each profile declares its dev servers' base ports by name, such as ATK's `"ports": { "web": 3000, "api": 7071, "maxSlot": 50 }` or `{ "web": 3000 }`.
+- A main checkout serves on the base ports (slot 0).
+- Each worktree gets a slot from 1 to `maxSlot` (default 50) and serves on base + slot. `conduct ports <path>` gives it the first slot whose ports no other checkout of any registered project has and nothing listens on, `--prefer` first. It's the same answer each time after that.
+- A retired worker's worktree frees its slot, and so does a worktree whose directory is gone (at the next assignment).
+- Ports are compared, not slots, so projects with different bases stay apart too.
+- A project's dev scripts read the assignment with `--json`, as ATK's `scripts/dev-ports.mjs assign` does. They keep their own scheme when it exits 3: no daemon, an older one, or a checkout in no registered project.
+- The broker knows only the slots it gave out. A slot a script picked on its own while no daemon answered stays unknown until that worktree asks the broker; until then only the listening probe keeps the slot clear. So `--prefer` is the slot the script would pick itself (`dev-ports.mjs` passes the checkout's own slot or its own free-slot scan's). The preferred slot is taken without the listening probe, because the checkout's own servers may be what listens there.
+- A stored assignment follows its project's profile: when the base ports or `maxSlot` change, the worktree moves, its old slot first.
+
+**Locks.** `conduct lock acquire chrome` takes the lock every project's verify runs share. It answers the work-issue helper's JSON (`acquired`, `heldBy`, `since`, `refreshed`; `released` for a release; `verdict` for a status).
+- The owner is `--owner`, else the item of the worker whose worktree this is.
+- Acquiring again refreshes it. 30 minutes after its holder last acquired it, another owner may take it over.
+- `--wait <minutes>` asks again every 15 s until then.
+- Retiring a worker releases the locks its item holds (a probe's retire doesn't).
+- `conduct status` lists the locks held, each with its holder, its last acquire and whether it is stale.
+- Exit 3 when no daemon answers.
+
+Events: `ports.assigned`, `ports.freed`, `lock.acquired`, `lock.released`, `lock.taken-over`.
+
 ## History
 
 `conduct history` and `conduct retro` read a window of the log and say what happened in it, so a review of a conducted run needs no transcripts. Both are queries over `conductor.db`, so they work without a daemon too (or with one older than this build).
@@ -324,6 +351,8 @@ Everything lives in `~/.conductor` (`CONDUCTOR_HOME` overrides it):
 - `GET /history?since=<ISO time>&until=<ISO time>&project=<name>`: the report for that window (see History). Every parameter is optional; the default window is the 24 hours before `until` (default: now). 400 for a time it can't read, a window whose start isn't before its end, or an unknown parameter.
 - `GET /why/:id`: the event's chain of causes and the rule behind it; `GET /why?item=ATK-315` the same for the item's newest actions.
 - `POST /rules/test` with `{ "event"?: "pr.comment", "project"?: "atk", "fields"?: { … } }`: a dry run; 400 for a sample it can't read.
+- `GET /ports`: every worktree's port assignment. `POST /ports` with `{ "worktree": "<absolute path>", "prefer"?: 3 }`: the checkout's (see Broker); 200 with `assignment`, 409 when the path is in no registered project or no slot is free.
+- `GET /locks`: the locks held. `POST /locks/:name` with `{ "action": "acquire" | "release" | "status", "owner"? }`: 200 with the work-issue helper's lock JSON; 409 for an acquire or release without an owner.
 - `POST /waits` with `{ "worker": 1, "condition": "pr:ado:Emergent.AgenticToolkit#1850:merged" }`: a wait in its full form (see Waits), stored in its normal form; 201 with the wait. `GET /waits/:id` shows one, with its resolution once it has one.
 - A refusal (a duplicate launch, a bad condition, a busy worker) is a 409 with `error` and `details`.
 

package/build/broker-cli.js

@@ -0,0 +1,125 @@
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { lockVerdict } from "./broker.js";
+import { callApi, NotRunningError } from "./client.js";
+import { ConductorError } from "./errors.js";
+import { lockSchema, portAssignmentSchema } from "./store.js";
+import { daemonWorker, gitToplevel } from "./wait.js";
+// Exit code when no daemon brokered the request: none runs, an older one has no broker, or it
+// refused (a checkout in no registered project, no free slot). The caller keeps its own scheme,
+// as ATK's scripts/dev-ports.mjs and the work-issue helper's file lock do.
+export const NOT_BROKERED = 3;
+// How often `conduct lock acquire --wait` asks again, as the work-issue helper's lock does.
+const LOCK_POLL_MS = 15_000;
+const errorBody = z.object({ details: z.array(z.string()).optional(), error: z.string() });
+const lockAnswer = z.looseObject({ acquired: z.boolean().optional(), lock: z.string() });
+// The broker's locks for `conduct status`, or null from a daemon older than the broker.
+export async function heldLocks(paths, now = new Date()) {
+    const answer = await callApi(paths, { method: 'GET', path: '/locks' });
+    if (answer.status === 404)
+        return null;
+    if (answer.status !== 200) {
+        const refusal = errorBody.safeParse(answer.body).data;
+        throw new ConductorError(refusal?.error ?? `the API answered ${answer.status} for the locks`, refusal?.details ?? []);
+    }
+    return z
+        .object({ locks: z.array(lockSchema) })
+        .parse(answer.body)
+        .locks.map((lock) => ({ ...lock, verdict: lockVerdict(lock, null, now) === 'stale' ? 'stale' : 'held' }));
+}
+// `conduct lock <acquire|release|status> <name>`: the broker's named lock, such as chrome, which
+// verify skills of every project take turns with. Prints the work-issue helper's JSON. The owner
+// is --owner, else the item of the worker whose worktree this is.
+export async function lockCommand(paths, action, name, options, io) {
+    if (action !== 'acquire' && action !== 'release' && action !== 'status')
+        throw new ConductorError('usage: conduct lock <acquire|release|status> <name> [--owner <id>] [--wait <minutes>]');
+    if (!/^[\w-]+$/.test(name))
+        throw new ConductorError(`a lock name is letters, digits, _ and -, not "${name}"`);
+    let owner = options.owner?.trim() || null;
+    if (owner === null) {
+        const worker = await daemonWorker(paths, await gitToplevel(io.cwd), undefined);
+        if (worker === 'no-daemon')
+            return notBrokered(io, 'the conductor is not running');
+        if (worker === 'unreachable')
+            throw new ConductorError("the conductor didn't answer");
+        owner = worker?.item ?? null;
+        if (owner === null && action !== 'status')
+            throw new ConductorError('no worker of the conductor works in this checkout: pass --owner <id>');
+    }
+    const until = Date.now() + (options.waitMinutes ?? 0) * 60_000;
+    const sleep = io.sleep ?? ((ms) => new Promise((done) => setTimeout(done, ms)));
+    for (;;) {
+        const answer = await ask(paths, { body: { action, ...(owner === null ? {} : { owner }) }, method: 'POST', path: `/locks/${name}` });
+        if (!answer.ok)
+            return notBrokered(io, answer.why);
+        const body = lockAnswer.parse(answer.body);
+        if (action !== 'acquire' || body.acquired !== false || Date.now() >= until) {
+            io.out(JSON.stringify(body, null, 2));
+            return 0;
+        }
+        await sleep(LOCK_POLL_MS);
+    }
+}
+// One line per lock: name, holder, and its last acquire.
+export function lockLine(lock) {
+    return `  ${lock.name}  ${lock.holder} since ${new Date(lock.since).toLocaleString()}${lock.verdict === 'stale' ? '  (stale: free to take over)' : ''}`;
+}
+// `conduct ports [<path>]`: the checkout's dev ports from the broker, or every assignment.
+export async function portsCommand(paths, path, options, io) {
+    if (path === undefined) {
+        const answer = await ask(paths, { method: 'GET', path: '/ports' });
+        if (!answer.ok)
+            return notBrokered(io, answer.why);
+        const assignments = z.object({ assignments: z.array(portAssignmentSchema) }).parse(answer.body).assignments;
+        if (options.json)
+            io.out(JSON.stringify(assignments, null, 2));
+        else if (assignments.length === 0)
+            io.out('no worktree has ports from the conductor');
+        else
+            assignments.forEach((a) => io.out(portsLine(a)));
+        return 0;
+    }
+    const answer = await ask(paths, {
+        body: { worktree: resolve(io.cwd, path), ...(options.prefer === undefined ? {} : { prefer: options.prefer }) },
+        method: 'POST',
+        path: '/ports',
+    });
+    if (!answer.ok)
+        return notBrokered(io, answer.why);
+    const { assignment } = z.object({ assignment: portAssignmentSchema }).parse(answer.body);
+    io.out(options.json ? JSON.stringify(assignment, null, 2) : portsLine(assignment));
+    return 0;
+}
+// One line per checkout: project, slot, each port, then where.
+export function portsLine(a) {
+    const ports = Object.entries(a.ports)
+        .map(([name, port]) => `${name} ${port}`)
+        .join(' · ');
+    return `${a.project}  slot ${a.slot}  ${ports}  ${a.worktree}`;
+}
+// The body of a 200 answer, or why nothing was brokered.
+async function ask(paths, request) {
+    let answer;
+    try {
+        answer = await callApi(paths, request);
+    }
+    catch (error) {
+        if (error instanceof NotRunningError)
+            return { ok: false, why: 'the conductor is not running' };
+        throw error;
+    }
+    if (answer.status === 200)
+        return { body: answer.body, ok: true };
+    // A daemon from before the broker has no such route.
+    if (answer.status === 404)
+        return { ok: false, why: 'this conductor has no port broker (upgrade it)' };
+    const refusal = errorBody.safeParse(answer.body).data;
+    if (answer.status === 409 && refusal)
+        return { ok: false, why: [refusal.error, ...(refusal.details ?? [])].join('; ') };
+    throw new ConductorError(refusal?.error ?? `the API answered ${answer.status}`, refusal?.details ?? []);
+}
+function notBrokered(io, why) {
+    io.err(`not brokered: ${why}`);
+    return NOT_BROKERED;
+}
+//# sourceMappingURL=broker-cli.js.map

package/build/broker-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"broker-cli.js","sourceRoot":"","sources":["../src/broker-cli.ts"],"names":[],"mappings":"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"}

package/build/broker.js

@@ -0,0 +1,154 @@
+import { existsSync } from 'node:fs';
+import { connect } from 'node:net';
+import { ConductorError } from "./errors.js";
+import { samePath } from "./paths.js";
+import { basePorts } from "./profile.js";
+import { checkoutOf } from "./registry.js";
+import {} from "./store.js";
+// The broker shares what every project on the machine uses (design note, sections 3 and 12): dev
+// server ports, so two projects' worktrees never serve on the same port, and named locks such as
+// chrome, so verify skills of different projects take turns with the one browser.
+// A holder keeps a lock by acquiring it again; one it hasn't acquired for this long is free to take
+// over. The same rule as the work-issue helper's file lock.
+export const LOCK_STALE_MS = 30 * 60_000;
+const MAX_PORT = 65_535;
+export function broker({ exists = existsSync, listening = portListening, now = () => new Date(), store }) {
+    // One assignment at a time: each waits on port probes, and two at once could pick the same slot.
+    let assigning = Promise.resolve();
+    // Frees the ports of worktrees whose directory is gone, such as one /worktree-gc removed.
+    const sweep = () => {
+        for (const held of store.portAssignments())
+            if (!exists(held.worktree))
+                freePorts(store, held.worktree, 'worktree gone');
+        return store.portAssignments();
+    };
+    const assign = async (path, wanted) => {
+        const { checkout, root } = checkoutOf(path);
+        const projects = store.listProjects();
+        const project = projects.find((p) => samePath(p.root, root));
+        if (!project)
+            throw new ConductorError(`${checkout} is in no registered project`, ['`conduct project add <path>` registers one']);
+        const profile = profileOf(project);
+        const base = basePorts(profile);
+        if (samePath(checkout, root))
+            return { assignedAt: null, ports: base, project: project.name, slot: 0, worktree: checkout };
+        const portsOf = (slot) => Object.fromEntries(Object.entries(base).map(([name, port]) => [name, port + slot]));
+        let prefer = wanted;
+        const held = sweep().find((a) => samePath(a.worktree, checkout));
+        if (held) {
+            // Kept while the profile still gives its slot those ports; otherwise it moves, its old slot first.
+            if (held.slot <= profile.ports.maxSlot && samePorts(held.ports, portsOf(held.slot)))
+                return held;
+            freePorts(store, held.worktree, 'profile changed');
+            prefer ??= held.slot;
+        }
+        // Every main checkout's ports, and every worktree's.
+        const taken = new Set([
+            ...projects.flatMap((p) => (p.profile ? Object.values(basePorts(p.profile)) : [])),
+            ...store.portAssignments().flatMap((a) => Object.values(a.ports)),
+        ]);
+        const slots = Array.from({ length: profile.ports.maxSlot }, (_, i) => i + 1);
+        const order = prefer !== undefined && slots.includes(prefer) ? [prefer, ...slots.filter((s) => s !== prefer)] : slots;
+        for (const slot of order) {
+            const ports = portsOf(slot);
+            const values = Object.values(ports);
+            if (values.some((port) => port > MAX_PORT || taken.has(port)))
+                continue;
+            // The preferred slot is the one the checkout already serves on (its own scheme gave it), so
+            // its own dev servers may be what listens there.
+            if (slot !== prefer && (await Promise.all(values.map(listening))).some(Boolean))
+                continue;
+            const assignment = store.savePorts({ ports, project: project.name, slot, worktree: checkout });
+            store.appendEvent({ data: { ports, slot, worktree: checkout }, kind: 'ports.assigned', project: project.name });
+            return assignment;
+        }
+        throw new ConductorError(`no free slot between 1 and ${profile.ports.maxSlot} for ${checkout}`, [
+            '`conduct ports` lists the assignments; a removed worktree frees its slot',
+        ]);
+    };
+    return {
+        assignPorts: (path, prefer) => {
+            const next = assigning.then(() => assign(path, prefer));
+            assigning = next.catch(() => { });
+            return next;
+        },
+        lock: (name, action, owner) => {
+            const current = store.getLock(name);
+            const verdict = lockVerdict(current, owner, now());
+            if (action === 'status')
+                return { lock: name, verdict, ...(current ? { heldBy: current.holder, since: current.since } : {}) };
+            if (owner === null)
+                throw new ConductorError(`an owner is needed to ${action} a lock`);
+            if (action === 'release') {
+                if (verdict === 'mine') {
+                    store.deleteLock(name);
+                    store.appendEvent({ data: { holder: owner }, kind: 'lock.released', subject: name });
+                }
+                return { lock: name, released: verdict === 'mine', ...(current && verdict !== 'mine' ? { heldBy: current.holder } : {}) };
+            }
+            if (current && verdict === 'held')
+                return { acquired: false, heldBy: current.holder, lock: name, since: current.since };
+            store.saveLock(name, owner);
+            if (verdict === 'stale' && current) {
+                store.appendEvent({ data: { holder: owner, previous: current.holder, since: current.since }, kind: 'lock.taken-over', subject: name });
+            }
+            else if (verdict === 'free') {
+                store.appendEvent({ data: { holder: owner }, kind: 'lock.acquired', subject: name });
+            }
+            return { acquired: true, lock: name, owner, ...(verdict === 'mine' ? { refreshed: true } : {}) };
+        },
+        locks: () => store.listLocks(),
+        portAssignments: sweep,
+    };
+}
+// Frees the ports of a worktree (a retired worker's, or one whose directory is gone).
+export function freePorts(store, worktree, reason) {
+    for (const held of store.portAssignments()) {
+        if (!samePath(held.worktree, worktree))
+            continue;
+        store.deletePorts(held.worktree);
+        store.appendEvent({ data: { ports: held.ports, reason, slot: held.slot, worktree: held.worktree }, kind: 'ports.freed', project: held.project });
+    }
+}
+export function lockVerdict(lock, owner, now) {
+    if (!lock)
+        return 'free';
+    if (owner !== null && lock.holder === owner)
+        return 'mine';
+    const since = Date.parse(lock.since);
+    return Number.isNaN(since) || now.getTime() - since > LOCK_STALE_MS ? 'stale' : 'held';
+}
+// True when something accepts connections on the port, on IPv4 or IPv6 loopback.
+export async function portListening(port) {
+    const probe = (host) => new Promise((done) => {
+        const socket = connect({ host, port });
+        const finish = (open) => {
+            socket.destroy();
+            done(open);
+        };
+        socket.setTimeout(300, () => finish(false));
+        socket.once('connect', () => finish(true));
+        socket.once('error', () => finish(false));
+    });
+    return (await Promise.all(['127.0.0.1', '::1'].map(probe))).some(Boolean);
+}
+// Releases every lock the holder has, such as a retired worker's item.
+export function releaseLocks(store, holder, reason) {
+    for (const lock of store.listLocks()) {
+        if (lock.holder !== holder)
+            continue;
+        store.deleteLock(lock.name);
+        store.appendEvent({ data: { holder, reason }, kind: 'lock.released', subject: lock.name });
+    }
+}
+function profileOf(project) {
+    if (project.profile)
+        return project.profile;
+    throw new ConductorError(`project ${project.name}'s stored profile is invalid: ${project.problem ?? 'unknown'}`, [
+        '`conduct project add <path>` reads it again',
+    ]);
+}
+function samePorts(a, b) {
+    return Object.keys(a).length === Object.keys(b).length && Object.entries(b).every(([name, port]) => a[name] === port);
+}
+//# sourceMappingURL=broker.js.map

package/build/broker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"broker.js","sourceRoot":"","sources":["../src/broker.ts"],"names":[],"mappings":"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"}

package/build/cli.js

@@ -5,6 +5,7 @@ import { resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import { z } from 'zod';
+import { heldLocks, lockCommand, lockLine, portsCommand } from "./broker-cli.js";
 import { callApi, NotRunningError, ping, readEndpoint } from "./client.js";
 import { loadConfig } from "./config.js";
 import { CONSOLE_ARGS, CONSOLE_WINDOW, consoleProject, consoleTabArgs, escalationLines, escalationSchema, handledSchema } from "./console.js";
@@ -38,7 +39,7 @@ const USAGE = `Usage: conduct <command>
   start                     start the daemon detached (the logon task, else a detached serve) and
                             wait until it answers; nothing when it runs already
   stop                      stop the running daemon
-  status [--json]           the daemon's pid, port, projects and workers
+  status [--json]           the daemon's pid, port, projects, workers and held locks
   project add <path>        register the project whose checkout holds .claude/conductor.json
   project list [--json]     the registered projects
   launch <item>             start a worker: its worktree, a background session, a tab
@@ -103,6 +104,16 @@ const USAGE = `Usage: conduct <command>
       time <when>             such as 17:00 (the next one) or 2026-10-10T09:00 (local)
       <full form>             such as pr:ado:Emergent.AgenticToolkit#1850:merged
       [--local] [--timeout <minutes, local only; 29>] [--worker <worker>] [--item <item>]
+  ports [<path>] [--prefer <slot>] [--json]
+                            the checkout's dev ports from the port broker: its project's base ports
+                            + its slot, which no other project's worktree shares (a main checkout:
+                            slot 0); --prefer asks for a slot first. Without <path>, every worktree's.
+                            Exit 3 when no conductor brokered it, so the caller keeps its own ports
+  lock acquire|release|status <name> [--owner <id>] [--wait <minutes>]
+                            a lock every project shares, such as chrome for verify runs; stale 30 min
+                            after its holder last acquired it (acquire again to keep it). The owner is
+                            this checkout's worker's item unless given; --wait polls. Prints JSON;
+                            exit 3 when no conductor answers
   events [--since <id>]     the event log after <id> (all of it without), one JSON event per line
   events --follow [--since <id>]
                             keep following it (live without --since), reconnecting when the
@@ -218,6 +229,10 @@ async function awaitDaemon(paths) {
     }
     throw new ConductorError(`the conductor did not answer within ${START_WAIT_MS / 1000} s`, [`see ${paths.log}`]);
 }
+// What `conduct ports` and `conduct lock` print to and run in.
+function brokerIo() {
+    return { cwd: process.cwd(), err: (line) => process.stderr.write(`${line}\n`), out };
+}
 // `conduct console`: the console (design note, section 11), the Claude session the conductor mod
 // serves, started with CONDUCTOR_CONSOLE=1 in the project's main checkout, where the console skill
 // is installed. It keeps no state of its own, so a new one after a close loses nothing.
@@ -442,6 +457,8 @@ async function main(argv) {
             here: { type: 'boolean' },
             json: { type: 'boolean' },
             kind: { type: 'string' },
+            owner: { type: 'string' },
+            prefer: { type: 'string' },
             probe: { type: 'boolean' },
             project: { type: 'string' },
             prompt: { type: 'string' },
@@ -453,6 +470,7 @@ async function main(argv) {
             text: { type: 'string' },
             until: { type: 'string' },
             version: { short: 'v', type: 'boolean' },
+            wait: { type: 'string' },
             weight: { type: 'string' },
             worker: { type: 'string' },
         },
@@ -502,6 +520,15 @@ async function main(argv) {
                 project: values.project,
                 prompt: values.prompt,
             });
+        case 'lock': {
+            if (sub === undefined || arg === undefined)
+                throw new ConductorError('usage: conduct lock <acquire|release|status> <name> [--owner <id>] [--wait <minutes>]');
+            const waitMinutes = values.wait === undefined ? undefined : Number(values.wait);
+            if (waitMinutes !== undefined && !(waitMinutes >= 0))
+                throw new ConductorError('--wait takes minutes, such as --wait 30');
+            process.exitCode = await lockCommand(paths, sub, arg, { owner: values.owner, waitMinutes }, brokerIo());
+            return;
+        }
         case 'note':
             if (sub === undefined || arg === undefined)
                 throw new ConductorError('usage: conduct note <item> <file> [--worker <worker>]');
@@ -537,6 +564,9 @@ async function main(argv) {
             });
         case 'pause':
             return override(paths, { action: 'pause', ...(sub === undefined ? {} : { project: sub }), ...(values.until === undefined ? {} : { until: untilOf(values.until) }) });
+        case 'ports':
+            process.exitCode = await portsCommand(paths, sub, { json: values.json === true, ...(values.prefer === undefined ? {} : { prefer: wholeNumber('--prefer', values.prefer) }) }, brokerIo());
+            return;
         case 'queue':
             return queue(paths, values.json === true, values.fresh === true);
         case 'rules':
@@ -823,15 +853,22 @@ async function status(paths, json) {
     const { workers } = fleetBody.parse(await expectOk(callApi(paths, { method: 'GET', path: '/fleet' })));
     // A linked build's CLI can be newer than the daemon still running, which has no inbox (null).
     const items = await openItems(paths);
+    // Null from a daemon older than the broker.
+    const locks = await heldLocks(paths);
     const pid = readPid(paths.pid);
     const port = readEndpoint(paths)?.port ?? null;
     if (json)
-        return out(JSON.stringify({ home: paths.home, inbox: items, pid, port, projects, running: true, workers }, null, 2));
+        return out(JSON.stringify({ home: paths.home, inbox: items, locks, pid, port, projects, running: true, workers }, null, 2));
     out(`conductor running (pid ${pid ?? '?'}, port ${port ?? '?'}, home ${paths.home})`);
     out(projects.length === 0 ? 'no projects; add one with `conduct project add <path>`' : 'projects:');
     projects.forEach((p) => out(projectLine(p)));
     out(workers.length === 0 ? 'no workers' : 'workers:');
     workers.forEach((w) => out(workerLine(w)));
+    if (locks === null)
+        out('locks: not in this daemon (restart it to run this build)');
+    else
+        out(locks.length === 0 ? 'locks: none held' : 'locks:');
+    locks?.forEach((l) => out(lockLine(l)));
     if (items === null)
         out('inbox: not in this daemon (restart it to run this build)');
     else