@gaia-ai/conductor 0.7.0 → 0.8.0

package/dist/src/commands/conductor.d.ts

@@ -1,4 +1,4 @@
-import { type ConductorLogger, type GaiaCommandHost, type GaiaCommandPlugin } from '@gaia-ai/core';
+import { type ConductorLogger, type GaiaCommandHost, type GaiaCommandPlugin, type ProcProbe } from '@gaia-ai/core';
 import { Command } from 'commander';
 import type { GaiaExecutor } from '../plugins/executor.js';
 import { type ResolvedAgent } from '../plugins/plugins.js';
@@ -14,6 +14,8 @@ export interface GaiaCliDeps {
     config?: ConductorFileConfig;
     /** Injectable registry fetch for the start-time version check (tests). */
     fetch?: typeof fetch;
+    /** Marker immediately before start hands control to conductor work. */
+    onStartLoop?: () => void;
     /** Host contract (resolveBases); default: this install + cwd. */
     host?: GaiaCommandHost;
     /**
@@ -23,6 +25,11 @@ export interface GaiaCliDeps {
      * machine.
      */
     herdr?: HerdrHost;
+    /**
+     * GAIA-232: the pid probe behind `stop`. Defaults to the real /proc reader —
+     * a test MUST inject a fake, or the suite signals real processes.
+     */
+    procProbe?: ProcProbe;
 }
 /**
  * The multiplexer seam of the conductor lifecycle: start a detached foreground

package/dist/src/commands/conductor.js

@@ -1,12 +1,11 @@
 import { existsSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { createInterface } from 'node:readline';
-import { CommandRunner, createLogger, exec, getRegisteredConductor, listRegisteredConductors, loadGaiaConfig, machineContextPath, readMachineContext, registerConductor, removeConductor, resolveConfigPath, setDefaultCommandRunner, } from '@gaia-ai/core';
+import { CommandRunner, createLogger, deriveConductorLiveness, exec, fetchUpdateNotice, loadGaiaConfig, machineContextPath, printVersionLine, readMachineContext, resolveConfigPath, setDefaultCommandRunner, signalVerifiedProcess, } from '@gaia-ai/core';
 import { Command } from 'commander';
 import { authStatus } from 'dropsh';
 import { scaffold } from '../cli/init.js';
 import { runUpgrade } from '../cli/upgrade.js';
-import { fetchUpdateNotice, printVersionLine } from '../cli/version-check.js';
 import { composeConductorConfig, loadConductorConfig } from '../config.js';
 import { Conductor } from '../core/conductor.js';
 import { selectAgents, selectExecutor, selectRemote, selectWorkspace, } from '../plugins/plugins.js';
@@ -106,26 +105,18 @@ export const realHerdrHost = {
 function herdrHostOf(deps) {
     return deps.herdr ?? realHerdrHost;
 }
-// --- ls/status freshness ----------------------------------------------------
-const DEFAULT_FRESH_S = 120;
-function freshnessThresholdS(config) {
-    return config
-        ? Math.max(DEFAULT_FRESH_S, config.lease_seconds * 2)
-        : DEFAULT_FRESH_S;
-}
-function classify(hub, freshS) {
-    if (!hub) {
-        return 'registry-only';
-    }
-    if (hub.status === 'offline') {
-        return 'stopped';
-    }
-    const nowS = Math.floor(Date.now() / 1000);
-    const fresh = hub.lastSeen > 0 && nowS - hub.lastSeen <= freshS;
-    return fresh ? 'running' : 'wedged';
+/**
+ * The liveness words this CLI prints.
+ *
+ * Delegated to core so `gaia conductor ls`, the cockpit and the server-side
+ * deriver describe one conductor identically. The previous CLI-only vocabulary
+ * (`wedged`, `stopped`, `host-missing`, `registry-only`) went with the registry
+ * that made those distinctions expressible.
+ */
+function classify(hub) {
+    return deriveConductorLiveness(hub, Math.floor(Date.now() / 1000));
 }
-async function buildLsRows(remote, config, onlyId) {
-    const entries = await listRegisteredConductors();
+async function buildLsRows(remote, _config, onlyId) {
     let hub = [];
     try {
         hub = await remote.listConductors('me');
@@ -133,39 +124,23 @@ async function buildLsRows(remote, config, onlyId) {
     catch {
         hub = [];
     }
-    const hubById = new Map(hub.map((c) => [c.id, c]));
-    const freshS = freshnessThresholdS(config);
-    const ids = new Set();
-    for (const e of entries) {
-        ids.add(e.id);
-    }
-    for (const c of hub) {
-        ids.add(c.id);
-    }
-    const rows = [];
-    for (const id of ids) {
-        if (onlyId && id !== onlyId) {
-            continue;
-        }
-        const entry = entries.find((e) => e.id === id);
-        const h = hubById.get(id);
-        rows.push({
-            id,
-            project: entry?.project ?? h?.project ?? '',
-            label: entry?.label ?? h?.label ?? '',
-            host: entry?.host ?? '-',
-            status: classify(h, freshS),
-        });
-    }
-    return rows;
+    return hub
+        .filter((c) => !onlyId || c.id === onlyId)
+        .map((c) => ({
+        id: c.id,
+        project: c.project,
+        label: c.label,
+        workspaceRoot: c.workspaceRoot,
+        status: classify(c),
+    }));
 }
 function printRows(rows) {
     if (rows.length === 0) {
-        console.log('no conductors registered');
+        console.log('no conductors on the control plane');
         return;
     }
     for (const r of rows) {
-        console.log(`${r.id}\t${r.status}\t${r.host}\t${r.project}\t${r.label}`);
+        console.log(`${r.id}\t${r.status}\t${r.project}\t${r.label}\t${r.workspaceRoot}`);
     }
 }
 // --- command handlers -------------------------------------------------------
@@ -222,6 +197,10 @@ async function cmdStartForeground(deps, log = {}) {
     const workspace = deps.workspace ?? (await selectWorkspace(config, logger));
     const agents = deps.agents ?? (await selectAgents(config));
     const conductor = new Conductor(config, remote, executor, workspace, agents, logger, checkoutRoot);
+    // This process IS the conductor, so it may report its own pid and config
+    // name — the two values a cockpit needs to stop it later. poll/reap build a
+    // Conductor too but never claim, so they cannot overwrite this pid.
+    conductor.claimServeProcess();
     await conductor.start();
     const controller = new AbortController();
     const onSignal = () => controller.abort();
@@ -233,19 +212,36 @@ async function cmdStartForeground(deps, log = {}) {
     finally {
         process.removeListener('SIGINT', onSignal);
         process.removeListener('SIGTERM', onSignal);
+        // The exiting process writes its own `offline`. It has to be this process:
+        // a heartbeat sets `online` unconditionally (ConductorRegistrar), so an
+        // offline written by anyone else is erased by the next tick — the status
+        // is only trustworthy when written after the heartbeats have stopped.
+        // Best-effort: a conductor that cannot reach the control plane on the way
+        // out must still exit, and the reaper flips it on lease expiry anyway.
+        try {
+            await remote.setConductorStatus(conductor.id, 'offline');
+        }
+        catch (err) {
+            logger.warn({ conductorId: conductor.id, err: String(err) }, 'could not write offline status on shutdown; the lease reaper will');
+        }
     }
 }
-async function cmdStart(deps, log = {}) {
+async function cmdStart(deps, log = {}, updateCheck = true, body = cmdStartBody) {
     const current = printVersionLine();
-    const noticePromise = fetchUpdateNotice(current, deps.fetch ?? globalThis.fetch).catch(() => null);
-    try {
-        await cmdStartBody(deps, log);
-    }
-    finally {
-        const notice = await noticePromise;
+    if (updateCheck) {
+        const notice = await fetchUpdateNotice(current, {
+            fetchImpl: deps.fetch ?? globalThis.fetch,
+            ...(deps.fetch
+                ? {
+                    cachePath: `/tmp/gaia-update-check-${process.pid}-${Math.random()}.json`,
+                }
+                : {}),
+        });
         if (notice !== null)
             console.log(notice);
     }
+    deps.onStartLoop?.();
+    await body(deps, log);
 }
 async function cmdStartBody(deps, log) {
     const config = await resolveConfig(deps);
@@ -255,30 +251,25 @@ async function cmdStartBody(deps, log) {
         return;
     const remote = await resolveRemote(deps, config);
     const id = conductorIdOf(config);
-    const existing = await getRegisteredConductor(id);
-    if (existing) {
-        const hubStatus = await remote.getConductorStatus(id);
-        if (hubStatus !== null && hubStatus !== 'offline') {
-            console.log(`conductor already running for ${config.project}`);
-            return;
-        }
+    // Block on the DERIVED status, not the raw one. A crashed conductor keeps
+    // `status: online` on its record until the cron reaper notices the lapsed
+    // lease, and those are precisely the minutes in which someone wants to
+    // restart it. Only a conductor that is actually alive refuses a second start.
+    const existing = (await remote.listConductors('me')).find((c) => c.id === id);
+    if (existing && classify(existing) === 'running') {
+        console.log(`conductor already running for ${config.project}`);
+        return;
     }
+    // The conductor registers itself with the control plane on start(); there is
+    // no local file to write, and nothing left that a second list could add.
     const handle = `gaia-conductor:${id}`;
-    await registerConductor({
-        id,
-        path: checkoutRoot,
-        project: config.project,
-        label: config.label,
-        host: 'herdr',
-        handle,
-    });
     const fgFlags = [
         log.level ? `--log-level ${log.level}` : '',
         log.sink ? `--log-sink ${log.sink}` : '',
     ]
         .filter(Boolean)
         .join(' ');
-    const fgCmd = `GAIA_CONDUCTOR_LOG=file gaia conductor ${fgFlags} start --foreground`.replace(/\s+/g, ' ');
+    const fgCmd = `GAIA_CONDUCTOR_LOG=file gaia conductor ${fgFlags} start --foreground --no-update-check`.replace(/\s+/g, ' ');
     try {
         await herdrHostOf(deps).spawn(handle, checkoutRoot, fgCmd);
         logger.info({ id, handle }, 'started conductor via herdr');
@@ -288,27 +279,45 @@ async function cmdStartBody(deps, log) {
         logger.warn({}, 'Hint: run `gaia conductor start --foreground` under a service manager (systemd-user / docker) on hosts without herdr.');
     }
 }
+/**
+ * Stops this checkout's conductor with a verified signal.
+ *
+ * Two things this deliberately no longer does. It does not kill a herdr tab:
+ * that killed the pane the conductor happened to be shown in, which is neither
+ * necessary (a signal reaches the process wherever it lives) nor sufficient (a
+ * conductor started by systemd or a bare --foreground has no tab). And it does
+ * not write `offline` — a heartbeat sets `online` unconditionally, so a status
+ * written from here is erased by the next tick unless it happens to land after
+ * the process died. The exiting process writes its own, which is correct by
+ * construction rather than by ordering luck.
+ *
+ * `--now` differs only in the signal. It runs through the same verification
+ * gate, because a hard kill aimed at a recycled pid is the most damaging
+ * version of the same mistake.
+ */
 async function cmdStop(deps, now) {
     const config = await resolveConfig(deps);
     const remote = await resolveRemote(deps, config);
     const id = conductorIdOf(config);
-    if (now) {
-        const entry = await getRegisteredConductor(id);
-        if (entry && entry.host === 'herdr') {
-            await herdrHostOf(deps).kill(entry.handle);
-            console.log(`hard-stopped conductor ${id} (${entry.handle})`);
-        }
-        else {
-            console.log(`no herdr-hosted conductor to hard-stop for ${id}`);
-        }
+    const row = (await remote.listConductors('me')).find((c) => c.id === id);
+    if (!row) {
+        console.log(`no conductor ${id} on the control plane — nothing to stop (it may never have started)`);
         return;
     }
-    const entry = await getRegisteredConductor(id);
-    if (entry && entry.host === 'herdr') {
-        await herdrHostOf(deps).kill(entry.handle);
+    const signal = now ? 'SIGKILL' : 'SIGTERM';
+    const outcome = signalVerifiedProcess({
+        pid: row.lastPid,
+        workspaceRoot: row.workspaceRoot,
+        signal,
+        ...(deps.procProbe ? { probe: deps.procProbe } : {}),
+    });
+    if (!outcome.ok) {
+        console.log(`could not stop conductor ${id}: ${outcome.message}`);
+        return;
     }
-    await remote.setConductorStatus(id, 'offline');
-    console.log(`stopped conductor ${id} (offline)`);
+    console.log(now
+        ? `hard-stopped conductor ${id} (SIGKILL to pid ${outcome.pid}); a killed process writes no offline, so the status follows on lease expiry`
+        : `stopped conductor ${id} (SIGTERM to pid ${outcome.pid}); it writes its own offline as it exits`);
 }
 async function cmdLs(deps) {
     const config = deps.config ?? (await tryConfig(deps));
@@ -323,12 +332,6 @@ async function cmdStatus(deps) {
     const rows = await buildLsRows(remote, config, id);
     printRows(rows);
 }
-async function cmdRm(deps) {
-    const config = await resolveConfig(deps);
-    const id = conductorIdOf(config);
-    await removeConductor(id);
-    console.log(`removed conductor ${id} from registry`);
-}
 /** ls may run without a config file; best-effort load. */
 async function tryConfig(deps) {
     if (deps.config) {
@@ -402,12 +405,13 @@ Examples:
         .command('start')
         .description('start the conductor loop (herdr-hosted by default)')
         .option('--foreground', 'run the loop in this process', false)
+        .option('--no-update-check', 'skip the daily CLI update check')
         .action(async function (opts) {
         if (opts.foreground) {
-            await cmdStartForeground(deps, logOptsOf(this));
+            await cmdStart(deps, logOptsOf(this), opts.updateCheck, cmdStartForeground);
         }
         else {
-            await cmdStart(deps, logOptsOf(this));
+            await cmdStart(deps, logOptsOf(this), opts.updateCheck);
         }
     });
     conductor
@@ -441,12 +445,10 @@ Examples:
         .action(async () => {
         await cmdStatus(deps);
     });
-    conductor
-        .command('rm')
-        .description('deregister the conductor for this checkout')
-        .action(async () => {
-        await cmdRm(deps);
-    });
+    // `gaia conductor rm` is gone (GAIA-232). Its only job was deleting the local
+    // registry entry; with no registry there is nothing to remove, and deleting
+    // the control-plane record is explicitly not the model — a conductor that
+    // stops is offline, not absent.
     registerInit(conductor);
     return conductor;
 }

package/dist/src/contract.d.ts

@@ -1,5 +1,5 @@
 export { type AgentFootprint, emptyAgentFootprint, type GaiaAgent, } from './plugins/agent.js';
-export type { ExecutorCapabilities, GaiaExecutor, HookContext, HookName, HookResult, SpawnedSession, SpawnRunInput, } from './plugins/executor.js';
+export type { ExecutorCapabilities, GaiaExecutor, HookContext, HookName, HookResult, SpawnedSession, SpawnRunInput, WorktreeTeardown, } from './plugins/executor.js';
 export type { AgentCandidate, AgentPlugin, ExecutorDeps, ExecutorPlugin, RemotePlugin, ResolvedAgent, WorkspacePlugin, } from './plugins/plugins.js';
 export { selectAgent, selectAgents, selectExecutor, selectRemote, selectWorkspace, } from './plugins/plugins.js';
 export { type ConductorAddonEntry, type ConductorContributions, narrowConductorContributions, type Preset, } from './plugins/preset.js';

package/dist/src/core/conductor.d.ts

@@ -25,8 +25,35 @@ export declare class Conductor {
     private uuid;
     constructor(config: ConductorFileConfig, remote: GaiaRemote, executor: GaiaExecutor, workspace: GaiaWorkspace, agents: ResolvedAgent[], logger: ConductorLogger, checkoutRoot?: string);
     get id(): string;
+    /**
+     * Whether this instance is the serve-loop process itself (GAIA-232).
+     *
+     * Off by default so that only a caller which genuinely owns the process can
+     * report a pid — see {@link claimServeProcess}.
+     */
+    private ownsServeProcess;
+    /**
+     * Declares that this instance runs *as* the conductor process, so its
+     * registrations may carry the process identity a cockpit needs to stop it.
+     *
+     * Only `cmdStartForeground` calls this. `cmdPoll` and `cmdReap` also build a
+     * Conductor and call start() + tick(), then exit; if they reported a pid,
+     * every `gaia conductor poll` would overwrite the running conductor's pid
+     * with its own short-lived one and the next stop would signal a dead — or
+     * recycled — process. Making the report opt-in means those two commands
+     * cannot do so even by accident.
+     */
+    claimServeProcess(): void;
     /** This conductor's registration payload, built from config. */
     private registration;
+    /**
+     * The stem of the config file this conductor was loaded from.
+     *
+     * Derived through core's own mapping rather than by slicing the filename
+     * here, so the CLI and the conductor cannot disagree about which files count
+     * as a conductor config.
+     */
+    private get conductorName();
     start(): Promise<void>;
     tick(): Promise<void>;
     /**
@@ -52,14 +79,21 @@ export declare class Conductor {
      *
      * Per ticket, close is DECOUPLED from teardown (no withholding): a done ticket
      * is closed at once as a lifecycle step, independent of whether its worktree
-     * teardown then succeeds. `cleaned_up` is flagged ONLY on a VERIFIED teardown
-     * (GAIA-141 RC-2): `removeWorktree` returns `true` when the worktree is gone on
-     * this host (removed by us, or confirmed already absent), `false` when it could
-     * not be resolved and may still be on disk (e.g. its `worktree_path` was never
-     * persisted). A `false` return — like a THROW — logs loudly and leaves
-     * `cleaned_up=0`, so the next reconciliation retries; flagging cleaned on an
-     * unverified teardown was the root cause of the ~28 never-touched leftovers,
-     * because the ticket then dropped off the (cleaned_up=0) work list forever.
+     * teardown then succeeds. `cleaned_up` is withheld unless the teardown is
+     * ACCOUNTED FOR (GAIA-141 RC-2), which `removeWorktree` reports as one of
+     * three outcomes (GAIA-293):
+     *   - `removed` — gone because this host tore it down → flag cleaned;
+     *   - `already_absent` — nothing was there to tear down. A FINISHED teardown,
+     *     not a failure: it is recorded in this log AND on the run record, then
+     *     flagged cleaned. Recording it is the point — swallowing the absence and
+     *     leaving `cleaned_up=0` is what made every later reap repeat the same
+     *     failing teardown;
+     *   - `unverified` — it could not be resolved and may still be on disk (e.g.
+     *     its `worktree_path` was never persisted). Like a THROW, it logs loudly
+     *     and leaves `cleaned_up=0` so the next reconciliation retries.
+     * Flagging cleaned on an unverified teardown was the root cause of the ~28
+     * never-touched leftovers, because the ticket then dropped off the
+     * (cleaned_up=0) work list forever.
      * Re-running on an already-cleaned ticket is a no-op — it is off the list
      * (idempotent). Each ticket is isolated in a try/catch so one failure never
      * aborts the rest.

package/dist/src/core/conductor.js

@@ -1,5 +1,6 @@
 import { existsSync } from 'node:fs';
-import { conductorId } from '@gaia-ai/core';
+import { basename } from 'node:path';
+import { conductorId, stemForConfigFile, } from '@gaia-ai/core';
 import { selectAgent } from '../plugins/plugins.js';
 function sleep(ms, signal) {
     return new Promise((resolve) => {
@@ -104,9 +105,30 @@ export class Conductor {
     get id() {
         return this.config.machine_id ?? conductorId(this.checkoutRoot);
     }
+    /**
+     * Whether this instance is the serve-loop process itself (GAIA-232).
+     *
+     * Off by default so that only a caller which genuinely owns the process can
+     * report a pid — see {@link claimServeProcess}.
+     */
+    ownsServeProcess = false;
+    /**
+     * Declares that this instance runs *as* the conductor process, so its
+     * registrations may carry the process identity a cockpit needs to stop it.
+     *
+     * Only `cmdStartForeground` calls this. `cmdPoll` and `cmdReap` also build a
+     * Conductor and call start() + tick(), then exit; if they reported a pid,
+     * every `gaia conductor poll` would overwrite the running conductor's pid
+     * with its own short-lived one and the next stop would signal a dead — or
+     * recycled — process. Making the report opt-in means those two commands
+     * cannot do so even by accident.
+     */
+    claimServeProcess() {
+        this.ownsServeProcess = true;
+    }
     /** This conductor's registration payload, built from config. */
     registration() {
-        return {
+        const base = {
             id: this.id,
             project: this.config.project,
             states: this.config.states,
@@ -114,6 +136,24 @@ export class Conductor {
             label: this.config.label,
             max_parallel: this.config.max_parallel,
         };
+        if (!this.ownsServeProcess)
+            return base;
+        return {
+            ...base,
+            last_pid: process.pid,
+            ...(this.conductorName ? { conductor_name: this.conductorName } : {}),
+        };
+    }
+    /**
+     * The stem of the config file this conductor was loaded from.
+     *
+     * Derived through core's own mapping rather than by slicing the filename
+     * here, so the CLI and the conductor cannot disagree about which files count
+     * as a conductor config.
+     */
+    get conductorName() {
+        const path = this.config.config_path;
+        return path ? stemForConfigFile(basename(path)) : undefined;
     }
     async start() {
         this.uuid = await this.remote.registerConductor(this.registration());
@@ -268,14 +308,21 @@ export class Conductor {
      *
      * Per ticket, close is DECOUPLED from teardown (no withholding): a done ticket
      * is closed at once as a lifecycle step, independent of whether its worktree
-     * teardown then succeeds. `cleaned_up` is flagged ONLY on a VERIFIED teardown
-     * (GAIA-141 RC-2): `removeWorktree` returns `true` when the worktree is gone on
-     * this host (removed by us, or confirmed already absent), `false` when it could
-     * not be resolved and may still be on disk (e.g. its `worktree_path` was never
-     * persisted). A `false` return — like a THROW — logs loudly and leaves
-     * `cleaned_up=0`, so the next reconciliation retries; flagging cleaned on an
-     * unverified teardown was the root cause of the ~28 never-touched leftovers,
-     * because the ticket then dropped off the (cleaned_up=0) work list forever.
+     * teardown then succeeds. `cleaned_up` is withheld unless the teardown is
+     * ACCOUNTED FOR (GAIA-141 RC-2), which `removeWorktree` reports as one of
+     * three outcomes (GAIA-293):
+     *   - `removed` — gone because this host tore it down → flag cleaned;
+     *   - `already_absent` — nothing was there to tear down. A FINISHED teardown,
+     *     not a failure: it is recorded in this log AND on the run record, then
+     *     flagged cleaned. Recording it is the point — swallowing the absence and
+     *     leaving `cleaned_up=0` is what made every later reap repeat the same
+     *     failing teardown;
+     *   - `unverified` — it could not be resolved and may still be on disk (e.g.
+     *     its `worktree_path` was never persisted). Like a THROW, it logs loudly
+     *     and leaves `cleaned_up=0` so the next reconciliation retries.
+     * Flagging cleaned on an unverified teardown was the root cause of the ~28
+     * never-touched leftovers, because the ticket then dropped off the
+     * (cleaned_up=0) work list forever.
      * Re-running on an already-cleaned ticket is a no-op — it is off the list
      * (idempotent). Each ticket is isolated in a try/catch so one failure never
      * aborts the rest.
@@ -303,20 +350,56 @@ export class Conductor {
                 // not by the mutable checked-out branch (the coding agent may rename
                 // it). Teardown is idempotent: a worktree herdr no longer tracks is a
                 // no-op / on-disk reclaim, not a failure.
+                //
+                // The hook needs the DIRECTORY, not just a recorded path (GAIA-293): a
+                // hook is a shell spawned with the worktree as its `cwd`, so against an
+                // absent one the spawn fails with ENOENT and the shared exec helper logs
+                // `ERROR: exec failed` — for the very condition this ticket declares
+                // normal. There is no useful work such a hook could do either: a command
+                // that must run inside the worktree cannot run anywhere else.
+                //
+                // The absence is logged rather than passed over in silence, because an
+                // `after_done` can reach beyond the directory it runs in — `ddev delete
+                // -Oy` also drops a DDEV project registration and its database — and
+                // that leftover is then an operator's to clear by hand.
+                //
+                // But the line states the CONDITION, not a decision about a hook: hook
+                // commands are executor-owned config that the core cannot see, so it
+                // does not know whether an `after_done` is configured at all. Saying a
+                // hook was "skipped" would be false wherever none exists (the generated
+                // playground config is exactly such a case). What the core does know is
+                // that the directory is gone and that no `after_done` ran — both true in
+                // either configuration.
+                //
+                // `existsSync` here is a plain filesystem question, not worktree
+                // knowledge: the core stays executor-agnostic and asks nothing about
+                // git. The check is deliberately reap-local — at dispatch a worktree the
+                // workspace just created MUST exist, and silencing a hook there would
+                // hide a real provisioning failure.
                 if (t.worktreePath) {
-                    await this.executor.runHook('after_done', t.worktreePath, {
-                        ticket: t.ticketUuid,
-                    });
+                    if (existsSync(t.worktreePath)) {
+                        await this.executor.runHook('after_done', t.worktreePath, {
+                            ticket: t.ticketUuid,
+                        });
+                    }
+                    else {
+                        this.logger.info({
+                            ticket: t.ticketUuid,
+                            hook: 'after_done',
+                            worktreePath: t.worktreePath,
+                        }, 'worktree directory absent — after_done not run');
+                    }
                 }
                 if (this.executor.capabilities().persistent) {
-                    let removed;
+                    let outcome;
                     try {
-                        // removeWorktree returns whether the teardown was VERIFIED on this
-                        // host: `true` = the worktree is gone (removed by us, or confirmed
-                        // already absent); `false` = it could NOT be resolved and may still
-                        // be on disk (GAIA-141 RC-2 — e.g. worktree_path was never persisted
-                        // and herdr lost track of the branch). A THROW is a hard failure.
-                        removed = await this.executor.removeWorktree(t.branchName, t.worktreePath || undefined);
+                        // removeWorktree reports what the teardown DID (GAIA-293):
+                        // `removed` = the worktree is gone because this host removed it;
+                        // `already_absent` = there was nothing to tear down; `unverified` =
+                        // it could NOT be resolved and may still be on disk (GAIA-141 RC-2
+                        // — e.g. worktree_path was never persisted and herdr lost track of
+                        // the branch). A THROW is a hard failure.
+                        outcome = await this.executor.removeWorktree(t.branchName, t.worktreePath || undefined);
                     }
                     catch (err) {
                         this.logger.warn({
@@ -327,7 +410,7 @@ export class Conductor {
                         }, 'worktree teardown failed');
                         continue; // leave cleaned_up=0 → the next reconciliation retries.
                     }
-                    if (!removed) {
+                    if (outcome === 'unverified') {
                         // Unverified teardown (GAIA-141 RC-2): do NOT flag cleaned_up, or the
                         // ticket drops off fetchUncleanedTickets (which filters cleaned_up=0)
                         // and the orphan is never retried. Leave it on the work list so a
@@ -340,9 +423,33 @@ export class Conductor {
                         }, 'worktree teardown unverified — retrying next reap');
                         continue; // leave cleaned_up=0 → the next reconciliation retries.
                     }
+                    if (outcome === 'already_absent') {
+                        // GAIA-293: the worktree was gone before we got here. That is a
+                        // FINISHED teardown, so it is recorded rather than swallowed and
+                        // the ticket is flagged cleaned below — the next reap will not
+                        // retry it.
+                        this.logger.info({
+                            ticket: t.ticketUuid,
+                            branch: t.branchName,
+                            worktreePath: t.worktreePath,
+                        }, 'worktree already absent — teardown complete');
+                        // A ticket with no run has no record to write to — the conductor
+                        // log above is then the whole account.
+                        if (t.runUuid) {
+                            try {
+                                await this.remote.appendRunNote(t.runUuid, `worktree already absent at teardown: ${t.worktreePath || '(path unknown)'}`);
+                            }
+                            catch (err) {
+                                // Best-effort: an unreachable control plane must not keep a
+                                // finished teardown from being flagged.
+                                this.logger.warn({ ticket: t.ticketUuid, run: t.runUuid, err: String(err) }, 'run note write failed');
+                            }
+                        }
+                    }
                 }
-                // Teardown verified locally (or nothing hosted to tear down): flag it
-                // cleaned so it drops off the work list.
+                // Teardown verified locally, the worktree was already absent, or there
+                // is nothing hosted to tear down: flag it cleaned so it drops off the
+                // work list.
                 await this.remote.markTicketCleanedUp(t.ticketUuid);
                 this.logger.info({ ticket: t.ticketUuid }, 'ticket cleaned up');
             }

package/dist/src/index.d.ts

@@ -1,5 +1,4 @@
 export type * from '@gaia-ai/core';
-export type { ConductorRegistryEntry } from '@gaia-ai/core';
 export { conductorId } from '@gaia-ai/core';
 export { GAIA_CONFIG_SCHEMA_VERSION, readConfigSchemaVersion, } from './cli/config-schema.js';
 export { renderGaiaConfig } from './cli/init.js';

package/dist/src/index.js

@@ -1,3 +1,5 @@
+// GAIA-224: the conductor registry lives ONLY in `@gaia-ai/core` — the former
+// thin re-export shim under `./cli/` is deleted and importers name core direct.
 export { conductorId } from '@gaia-ai/core';
 // GAIA-216: the connection-config schema version + its regex reader. GAIA-230:
 // the host's `gaia upgrade` intro prints the `from → to` pair from these.

package/dist/src/plugins/executor.d.ts

@@ -52,6 +52,23 @@ export interface HookResult {
     /** The stringified failure; present iff `ok` is false. */
     error?: string;
 }
+/**
+ * Outcome of a worktree teardown (GAIA-293).
+ *
+ * - `removed`        — the worktree was torn down on this host, or the prunable
+ *                      admin entry it left behind was swept.
+ * - `already_absent` — nothing to tear down: neither git nor the filesystem
+ *                      still has it. A FINISHED teardown, not a failure.
+ * - `unverified`     — it could not be resolved or removed and may still be on
+ *                      disk; the reaper leaves the ticket on its work list.
+ *
+ * Replaces the former `boolean`, which could not distinguish "gone because we
+ * removed it" from "gone before we got here" — the distinction the reaper needs
+ * in order to record the absence rather than swallow it. The mapping preserves
+ * the old semantics exactly: `removed` is the old `true`, `unverified` the old
+ * `false`.
+ */
+export type WorktreeTeardown = 'removed' | 'already_absent' | 'unverified';
 export interface GaiaExecutor {
     id: string;
     capabilities(): ExecutorCapabilities;
@@ -112,14 +129,15 @@ export interface GaiaExecutor {
      * checked-out branch is mutable (the coding agent may rename/switch it), the
      * path is not.
      *
-     * Returns whether the worktree was actually present on THIS host and torn
-     * down (or reclaimed on disk) — i.e. whether the teardown happened locally.
-     * `false` means nothing matched here: the worktree is either already gone or
-     * lives on another conductor's host. The reaper uses this to avoid marking a
-     * ticket `cleaned_up` for a worktree it did not actually tear down (a
-     * cross-host false-teardown), leaving it for the host that physically holds
-     * it. A genuine failure still throws (surfaced as a teardown miss); a `false`
-     * return is a clean "not here", not an error.
+     * Reports what the teardown DID as a {@link WorktreeTeardown} (GAIA-293):
+     * `removed` when the worktree was present on this host and torn down (or its
+     * prunable admin entry swept), `already_absent` when there was nothing to
+     * tear down at all, and `unverified` when nothing matched here and the
+     * worktree may still be on disk (another conductor's host, or a path that
+     * could not be resolved). The reaper flags a ticket `cleaned_up` for the
+     * first two and leaves it on the work list for `unverified`, so it never
+     * false-teardowns a worktree another host physically holds. A genuine
+     * failure still throws (surfaced as a teardown miss).
      */
-    removeWorktree(branch: string, worktreePath?: string): Promise<boolean>;
+    removeWorktree(branch: string, worktreePath?: string): Promise<WorktreeTeardown>;
 }

package/dist/src/plugins/remote.d.ts

@@ -6,6 +6,22 @@ export interface ConductorRegistration {
     workspace: string;
     label: string;
     max_parallel: number;
+    /**
+     * The pid of the serve-loop process, when this conductor *is* that process.
+     *
+     * Absent from a registration sent by `poll` or `reap`, which build a
+     * Conductor and exit within seconds — reporting their pid would overwrite a
+     * running conductor's with a short-lived one. Absent likewise means "leave
+     * whatever is stored alone", never "clear it".
+     */
+    last_pid?: number;
+    /**
+     * The stem of the config file this conductor was started from (`conductor`
+     * for the default, `shop` for `shop.conductor.config.js`) — what
+     * `--conductor <name>` selects. Together with `workspace` it identifies one
+     * conductor in a repo that holds several.
+     */
+    conductor_name?: string;
 }
 export interface ClaimOptions {
     leaseSeconds: number;
@@ -60,6 +76,18 @@ export interface ConductorStatus {
     status: string;
     lastSeen: number;
     load: number;
+    /**
+     * The `.gaia` dir the conductor last registered from — where its config and
+     * `log.txt` live, and the cwd a start must use. Empty when never reported.
+     */
+    workspaceRoot: string;
+    /** Lease expiry (unix seconds); with lastSeen it derives liveness. 0 = unset. */
+    leaseExpiresAt: number;
+    maxParallel: number;
+    /** The last pid the conductor's serve loop reported, if any (GAIA-232). */
+    lastPid?: number;
+    /** The config stem it was started from, as `--conductor <name>` takes it. */
+    conductorName?: string;
 }
 export interface FinalizableRun {
     runUuid: string;
@@ -105,6 +133,13 @@ export interface UncleanTicket {
     state: string;
     /** Whether the ticket's lifecycle has already been closed out. */
     closed: boolean;
+    /**
+     * UUID of the ticket's latest run — the one {@link worktreePath} came from —
+     * or '' when the ticket has no run with a path. The record teardown notes are
+     * written to (GAIA-293). Resolved by the same query that resolves the path,
+     * so it costs no extra round-trip.
+     */
+    runUuid: string;
 }
 /** Extra conductor-writable gaia_run attributes (besides state/lease). */
 export interface RunWriteAttributes {
@@ -191,6 +226,14 @@ export interface GaiaRemote {
      * already-cleaned ticket is a no-op (it is no longer on the list).
      */
     markTicketCleanedUp(uuid: string): Promise<void>;
+    /**
+     * Append one diagnostic line to a run's log (GAIA-293) — how the reaper
+     * records what it found on the run record itself, not only in this machine's
+     * process log. Touches `log` alone: the run is already closed, and its
+     * lifecycle fields are not this call's business. An empty `runUuid` writes
+     * nothing.
+     */
+    appendRunNote(runUuid: string, note: string): Promise<void>;
     /**
      * Resolve a ticket identifier (e.g. "GAIA-134") to its uuid+title within a
      * project, or null when no such ticket exists. Used by the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaia-ai/conductor",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "GAIA conductor engine + CLI: registers, claims tickets via JSON:API, dispatches agents.",
   "type": "module",
   "license": "MIT",
@@ -28,11 +28,10 @@
     "directory": "gaia-cli/conductor"
   },
   "dependencies": {
-    "@gaia-ai/core": "^0.7.0",
+    "@gaia-ai/core": "^0.8.0",
     "@dropsh/plugin-oauth2": "^0.5.7",
     "@dropsh/plugin-jsonapi-schema": "^0.5.8",
     "commander": "^12.1.0",
-    "dropsh": "^0.5.8",
-    "semver": "^7.6.0"
+    "dropsh": "^0.5.8"
   }
 }