@gaia-ai/conductor 0.11.1 → 0.11.2

package/dist/src/cli/version-check.d.ts

@@ -0,0 +1,72 @@
+/** The global install target on npm (the meta package). */
+export declare const GAIA_PACKAGE = "@gaia-ai/gaia";
+/** The npm registry endpoint for the latest published version. */
+export declare const REGISTRY_LATEST_URL = "https://registry.npmjs.org/@gaia-ai/gaia/latest";
+/**
+ * The sentinel returned when the installed version cannot be resolved (the
+ * package.json walk failed). Never a real published release, so callers treat
+ * it as "unknown" and suppress the update notice rather than nagging.
+ */
+export declare const UNKNOWN_VERSION = "0.0.0";
+/**
+ * The currently installed CLI version. Walks up from this module to the nearest
+ * @gaia-ai/conductor package.json so it resolves both from the compiled
+ * dist/src/cli/version-check.js and from a vitest src run. Same release tag
+ * across packages ⇒ == @gaia-ai/gaia. Memoized — the version cannot change
+ * within a process, so the walk runs at most once (finding #6).
+ */
+export declare function resolveCliVersion(): string;
+/**
+ * Fetch the latest published version of @gaia-ai/gaia from the npm registry.
+ * Bounded by an AbortController timeout; NEVER throws — any failure (network,
+ * non-2xx, timeout, malformed JSON, missing field) resolves to null so the
+ * caller can treat the check as best-effort (AC-4). fetchImpl is injectable so
+ * tests run without network.
+ */
+export declare function fetchLatestVersion(fetchImpl?: typeof fetch, timeoutMs?: number): Promise<string | null>;
+/**
+ * A human-readable "update available" notice when `latest` is strictly newer
+ * than `current`, else null (already current or ahead — AC-5). Pure.
+ */
+export declare function updateNotice(current: string, latest: string): string | null;
+/** Spawns a command, inheriting stdio, resolving to its exit code. */
+export type SpawnUpdate = (cmd: string, args: string[]) => Promise<number>;
+/** Spawns a command, capturing stdout, resolving to its exit code + stdout. */
+export type SpawnCapture = (cmd: string, args: string[]) => Promise<{
+    code: number;
+    stdout: string;
+}>;
+/**
+ * Upgrade the globally installed gaia CLI to the latest published version via
+ * `npm install -g @gaia-ai/gaia@latest`. Reports the actual global version
+ * before and after the install (queried from npm, not from a separate registry
+ * fetch — finding #2), so the caller reports the real change: `before` is null
+ * when gaia was not installed globally, and no "upgraded" claim is made unless
+ * npm actually changed the on-disk version. On install failure `after` mirrors
+ * `before` and the post-install query is skipped. spawnImpl/captureImpl are
+ * injectable for tests.
+ */
+export declare function runUpdate(spawnImpl?: SpawnUpdate, captureImpl?: SpawnCapture): Promise<{
+    ok: boolean;
+    before: string | null;
+    after: string | null;
+}>;
+/**
+ * Print the installed gaia version line (AC-2), synchronously, and return it.
+ * Never blocks on the registry — the caller kicks off the newer-version check
+ * separately (see fetchUpdateNotice) so start is not stalled waiting on npm.
+ */
+export declare function printVersionLine(out?: (s: string) => void): string;
+/**
+ * Best-effort "update available" notice for the given installed version
+ * (AC-3/AC-5). Fetches the latest published version (fail-silent → null on any
+ * error, AC-4) and compares. Returns the notice string or null. fetchImpl is
+ * injectable for tests.
+ */
+export declare function fetchUpdateNotice(current: string, fetchImpl?: typeof fetch): Promise<string | null>;
+/**
+ * Print the installed gaia version (AC-2) and, best-effort, a newer-version
+ * notice (AC-3/AC-5). The registry check is fail-silent (AC-4): an offline
+ * registry prints only the version line. out/fetchImpl are injectable for tests.
+ */
+export declare function printStartVersionBanner(out?: (s: string) => void, fetchImpl?: typeof fetch): Promise<void>;

package/dist/src/cli/version-check.js

@@ -0,0 +1,186 @@
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import semver from 'semver';
+/** The global install target on npm (the meta package). */
+export const GAIA_PACKAGE = '@gaia-ai/gaia';
+/** The npm registry endpoint for the latest published version. */
+export const REGISTRY_LATEST_URL = 'https://registry.npmjs.org/@gaia-ai/gaia/latest';
+/**
+ * The sentinel returned when the installed version cannot be resolved (the
+ * package.json walk failed). Never a real published release, so callers treat
+ * it as "unknown" and suppress the update notice rather than nagging.
+ */
+export const UNKNOWN_VERSION = '0.0.0';
+let cachedCliVersion;
+/**
+ * The currently installed CLI version. Walks up from this module to the nearest
+ * @gaia-ai/conductor package.json so it resolves both from the compiled
+ * dist/src/cli/version-check.js and from a vitest src run. Same release tag
+ * across packages ⇒ == @gaia-ai/gaia. Memoized — the version cannot change
+ * within a process, so the walk runs at most once (finding #6).
+ */
+export function resolveCliVersion() {
+    if (cachedCliVersion !== undefined)
+        return cachedCliVersion;
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i++) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+            if (pkg.name === '@gaia-ai/conductor') {
+                cachedCliVersion = pkg.version ?? UNKNOWN_VERSION;
+                return cachedCliVersion;
+            }
+        }
+        catch {
+            // no package.json here — keep walking up
+        }
+        dir = dirname(dir);
+    }
+    cachedCliVersion = UNKNOWN_VERSION;
+    return cachedCliVersion;
+}
+/**
+ * Fetch the latest published version of @gaia-ai/gaia from the npm registry.
+ * Bounded by an AbortController timeout; NEVER throws — any failure (network,
+ * non-2xx, timeout, malformed JSON, missing field) resolves to null so the
+ * caller can treat the check as best-effort (AC-4). fetchImpl is injectable so
+ * tests run without network.
+ */
+export async function fetchLatestVersion(fetchImpl = globalThis.fetch, timeoutMs = 1500) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(REGISTRY_LATEST_URL, {
+            signal: controller.signal,
+            headers: { accept: 'application/json' },
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return typeof body.version === 'string' ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * A human-readable "update available" notice when `latest` is strictly newer
+ * than `current`, else null (already current or ahead — AC-5). Pure.
+ */
+export function updateNotice(current, latest) {
+    // Unknown installed version ⇒ suppress the notice (finding #5): otherwise a
+    // failed package.json walk yields a perpetual bogus "0.0.0 → x.y.z" nag.
+    if (current === UNKNOWN_VERSION)
+        return null;
+    if (!semver.valid(current) || !semver.valid(latest))
+        return null;
+    if (!semver.gt(latest, current))
+        return null;
+    // Two distinct steps, apt-style: first get the newer CODE, then migrate the
+    // CONFIG. There is no `gaia update` command — the CLI is a global npm package,
+    // so code is updated via npm; `gaia upgrade` then migrates the config shape.
+    return (`A new gaia version is available: ${current} → ${latest}\n` +
+        'Run `npm install -g @gaia-ai/gaia@latest` to update the CLI, ' +
+        'then `gaia upgrade` to migrate your config.');
+}
+const defaultSpawn = (cmd, args) => new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: 'inherit', shell: false });
+    child.on('error', () => resolve(1));
+    child.on('close', (code) => resolve(code ?? 1));
+});
+const defaultCapture = (cmd, args) => new Promise((resolve) => {
+    let stdout = '';
+    const child = spawn(cmd, args, {
+        stdio: ['ignore', 'pipe', 'ignore'],
+        shell: false,
+    });
+    child.stdout?.on('data', (chunk) => {
+        stdout += String(chunk);
+    });
+    child.on('error', () => resolve({ code: 1, stdout }));
+    child.on('close', (code) => resolve({ code: code ?? 1, stdout }));
+});
+/**
+ * The version of the globally installed @gaia-ai/gaia, read from
+ * `npm ls -g @gaia-ai/gaia --json`, or null when it is not installed globally /
+ * the output cannot be parsed. This reflects what npm actually has on disk —
+ * independent of the (possibly dev-shim) CLI running this process.
+ */
+async function queryGlobalVersion(captureImpl) {
+    try {
+        const { stdout } = await captureImpl('npm', [
+            'ls',
+            '-g',
+            GAIA_PACKAGE,
+            '--json',
+            '--depth',
+            '0',
+        ]);
+        const parsed = JSON.parse(stdout);
+        const v = parsed.dependencies?.[GAIA_PACKAGE]?.version;
+        return typeof v === 'string' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Upgrade the globally installed gaia CLI to the latest published version via
+ * `npm install -g @gaia-ai/gaia@latest`. Reports the actual global version
+ * before and after the install (queried from npm, not from a separate registry
+ * fetch — finding #2), so the caller reports the real change: `before` is null
+ * when gaia was not installed globally, and no "upgraded" claim is made unless
+ * npm actually changed the on-disk version. On install failure `after` mirrors
+ * `before` and the post-install query is skipped. spawnImpl/captureImpl are
+ * injectable for tests.
+ */
+export async function runUpdate(spawnImpl = defaultSpawn, captureImpl = defaultCapture) {
+    const before = await queryGlobalVersion(captureImpl);
+    const code = await spawnImpl('npm', [
+        'install',
+        '-g',
+        `${GAIA_PACKAGE}@latest`,
+    ]);
+    if (code !== 0)
+        return { ok: false, before, after: before };
+    const after = await queryGlobalVersion(captureImpl);
+    return { ok: true, before, after };
+}
+/**
+ * Print the installed gaia version line (AC-2), synchronously, and return it.
+ * Never blocks on the registry — the caller kicks off the newer-version check
+ * separately (see fetchUpdateNotice) so start is not stalled waiting on npm.
+ */
+export function printVersionLine(out = console.log) {
+    const current = resolveCliVersion();
+    out(`gaia v${current}`);
+    return current;
+}
+/**
+ * Best-effort "update available" notice for the given installed version
+ * (AC-3/AC-5). Fetches the latest published version (fail-silent → null on any
+ * error, AC-4) and compares. Returns the notice string or null. fetchImpl is
+ * injectable for tests.
+ */
+export async function fetchUpdateNotice(current, fetchImpl = globalThis.fetch) {
+    const latest = await fetchLatestVersion(fetchImpl);
+    if (latest === null)
+        return null;
+    return updateNotice(current, latest);
+}
+/**
+ * Print the installed gaia version (AC-2) and, best-effort, a newer-version
+ * notice (AC-3/AC-5). The registry check is fail-silent (AC-4): an offline
+ * registry prints only the version line. out/fetchImpl are injectable for tests.
+ */
+export async function printStartVersionBanner(out = console.log, fetchImpl = globalThis.fetch) {
+    const current = printVersionLine(out);
+    const notice = await fetchUpdateNotice(current, fetchImpl);
+    if (notice !== null)
+        out(notice);
+}

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

@@ -71,23 +71,25 @@ export declare class Conductor {
      */
     private finalizeDoneRuns;
     /**
-     * Reconcile finished tickets against their herdr worktrees and tear down any
+     * Reconcile closed tickets against their herdr worktrees and tear down any
      * whose workspace still lingers (GAIA-89). Driven by the durable `cleaned_up`
-     * flag via {@link GaiaRemote.fetchUncleanedTickets}: every ticket that is
-     * finished (state=done OR closed) but not yet cleaned. The SAME reconciliation
-     * runs on every tick AND standalone as `gaia conductor reap`, and the query is
+     * flag via {@link GaiaRemote.fetchUncleanedTickets}: every ticket the server
+     * has already closed but not yet cleaned. The SAME reconciliation runs on
+     * every tick AND standalone as `gaia conductor reap`, and the query is
      * scoped to THIS conductor (GAIA-121) — so it catches the orphans a
      * live-tick-only path structurally cannot (the conductor was down when the
-     * ticket hit `done`, or crashed mid-cleanup) for its OWN tickets. A foreign
+     * ticket closed, or crashed mid-cleanup) for its OWN tickets. A foreign
      * (non-gaia) worktree has no gaia ticket, so it is never on the work list; a
      * ticket assigned to another conductor is filtered out at the query — both are
      * left untouched with no host enumeration.
      *
-     * 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 withheld unless the teardown is
-     * ACCOUNTED FOR (GAIA-141 RC-2), which `removeWorktree` reports as one of
-     * three outcomes (GAIA-293):
+     * The conductor is structurally UNABLE to close a ticket (GAIA-451): closing
+     * is a server-side projection of terminality written by
+     * `GaiaTicket::preSave()` on any save of a terminal, unclosed ticket, so it
+     * holds for every write path and cannot be withheld by a teardown hiccup —
+     * the reap reasons about `cleaned_up` alone. `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

package/dist/src/core/conductor.js

@@ -330,23 +330,25 @@ export class Conductor {
         }
     }
     /**
-     * Reconcile finished tickets against their herdr worktrees and tear down any
+     * Reconcile closed tickets against their herdr worktrees and tear down any
      * whose workspace still lingers (GAIA-89). Driven by the durable `cleaned_up`
-     * flag via {@link GaiaRemote.fetchUncleanedTickets}: every ticket that is
-     * finished (state=done OR closed) but not yet cleaned. The SAME reconciliation
-     * runs on every tick AND standalone as `gaia conductor reap`, and the query is
+     * flag via {@link GaiaRemote.fetchUncleanedTickets}: every ticket the server
+     * has already closed but not yet cleaned. The SAME reconciliation runs on
+     * every tick AND standalone as `gaia conductor reap`, and the query is
      * scoped to THIS conductor (GAIA-121) — so it catches the orphans a
      * live-tick-only path structurally cannot (the conductor was down when the
-     * ticket hit `done`, or crashed mid-cleanup) for its OWN tickets. A foreign
+     * ticket closed, or crashed mid-cleanup) for its OWN tickets. A foreign
      * (non-gaia) worktree has no gaia ticket, so it is never on the work list; a
      * ticket assigned to another conductor is filtered out at the query — both are
      * left untouched with no host enumeration.
      *
-     * 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 withheld unless the teardown is
-     * ACCOUNTED FOR (GAIA-141 RC-2), which `removeWorktree` reports as one of
-     * three outcomes (GAIA-293):
+     * The conductor is structurally UNABLE to close a ticket (GAIA-451): closing
+     * is a server-side projection of terminality written by
+     * `GaiaTicket::preSave()` on any save of a terminal, unclosed ticket, so it
+     * holds for every write path and cannot be withheld by a teardown hiccup —
+     * the reap reasons about `cleaned_up` alone. `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
@@ -371,13 +373,6 @@ export class Conductor {
         const tickets = await this.remote.fetchUncleanedTickets(this.id);
         for (const t of tickets) {
             try {
-                // Lifecycle: close a done+unclosed ticket at once, decoupled from the
-                // infra teardown below — a done ticket whose conductor was down was
-                // never closed, and withholding the close on a teardown hiccup would
-                // make a finished ticket look unfinished (the pre-GAIA-89 defect).
-                if (t.state === 'done' && !t.closed) {
-                    await this.remote.closeTicket(t.ticketUuid);
-                }
                 // Infra teardown. The `after_done` hook runs in the worktree regardless
                 // of executor kind (a non-persistent gitWorkspace still has an on-disk
                 // worktree); only the workspace removal is gated on the persistent

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

@@ -116,12 +116,14 @@ export interface RunMetrics {
     user_prompt_words: number;
 }
 /**
- * A finished ticket whose worktree has not yet been torn down — the
+ * A closed ticket whose worktree has not yet been torn down — the
  * conductor's teardown work list, driven by the durable `cleaned_up` flag
- * (GAIA-89). "Finished" = reached `done` OR already `closed`; `cleaned_up=0`
- * means the herdr worktree still needs reclaiming. The reconciliation is NOT
- * scoped to a conductor's machine_id, so it also surfaces tickets whose
- * conductor was down at `done` or whose `conductor_id` was reassigned.
+ * (GAIA-89). Since GAIA-451 the server closes every terminal ticket on its own
+ * save, so "finished" collapses to `closed = 1`; `cleaned_up=0` (or never
+ * written at all) means the herdr worktree still needs reclaiming. The
+ * reconciliation is NOT scoped to a conductor's machine_id, so it also
+ * surfaces tickets whose conductor was down at close or whose `conductor_id`
+ * was reassigned.
  */
 export interface UncleanTicket {
     ticketUuid: string;
@@ -132,10 +134,6 @@ export interface UncleanTicket {
      * `worktree_path`), or '' when unresolved. The cwd the teardown runs in.
      */
     worktreePath: string;
-    /** Workflow state (e.g. `coding`, `done`). */
-    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
@@ -215,22 +213,19 @@ export interface GaiaRemote {
      */
     finalizeRun(uuid: string, log: string, metrics?: RunMetrics): Promise<void>;
     /**
-     * Finished tickets (state=done OR closed) whose worktree is not yet torn
-     * down (cleaned_up=0) — the conductor's teardown work list (GAIA-89). Driven
-     * by the durable `cleaned_up` flag AND scoped to the reaping conductor
-     * (GAIA-121): only tickets assigned to `conductorId` are loaded, so every
-     * ticket on the list is unambiguously this conductor's — a missing worktree
-     * means "already torn down on this host", not "belongs to another host". The
-     * same query backs the live tick and the standalone `gaia conductor reap`.
-     * Empty once every finished ticket this conductor owns is cleaned.
+     * Closed tickets (closed=1) whose worktree is not yet torn down
+     * (cleaned_up=0, or never written at all) — the conductor's teardown work
+     * list (GAIA-89). Since GAIA-451 the server closes every terminal ticket on
+     * its own save, so this asks one question — closed but not cleaned up —
+     * with no workflow-state reasoning left in it. Driven by the durable
+     * `cleaned_up` flag AND scoped to the reaping conductor (GAIA-121): only
+     * tickets assigned to `conductorId` are loaded, so every ticket on the list
+     * is unambiguously this conductor's — a missing worktree means "already torn
+     * down on this host", not "belongs to another host". The same query backs
+     * the live tick and the standalone `gaia conductor reap`. Empty once every
+     * closed ticket this conductor owns is cleaned.
      */
     fetchUncleanedTickets(conductorId: string): Promise<UncleanTicket[]>;
-    /**
-     * Close a ticket: set closed=true + closed_date. Ticket-lifecycle only, and
-     * decoupled from teardown — a done ticket is closed even if its worktree
-     * teardown later fails. No state change (the ticket is already done).
-     */
-    closeTicket(uuid: string): Promise<void>;
     /**
      * Mark a ticket's worktree torn down: set cleaned_up=true so it drops off the
      * {@link fetchUncleanedTickets} work list. Written ONLY after a verified

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaia-ai/conductor",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "GAIA conductor engine + CLI: registers, claims tickets via JSON:API, dispatches agents.",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,7 @@
     "directory": "gaia-cli/conductor"
   },
   "dependencies": {
-    "@gaia-ai/core": "^0.11.1",
+    "@gaia-ai/core": "^0.11.2",
     "@dropsh/plugin-oauth2": "^0.6.1",
     "@dropsh/plugin-jsonapi-schema": "^0.6.1",
     "commander": "^12.1.0",