@cluesmith/codev 3.3.2 → 3.3.4

package/dist/agent-farm/db/tower-owner.d.ts

@@ -0,0 +1,168 @@
+/**
+ * global.db owner lock (Issue #1629).
+ *
+ * The port bind in tower-server.ts is a SAME-PORT mutex only: a second Tower on
+ * a DIFFERENT port can still open the same global.db. That is exactly how the
+ * incident happened — a test Tower on port 14733 exported `AGENT_FARM_DIR`
+ * instead of `CODEV_AGENT_FARM_DIR` (#1515), so it resolved to the production
+ * `~/.agent-farm` and opened the live `global.db` (port and DB path are set by
+ * independent inputs: the port is a CLI arg, the DB comes from AGENT_FARM_DIR).
+ * Its startup reconcile then reconnected every live shellper socket (a shellper
+ * holds ONE client), stealing them from the real Tower on 4100, and the
+ * stale-row sweep deleted the rows.
+ *
+ * This module makes the second Tower REFUSE to start instead. The owner record
+ * is an exclusive LOCK FILE sitting next to the exact global.db being contended
+ * (`<db path>.tower-owner`), so it travels with that file: cross-`CODEV_AGENT_FARM_DIR`
+ * isolation is untouched (an isolated DB carries its own lock), and two isolated
+ * test Towers on different DB files never share a lock. Acquisition is an atomic
+ * `O_EXCL` create — the filesystem itself resolves a race between two starters. A
+ * second Tower reads the lock at boot, before reconcile; if a live Tower owns the
+ * DB it refuses loudly, otherwise it claims. A dead owner self-clears — a crashed
+ * Tower's lock has a dead pid, so the legitimate restart just reclaims.
+ *
+ * The lock is deliberately NOT a table in global.db: ownership is ephemeral
+ * process state (a cleanly-stopped Tower leaves nothing behind), so it needs no
+ * durable schema, no migration, and it sits naturally alongside the other
+ * runtime artifacts in AGENT_FARM_DIR (`tower.log`, `local-key`).
+ */
+/** The owner record persisted in the lock file next to global.db. */
+export interface TowerOwner {
+    /** pid of the Tower process that owns this global.db. */
+    pid: number;
+    /** Port that Tower is listening on (the liveness probe target). */
+    port: number;
+    /** Machine the owning Tower runs on (diagnostic only). */
+    hostname: string;
+    /** When ownership was claimed (epoch ms; also the compare-and-set discriminator). */
+    startedAt: number;
+    /** Resolved AGENT_FARM_DIR the owner opened — surfaced in the conflict error. */
+    dbDir: string;
+    /**
+     * Interface the owner listens on — the liveness probe's target host. Default
+     * `127.0.0.1`; bridge mode may bind a specific non-loopback host, and probing
+     * loopback would then miss it (a false "gone" → hijack). `0.0.0.0`/`::` are
+     * resolved back to loopback for the probe.
+     */
+    bindHost: string;
+}
+/**
+ * The lock file for the active global.db: the DB path plus `.tower-owner`.
+ *
+ * The suffix is deliberately NOT `.lock`: SQLite's `unix-dotfile` VFS (a fallback
+ * on filesystems without POSIX locks) creates `<db>.lock`, which would collide.
+ * `.tower-owner` avoids every SQLite auxiliary name (`-wal`, `-shm`, `-journal`,
+ * `-mj*`, and the dotfile VFS's `.lock`).
+ */
+export declare function defaultLockFile(): string;
+/**
+ * Read the owner record from the lock file, or null if the lock is absent or its
+ * contents are unusable (corrupt / a partial write from a crashed acquire — the
+ * caller clears and reclaims those). A genuine IO error other than "not found"
+ * (permission, EISDIR) is rethrown so the boot guard fails CLOSED.
+ */
+export declare function readTowerOwner(lockFile: string): TowerOwner | null;
+/** Overwrite the lock file with `owner` (non-atomic; for takeover seams / tests). */
+export declare function writeTowerOwner(lockFile: string, owner: TowerOwner): void;
+/**
+ * Remove the lock file, but ONLY if it is still ours (pid match). Best-effort: a
+ * hard kill (SIGKILL) never reaches this, and the dead-pid liveness check
+ * self-clears the stale lock on the next start regardless. Called on graceful
+ * shutdown so the lock reflects reality between a clean stop and the next start.
+ */
+export declare function releaseTowerOwnerIfMine(lockFile: string, pid: number): void;
+/**
+ * The three distinguishable states of the owner's `/health` port.
+ * - `tower`: a live Tower answered — a healthy 200, OR a 503 `STARTING_UP` while
+ *   its readiness gate holds requests mid-boot. Both mean a live Tower owns it.
+ * - `gone`: proof the owner is NOT here — the connection was refused (port free),
+ *   or a non-Tower process answered (a squatter on a recycled port/pid). Claim.
+ * - `unreachable`: inconclusive — a timeout or transport error. A live Tower
+ *   under load (its `/health` shells out to `ps -A`) or mid-boot can miss the
+ *   budget, so this must NOT be read as "gone". The caller treats it as live.
+ */
+export type HealthProbe = 'tower' | 'gone' | 'unreachable';
+/**
+ * Probe `GET /health` on `host`:`port` (unauthenticated per server-utils).
+ *
+ * The budget is generous by default: `/health` calls `getInstances()` and shells
+ * out to `ps -A` (a 5s timeout of its own), so under the incident's load — 60+
+ * shellpers, a busy event loop — a tight budget would time out and be misread as
+ * "no Tower here", failing OPEN on the one guard that prevents data loss. Only
+ * paid on the conflict path (a live pid on a different port), so it costs nothing
+ * on the common restart.
+ */
+export declare function probeTowerHealth(host: string, port: number, timeoutMs?: number): Promise<HealthProbe>;
+/**
+ * Resolve the host to probe from the owner's recorded bind interface. A wildcard
+ * bind (`0.0.0.0` / `::` / bracketed `[::]` as validateHost emits) accepts
+ * loopback, so probe `127.0.0.1`; a specific bridge host is probed directly
+ * (probing loopback would falsely read 'gone').
+ */
+export declare function resolveProbeHost(bindHost: string | null | undefined): string;
+/** Injectable liveness seams — real implementations by default; fakes in tests. */
+export interface OwnerLivenessDeps {
+    isAlive?: (pid: number) => boolean;
+    probe?: (host: string, port: number) => Promise<HealthProbe>;
+}
+/**
+ * Decide whether the recorded owner is a live Tower this process must yield to.
+ *
+ * - same port AND same bind interface as us: our own `server.listen` succeeded
+ *   on that exact interface:port, and an identical bind is exclusive, so no other
+ *   process holds it — any prior owner recorded there is gone. Claim. The bind
+ *   interface must match: a wildcard bind (`0.0.0.0:P`) and a loopback bind
+ *   (`127.0.0.1:P`) COEXIST on the same port, so `port` alone matching does not
+ *   prove a differently-bound owner is gone — that path falls through to the probe.
+ * - dead owner pid: stale (a crashed Tower / a clean stop that outran the
+ *   release). Claim — this is the self-clearing legitimate restart.
+ * - live pid: probe the owner's port. Only a `gone` result (connection refused,
+ *   or a non-Tower response) proves the owner is absent → claim. A `tower`
+ *   response, OR an `unreachable` inconclusive probe against a still-live pid, is
+ *   treated as a live owner → refuse. This fails CLOSED: a loaded or mid-boot
+ *   Tower whose `/health` misses the budget is never mistaken for a free DB.
+ */
+export declare function ownerIsLive(owner: TowerOwner, myPort: number, myBindHost: string, deps?: OwnerLivenessDeps): Promise<boolean>;
+/** Outcome of {@link claimGlobalDbOwnership}. */
+export type ClaimResult = {
+    ok: true;
+} | {
+    ok: false;
+    conflict: TowerOwner;
+};
+/**
+ * Boot guard: refuse if the DB already has a LIVE owner, otherwise claim
+ * ownership by writing the lock file. A decision plus a lock write — the caller
+ * decides how to fail loudly (log + exit).
+ *
+ * Acquisition is atomic against a concurrent second Tower: {@link tryAcquire}
+ * writes a full temp file and hard-links it onto the path, so the filesystem
+ * resolves a two-starter race (one link wins, the other gets EEXIST) with no
+ * empty-file window. A stale lock (dead / absent owner) is cleared with a
+ * compare-and-set on its contents and the link retried; the invariant preserved
+ * is "never remove a LIVE owner's lock". Under persistent churn the claim refuses
+ * rather than forcing the lock.
+ */
+export declare function claimGlobalDbOwnership(opts: {
+    /** Lock file path; defaults to the active global.db's `.lock` sibling. */
+    lockFile?: string;
+    pid: number;
+    port: number;
+    dbDir: string;
+    /** Interface this Tower listens on (default `127.0.0.1`); persisted as the probe target. */
+    bindHost?: string;
+    deps?: OwnerLivenessDeps;
+}): Promise<ClaimResult>;
+/**
+ * The loud, teaching error for a refused start. Names the live owner (pid/port/
+ * host) and the shared DB, and — because the misconfiguration that triggered the
+ * incident was a mistyped env var — spells out the `AGENT_FARM_DIR` vs
+ * `CODEV_AGENT_FARM_DIR` fix.
+ *
+ * This string is user-visible at the CLI (surfaced by the launcher on a fast-exit,
+ * Issue #1691), so it carries no internal issue numbers — the incident context
+ * (#1629's shellper hijack, the #1515 mistyped-env-var trigger) stays here in the
+ * comment, not in the text a user reads.
+ */
+export declare function ownershipConflictMessage(conflict: TowerOwner, dbDir: string): string;
+//# sourceMappingURL=tower-owner.d.ts.map

package/dist/agent-farm/db/tower-owner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tower-owner.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/db/tower-owner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AASH,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAOD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAsBlE;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAGzE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAO3E;AAYD;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,aAAa,CAAC;AAE3D;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CA6DnG;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAQ5E;AAED,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACnC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;CAC9D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED,iDAAiD;AACjD,MAAM,MAAM,WAAW,GACnB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,UAAU,CAAA;CAAE,CAAC;AAiExC;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,iBAAiB,CAAC;CAC1B,GAAG,OAAO,CAAC,WAAW,CAAC,CAoCvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CASpF"}

package/dist/agent-farm/db/tower-owner.js

@@ -0,0 +1,369 @@
+/**
+ * global.db owner lock (Issue #1629).
+ *
+ * The port bind in tower-server.ts is a SAME-PORT mutex only: a second Tower on
+ * a DIFFERENT port can still open the same global.db. That is exactly how the
+ * incident happened — a test Tower on port 14733 exported `AGENT_FARM_DIR`
+ * instead of `CODEV_AGENT_FARM_DIR` (#1515), so it resolved to the production
+ * `~/.agent-farm` and opened the live `global.db` (port and DB path are set by
+ * independent inputs: the port is a CLI arg, the DB comes from AGENT_FARM_DIR).
+ * Its startup reconcile then reconnected every live shellper socket (a shellper
+ * holds ONE client), stealing them from the real Tower on 4100, and the
+ * stale-row sweep deleted the rows.
+ *
+ * This module makes the second Tower REFUSE to start instead. The owner record
+ * is an exclusive LOCK FILE sitting next to the exact global.db being contended
+ * (`<db path>.tower-owner`), so it travels with that file: cross-`CODEV_AGENT_FARM_DIR`
+ * isolation is untouched (an isolated DB carries its own lock), and two isolated
+ * test Towers on different DB files never share a lock. Acquisition is an atomic
+ * `O_EXCL` create — the filesystem itself resolves a race between two starters. A
+ * second Tower reads the lock at boot, before reconcile; if a live Tower owns the
+ * DB it refuses loudly, otherwise it claims. A dead owner self-clears — a crashed
+ * Tower's lock has a dead pid, so the legitimate restart just reclaims.
+ *
+ * The lock is deliberately NOT a table in global.db: ownership is ephemeral
+ * process state (a cleanly-stopped Tower leaves nothing behind), so it needs no
+ * durable schema, no migration, and it sits naturally alongside the other
+ * runtime artifacts in AGENT_FARM_DIR (`tower.log`, `local-key`).
+ */
+import http from 'node:http';
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { getGlobalDbPath } from './index.js';
+/**
+ * The lock file for the active global.db: the DB path plus `.tower-owner`.
+ *
+ * The suffix is deliberately NOT `.lock`: SQLite's `unix-dotfile` VFS (a fallback
+ * on filesystems without POSIX locks) creates `<db>.lock`, which would collide.
+ * `.tower-owner` avoids every SQLite auxiliary name (`-wal`, `-shm`, `-journal`,
+ * `-mj*`, and the dotfile VFS's `.lock`).
+ */
+export function defaultLockFile() {
+    return `${getGlobalDbPath()}.tower-owner`;
+}
+/** Serialize an owner record to the lock file's on-disk form. */
+function serialize(owner) {
+    return JSON.stringify(owner);
+}
+/**
+ * Read the owner record from the lock file, or null if the lock is absent or its
+ * contents are unusable (corrupt / a partial write from a crashed acquire — the
+ * caller clears and reclaims those). A genuine IO error other than "not found"
+ * (permission, EISDIR) is rethrown so the boot guard fails CLOSED.
+ */
+export function readTowerOwner(lockFile) {
+    let raw;
+    try {
+        raw = fs.readFileSync(lockFile, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    try {
+        const o = JSON.parse(raw);
+        if (typeof o.pid !== 'number' || typeof o.port !== 'number')
+            return null;
+        return {
+            pid: o.pid,
+            port: o.port,
+            hostname: typeof o.hostname === 'string' ? o.hostname : 'unknown',
+            startedAt: typeof o.startedAt === 'number' ? o.startedAt : 0,
+            dbDir: typeof o.dbDir === 'string' ? o.dbDir : '',
+            bindHost: typeof o.bindHost === 'string' ? o.bindHost : '127.0.0.1',
+        };
+    }
+    catch {
+        return null; // unparseable → treat as a corrupt lock the caller can clear
+    }
+}
+/** Overwrite the lock file with `owner` (non-atomic; for takeover seams / tests). */
+export function writeTowerOwner(lockFile, owner) {
+    fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+    fs.writeFileSync(lockFile, serialize(owner));
+}
+/**
+ * Remove the lock file, but ONLY if it is still ours (pid match). Best-effort: a
+ * hard kill (SIGKILL) never reaches this, and the dead-pid liveness check
+ * self-clears the stale lock on the next start regardless. Called on graceful
+ * shutdown so the lock reflects reality between a clean stop and the next start.
+ */
+export function releaseTowerOwnerIfMine(lockFile, pid) {
+    try {
+        const cur = readTowerOwner(lockFile);
+        if (cur && cur.pid === pid)
+            fs.rmSync(lockFile, { force: true });
+    }
+    catch {
+        // Lock gone / unreadable — nothing to release.
+    }
+}
+/** Whether a pid is a live process (SIGnal 0 probe, same as processExists). */
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Probe `GET /health` on `host`:`port` (unauthenticated per server-utils).
+ *
+ * The budget is generous by default: `/health` calls `getInstances()` and shells
+ * out to `ps -A` (a 5s timeout of its own), so under the incident's load — 60+
+ * shellpers, a busy event loop — a tight budget would time out and be misread as
+ * "no Tower here", failing OPEN on the one guard that prevents data loss. Only
+ * paid on the conflict path (a live pid on a different port), so it costs nothing
+ * on the common restart.
+ */
+export function probeTowerHealth(host, port, timeoutMs = 6000) {
+    return new Promise((resolve) => {
+        const req = http.request({ hostname: host, port, path: '/health', method: 'GET', timeout: timeoutMs }, (res) => {
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (chunk) => {
+                body += chunk;
+                // A tower /health payload is small; cap the read so a chatty non-tower
+                // process on the port can't stream unboundedly.
+                if (body.length > 64_000) {
+                    res.destroy();
+                    resolve('gone');
+                }
+            });
+            res.on('end', () => {
+                if (res.statusCode === 200) {
+                    try {
+                        resolve(JSON.parse(body).status === 'healthy' ? 'tower' : 'gone');
+                    }
+                    catch {
+                        resolve('gone');
+                    }
+                    return;
+                }
+                if (res.statusCode === 503) {
+                    // A live Tower can answer 503 {"error":"STARTING_UP"} from its readiness
+                    // gate. In practice a mid-boot Tower usually HOLDS /health past this
+                    // probe's budget, so that case times out to 'unreachable' (also refused);
+                    // this branch covers a 503 returned within budget. Either way, a live owner.
+                    try {
+                        resolve(JSON.parse(body).error === 'STARTING_UP' ? 'tower' : 'unreachable');
+                    }
+                    catch {
+                        resolve('unreachable');
+                    }
+                    return;
+                }
+                // Any other 5xx: a degraded-but-live server may answer 500 rather than a
+                // clean /health. Treat as inconclusive (fail closed), never as absent.
+                if (res.statusCode && res.statusCode >= 500) {
+                    resolve('unreachable');
+                    return;
+                }
+                // A non-5xx, non-Tower HTTP response — a process answered, but it is not
+                // a Tower serving /health (a squatter on a recycled port).
+                resolve('gone');
+            });
+        });
+        req.on('error', (err) => {
+            // ECONNREFUSED = nothing is listening on the port, so the recorded owner is
+            // not serving it (a live Tower always holds its port) → gone. Any other
+            // transport error is inconclusive → unreachable (fail closed).
+            resolve(err.code === 'ECONNREFUSED' ? 'gone' : 'unreachable');
+        });
+        req.on('timeout', () => {
+            req.destroy();
+            resolve('unreachable');
+        });
+        req.end();
+    });
+}
+/**
+ * Resolve the host to probe from the owner's recorded bind interface. A wildcard
+ * bind (`0.0.0.0` / `::` / bracketed `[::]` as validateHost emits) accepts
+ * loopback, so probe `127.0.0.1`; a specific bridge host is probed directly
+ * (probing loopback would falsely read 'gone').
+ */
+export function resolveProbeHost(bindHost) {
+    if (!bindHost || bindHost === '0.0.0.0' || bindHost === '::' || bindHost === '[::]')
+        return '127.0.0.1';
+    // A specific bracketed IPv6 literal ([::1], [2001:db8::1]): http.request's
+    // `hostname` wants the address WITHOUT brackets, or it rejects it and the probe
+    // is never conclusive. Strip them.
+    const ipv6 = bindHost.match(/^\[(.+)\]$/);
+    if (ipv6)
+        return ipv6[1];
+    return bindHost;
+}
+/**
+ * Decide whether the recorded owner is a live Tower this process must yield to.
+ *
+ * - same port AND same bind interface as us: our own `server.listen` succeeded
+ *   on that exact interface:port, and an identical bind is exclusive, so no other
+ *   process holds it — any prior owner recorded there is gone. Claim. The bind
+ *   interface must match: a wildcard bind (`0.0.0.0:P`) and a loopback bind
+ *   (`127.0.0.1:P`) COEXIST on the same port, so `port` alone matching does not
+ *   prove a differently-bound owner is gone — that path falls through to the probe.
+ * - dead owner pid: stale (a crashed Tower / a clean stop that outran the
+ *   release). Claim — this is the self-clearing legitimate restart.
+ * - live pid: probe the owner's port. Only a `gone` result (connection refused,
+ *   or a non-Tower response) proves the owner is absent → claim. A `tower`
+ *   response, OR an `unreachable` inconclusive probe against a still-live pid, is
+ *   treated as a live owner → refuse. This fails CLOSED: a loaded or mid-boot
+ *   Tower whose `/health` misses the budget is never mistaken for a free DB.
+ */
+export async function ownerIsLive(owner, myPort, myBindHost, deps = {}) {
+    const isAlive = deps.isAlive ?? pidAlive;
+    const probe = deps.probe ?? probeTowerHealth;
+    if (owner.port === myPort && owner.bindHost === myBindHost)
+        return false;
+    if (!isAlive(owner.pid))
+        return false;
+    return (await probe(resolveProbeHost(owner.bindHost), owner.port)) !== 'gone';
+}
+/**
+ * Bound on the acquire attempts under contention. Each losing attempt means
+ * another Tower held or rewrote the lock between our checks; a handful of retries
+ * converges in every realistic case, and exhausting them means the lock is
+ * churning between many simultaneous starts — where the safe answer is to refuse
+ * (fail closed), never to force the lock.
+ */
+const MAX_CLAIM_ATTEMPTS = 5;
+/**
+ * Atomically acquire the lock: write the FULL record to a unique temp file, then
+ * hard-link it onto the lock path. `link()` is atomic and fails with EEXIST if
+ * the path is already taken, and — unlike `writeFile({flag:'wx'})` — the linked
+ * file already has its complete content, so a concurrent reader never sees an
+ * empty/partial lock it could misclassify as corrupt and delete mid-write. The
+ * temp is always cleaned up (the hard link keeps the inode alive at the lock path).
+ * Returns whether we won the link.
+ */
+function tryAcquire(lockFile, owner) {
+    fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+    const tmp = `${lockFile}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    fs.writeFileSync(tmp, serialize(owner));
+    try {
+        fs.linkSync(tmp, lockFile);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EEXIST')
+            return false;
+        // Some filesystems don't support hard links (ENOSYS/EPERM, or a cross-device
+        // temp on EXDEV). Fall back to an O_EXCL create — a hair weaker (a brief
+        // empty-file window) but better than failing to boot at all.
+        if (code === 'ENOSYS' || code === 'EPERM' || code === 'EXDEV') {
+            try {
+                fs.writeFileSync(lockFile, serialize(owner), { flag: 'wx' });
+                return true;
+            }
+            catch (fallbackErr) {
+                if (fallbackErr.code === 'EEXIST')
+                    return false;
+                throw fallbackErr;
+            }
+        }
+        throw err;
+    }
+    finally {
+        try {
+            fs.rmSync(tmp, { force: true });
+        }
+        catch { /* temp already gone */ }
+    }
+}
+/**
+ * Remove a stale lock, but ONLY if it still names the holder we probed (a
+ * compare-and-set on pid + startedAt). If a contender rewrote it in between, the
+ * content differs and we do NOT remove it — we loop and re-evaluate. Returns
+ * whether we removed it.
+ */
+function removeStaleLock(lockFile, observed) {
+    const cur = readTowerOwner(lockFile);
+    if (!cur || cur.pid !== observed.pid || cur.startedAt !== observed.startedAt)
+        return false;
+    try {
+        fs.rmSync(lockFile, { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Boot guard: refuse if the DB already has a LIVE owner, otherwise claim
+ * ownership by writing the lock file. A decision plus a lock write — the caller
+ * decides how to fail loudly (log + exit).
+ *
+ * Acquisition is atomic against a concurrent second Tower: {@link tryAcquire}
+ * writes a full temp file and hard-links it onto the path, so the filesystem
+ * resolves a two-starter race (one link wins, the other gets EEXIST) with no
+ * empty-file window. A stale lock (dead / absent owner) is cleared with a
+ * compare-and-set on its contents and the link retried; the invariant preserved
+ * is "never remove a LIVE owner's lock". Under persistent churn the claim refuses
+ * rather than forcing the lock.
+ */
+export async function claimGlobalDbOwnership(opts) {
+    const lockFile = opts.lockFile ?? defaultLockFile();
+    const { pid, port, dbDir, deps } = opts;
+    const bindHost = opts.bindHost ?? '127.0.0.1';
+    let lastSeen = null;
+    for (let attempt = 0; attempt < MAX_CLAIM_ATTEMPTS; attempt++) {
+        const mine = { pid, port, hostname: os.hostname(), startedAt: Date.now(), dbDir, bindHost };
+        // Atomic acquire: full-content temp + hard link (see tryAcquire).
+        if (tryAcquire(lockFile, mine))
+            return { ok: true };
+        // Lock exists — evaluate the current holder.
+        const existing = readTowerOwner(lockFile);
+        if (!existing) {
+            // Corrupt / vanished under us — clear it and retry the atomic acquire.
+            try {
+                fs.rmSync(lockFile, { force: true });
+            }
+            catch { /* already gone */ }
+            continue;
+        }
+        lastSeen = existing;
+        if (await ownerIsLive(existing, port, bindHost, deps)) {
+            return { ok: false, conflict: existing };
+        }
+        // Stale — remove ONLY if the lock still names the holder we probed, then loop
+        // to re-attempt the atomic acquire (the link is the serialization point). A
+        // failed CAS means a contender rewrote it: loop and re-evaluate, never force.
+        removeStaleLock(lockFile, existing);
+    }
+    // Persistent contention: the lock keeps changing under us. Refuse rather than
+    // risk forcing over a live claimant that appeared mid-flight. Name a real
+    // contender we observed, never ourselves (Claude CMAP).
+    const conflict = readTowerOwner(lockFile) ?? lastSeen ?? {
+        pid: -1, port, hostname: 'unknown (lock contended)', startedAt: Date.now(), dbDir, bindHost,
+    };
+    return { ok: false, conflict };
+}
+/**
+ * The loud, teaching error for a refused start. Names the live owner (pid/port/
+ * host) and the shared DB, and — because the misconfiguration that triggered the
+ * incident was a mistyped env var — spells out the `AGENT_FARM_DIR` vs
+ * `CODEV_AGENT_FARM_DIR` fix.
+ *
+ * This string is user-visible at the CLI (surfaced by the launcher on a fast-exit,
+ * Issue #1691), so it carries no internal issue numbers — the incident context
+ * (#1629's shellper hijack, the #1515 mistyped-env-var trigger) stays here in the
+ * comment, not in the text a user reads.
+ */
+export function ownershipConflictMessage(conflict, dbDir) {
+    return [
+        `Refusing to start: this global.db is already owned by a live Tower.`,
+        `  owner pid ${conflict.pid} on port ${conflict.port} (host ${conflict.hostname})`,
+        `  shared database dir: ${dbDir}`,
+        `A second Tower opening a live global.db hijacks and deletes its shellper sessions.`,
+        `If you meant to run an isolated test Tower, set CODEV_AGENT_FARM_DIR (NOT AGENT_FARM_DIR) to a throwaway directory.`,
+        `Otherwise stop the existing Tower first ('afx tower stop'), or investigate pid ${conflict.pid} if you believe it is stale.`,
+    ].join('\n');
+}
+//# sourceMappingURL=tower-owner.js.map

package/dist/agent-farm/db/tower-owner.js.map

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

package/dist/agent-farm/db/types.d.ts

@@ -84,6 +84,52 @@ export type MailboxStatus = 'held' | 'delivered' | 'superseded' | 'dismissed';
  *   - `no-live-pty` — the recipient agent has no live terminal right now
  */
 export type MailboxReason = 'busy' | 'no-profile' | 'no-live-pty';
+/**
+ * The render gate's classification detail behind a `busy` hold (Issue #1482). Persisted
+ * beside {@link MailboxReason} so every operator surface can tell the two apart:
+ *   - `user-text`           — a draft or menu occupies the composer. A human is at the line;
+ *                             this is the SAFE, intended hold and it clears when they finish.
+ *   - `no-region-end`       — a composer marker with no rule/status line beneath it to bound
+ *                             the region (a partial/mid-repaint frame, or a mirror rendered at
+ *                             dims the real TUI never adopted).
+ *   - `no-composer-marker`  — no recognized marker at all (a wrapper/boot screen, a drifted
+ *                             profile, or an unrenderable frame).
+ *   - `recent-input`        — the terminal saw INPUT too recently to write onto (Issue #1473):
+ *                             either it landed while the gate was classifying, or the
+ *                             input-settle interval has not elapsed. "Input" is whatever
+ *                             survives `stripTerminalReplies` on a write reaching the PTY
+ *                             under `PtySession.write()`'s default `'external'` origin — a
+ *                             human's keystrokes, and equally an ungated `--interrupt`/
+ *                             `--escape`, which is why the operator wording says "input"
+ *                             rather than "typing"; a chunk that is nothing but a terminal
+ *                             REPLY moves neither signal. Like `user-text` this
+ *                             is a SAFE hold that clears on its own — the same someone-else-is-
+ *                             writing class, caught one beat earlier, before the TUI has echoed
+ *                             anything for the classifier to see.
+ *   - `composer-redraw`     — the composer is EMPTY but its rendered region changed within the
+ *                             settle window (Issue #1664): a turn-end box redraw, a rotating
+ *                             placeholder, a resize, or an interrupt clearing the line. The
+ *                             recipient's own output ELSEWHERE on the screen — a spinner, a
+ *                             streaming transcript — is deliberately NOT this: writing onto an
+ *                             empty composer while the agent talks is safe and intended, since
+ *                             claude/codex queue input received mid-turn. Self-clearing, like
+ *                             `user-text` and `recent-input`; it resolves about a settle after
+ *                             the composer stops moving.
+ * The two can't-verify values are the DEFECT class: the classifier could not verify anything,
+ * so the mail will not deliver on its own. `GateVerdict.detail`'s fourth value, `empty`, is
+ * never persisted — a clean verdict delivers the row (and delivery nulls both columns).
+ *
+ * `recent-input` and `composer-redraw` are deliberately NOT part of {@link isUnverifiableVerdict}'s
+ * set: escalating either would false-alarm on every ordinary typist and every ordinary repaint. That predicate is an allow-list, so the value is
+ * correctly inert there by construction rather than by an edit.
+ *
+ * Null for every non-gate hold (`no-live-pty`, `no-profile`) and for the post-classify
+ * token re-hold, so a stale detail can never outlive the verdict that produced it.
+ *
+ * The DB column carries NO CHECK constraint (see `GLOBAL_SCHEMA` / migration v18); this type
+ * is the enforcement.
+ */
+export type MailboxGateDetail = 'user-text' | 'no-region-end' | 'no-composer-marker' | 'recent-input' | 'composer-redraw';
 /**
  * Database row type for the mailbox table (Spec 1313).
  *
@@ -105,6 +151,7 @@ export interface DbMailbox {
     no_enter: number;
     status: MailboxStatus;
     reason: MailboxReason | null;
+    detail: MailboxGateDetail | null;
     supersede_key: string | null;
     escalated: number;
     not_before: number | null;

package/dist/agent-farm/db/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/db/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/db/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,UAAU,EAAe,MAAM,aAAa,CAAC;AAElG;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,YAAY,GAAG,WAAW,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,YAAY,GAAG,aAAa,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,eAAe,GACf,oBAAoB,GACpB,cAAc,GACd,iBAAiB,CAAC;AAEtB;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,WAAW,GAAG,cAAc,CAQ5E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAe1D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAM9D;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,YAAY,GAAG,UAAU,CAStE"}

package/dist/agent-farm/db/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/agent-farm/db/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsHH;;GAEG;AACH,MAAM,UAAU,2BAA2B,CAAC,GAAgB;IAC1D,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,EAAE;QACZ,GAAG,EAAE,GAAG,CAAC,GAAG;QACZ,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,UAAU,EAAE,GAAG,CAAC,WAAW,IAAI,SAAS;QACxC,SAAS,EAAE,GAAG,CAAC,UAAU,IAAI,SAAS;KACvC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAc;IAC/C,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,MAAM,EAAE,GAAG,CAAC,MAA2B;QACvC,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,IAAI,EAAE,GAAG,CAAC,IAAmB;QAC7B,QAAQ,EAAE,GAAG,CAAC,SAAS,IAAI,SAAS;QACpC,YAAY,EAAE,GAAG,CAAC,aAAa,IAAI,SAAS;QAC5C,WAAW,EAAE,GAAG,CAAC,YAAY,IAAI,SAAS;QAC1C,UAAU,EAAE,GAAG,CAAC,WAAW,IAAI,SAAS;QACxC,kBAAkB,EAAE,GAAG,CAAC,oBAAoB,IAAI,SAAS;KAC1D,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,UAAU,EAAE,GAAG,CAAC,WAAW,IAAI,SAAS;KACzC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAiB;IACxD,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,MAAM,EAAE;YACN,IAAI,EAAE,GAAG,CAAC,WAA2C;YACrD,EAAE,EAAE,GAAG,CAAC,SAAS,IAAI,SAAS;SAC/B;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/agent-farm/db/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA2KH;;GAEG;AACH,MAAM,UAAU,2BAA2B,CAAC,GAAgB;IAC1D,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,EAAE;QACZ,GAAG,EAAE,GAAG,CAAC,GAAG;QACZ,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,UAAU,EAAE,GAAG,CAAC,WAAW,IAAI,SAAS;QACxC,SAAS,EAAE,GAAG,CAAC,UAAU,IAAI,SAAS;KACvC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAc;IAC/C,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,MAAM,EAAE,GAAG,CAAC,MAA2B;QACvC,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,IAAI,EAAE,GAAG,CAAC,IAAmB;QAC7B,QAAQ,EAAE,GAAG,CAAC,SAAS,IAAI,SAAS;QACpC,YAAY,EAAE,GAAG,CAAC,aAAa,IAAI,SAAS;QAC5C,WAAW,EAAE,GAAG,CAAC,YAAY,IAAI,SAAS;QAC1C,UAAU,EAAE,GAAG,CAAC,WAAW,IAAI,SAAS;QACxC,kBAAkB,EAAE,GAAG,CAAC,oBAAoB,IAAI,SAAS;KAC1D,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,UAAU,EAAE,GAAG,CAAC,WAAW,IAAI,SAAS;KACzC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAiB;IACxD,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,MAAM,EAAE;YACN,IAAI,EAAE,GAAG,CAAC,WAA2C;YACrD,EAAE,EAAE,GAAG,CAAC,SAAS,IAAI,SAAS;SAC/B;KACF,CAAC;AACJ,CAAC"}