@phnx-labs/agents-cli 1.22.114 → 1.22.116

package/dist/lib/session/tail.js

@@ -73,3 +73,222 @@ export function readSessionTailWithRaw(filePath, agent, maxBytes = DEFAULT_MAX_B
 export function readSessionTail(filePath, agent, maxBytes = DEFAULT_MAX_BYTES, maxEvents = DEFAULT_MAX_EVENTS) {
     return readSessionTailWithRaw(filePath, agent, maxBytes, maxEvents).events;
 }
+/** A session's original first turn is typically within the first few KiB —
+ * far smaller than the tail window, since it's exactly one line near the
+ * start of the file, not a rolling window of recent activity. */
+const DEFAULT_HEAD_MAX_BYTES = 32 * 1024;
+/**
+ * Read exactly the first `maxBytes` of the file and, if that chunk doesn't
+ * reach EOF, drop a trailing partial line so downstream per-line parsers only
+ * see whole lines. This is the plain, cheap path — correct and unchanged for
+ * the overwhelming majority of transcripts, where the opening JSONL record is
+ * a few hundred bytes. Returns '' on any error, an empty file, or a chunk that
+ * turned out to hold no complete line at all (the record is bigger than
+ * `maxBytes`) — callers needing to recover from THAT case use
+ * {@link readSessionHeadContentBounded}, not this.
+ */
+function readSessionHeadChunk(filePath, maxBytes) {
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const size = fs.fstatSync(fd).size;
+        if (size === 0)
+            return { content: '', sawEof: true };
+        const len = Math.min(size, maxBytes);
+        const buf = Buffer.alloc(len);
+        fs.readSync(fd, buf, 0, len, 0);
+        return { content: buf.toString('utf8'), sawEof: len >= size };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Read the FIRST `maxBytes` of a JSONL transcript as cleaned text — the mirror
+ * of {@link readSessionTailContent}, for recovering the session's ACTUAL
+ * original request boundedly when it isn't already indexed
+ * (`SessionMeta.firstUserMessage`). Returns '' on any error, an empty file, or
+ * a first record too large to fit `maxBytes` (bare — no elision fallback; see
+ * {@link readSessionHeadContentBounded} for that).
+ */
+export function readSessionHeadContent(filePath, maxBytes = DEFAULT_HEAD_MAX_BYTES) {
+    const chunk = readSessionHeadChunk(filePath, maxBytes);
+    if (!chunk)
+        return '';
+    let content = chunk.content;
+    if (!chunk.sawEof) {
+        // Didn't reach EOF: the last line in this chunk may be a partial write
+        // of a longer record. Keep only whole lines.
+        const lastNl = content.lastIndexOf('\n');
+        content = lastNl >= 0 ? content.slice(0, lastNl) : '';
+    }
+    return content;
+}
+/**
+ * Hard ceiling on how far {@link readSessionHeadContentBounded} will read
+ * looking for the opening record's closing newline. A JSONL record is one
+ * line, so a user turn that embeds a multi-megabyte image (base64, inline in
+ * the same `"data": "..."` string) can push that line's own terminator
+ * arbitrarily far past the plain {@link DEFAULT_HEAD_MAX_BYTES} chunk — this
+ * is the point past which the record is treated as unrecoverable (`partial`),
+ * never guessed at from a truncated fragment.
+ */
+const HEAD_ELISION_MAX_READ_BYTES = 4 * 1024 * 1024;
+/** Keep at most this many UTF-16 units of any single JSON string value
+ * verbatim; the remainder is replaced with a short marker. Bounds the ELIDED
+ * OUTPUT size independent of how large the source string (an image's base64
+ * payload can be tens of megabytes) actually is, while staying far larger
+ * than any real first-turn text block ever needs to be. */
+const HEAD_ELISION_STRING_KEEP_UNITS = 2048;
+/** Wall-clock ceiling on the elision scan itself. The scan runs over data
+ * already bounded by {@link HEAD_ELISION_MAX_READ_BYTES} and does O(1) work
+ * per character, so this should never trip in practice — it exists as a
+ * defense-in-depth budget, not the primary bound. */
+const HEAD_ELISION_MAX_MS = 200;
+/** How many characters the elision scan advances between wall-clock checks —
+ * frequent enough that the time budget above is actually honored, infrequent
+ * enough that `Date.now()` isn't on the hot path of every character. */
+const HEAD_ELISION_TIME_CHECK_MASK = 0x3ffff; // every ~262k chars
+/**
+ * A single-pass, JSON-string-aware elision scan: copies `input` verbatim
+ * except inside a string literal whose content exceeds
+ * {@link HEAD_ELISION_STRING_KEEP_UNITS}, where it keeps a short prefix and
+ * splices in a `…[elided N chars]` marker for the rest — but still tracks
+ * escape/quote state through to that string's real closing quote, so
+ * surrounding JSON structure (a text block that follows an oversized image
+ * block in the same content array) stays syntactically valid. This is a
+ * generic JSON-string eliser, not an image-specific one: it does not care
+ * WHAT is inside the oversized string, only that it is too large to keep.
+ *
+ * `deadlineMs` is an absolute `Date.now()` value. `truncatedByBudget: true`
+ * means the scan did not finish (ran out of time) — critically, the output
+ * up to that point NEVER includes the unflushed tail of a string that had
+ * already crossed the elision threshold (the flush happens once, the moment
+ * the threshold is crossed, not at the closing quote), so a cutoff mid-scan
+ * can never smuggle megabytes of un-elided content into the result.
+ */
+function elideOversizedJsonStrings(input, deadlineMs) {
+    const outParts = [];
+    let spanStart = 0;
+    let inString = false;
+    let escaped = false;
+    let stringStart = 0;
+    let skipping = false; // current string already crossed the keep threshold
+    const n = input.length;
+    for (let i = 0; i < n; i++) {
+        if ((i & HEAD_ELISION_TIME_CHECK_MASK) === 0 && Date.now() > deadlineMs) {
+            if (!skipping)
+                outParts.push(input.slice(spanStart, i));
+            return { text: outParts.join(''), truncatedByBudget: true };
+        }
+        const ch = input.charCodeAt(i);
+        if (!inString) {
+            if (ch === 0x22 /* '"' */) {
+                inString = true;
+                stringStart = i + 1;
+                skipping = false;
+            }
+            continue;
+        }
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (ch === 0x5c /* '\\' */) {
+            escaped = true;
+            continue;
+        }
+        if (ch === 0x22 /* '"' */) {
+            inString = false;
+            if (skipping) {
+                const elidedUnits = i - stringStart - HEAD_ELISION_STRING_KEEP_UNITS;
+                outParts.push(`…[elided ${elidedUnits} chars]`);
+                spanStart = i; // resume normal copying AT the closing quote
+                skipping = false; // the string is closed; the final flush must still emit the record's own tail ("}\n) even when this was the last string literal
+            }
+            continue;
+        }
+        if (!skipping && (i - stringStart) === HEAD_ELISION_STRING_KEEP_UNITS) {
+            outParts.push(input.slice(spanStart, i)); // flush the kept prefix now
+            skipping = true;
+        }
+    }
+    if (!skipping)
+        outParts.push(input.slice(spanStart, n));
+    return { text: outParts.join(''), truncatedByBudget: false };
+}
+/**
+ * Recover the transcript's opening JSONL record even when it doesn't fit the
+ * plain {@link DEFAULT_HEAD_MAX_BYTES} chunk — the case a first turn carrying
+ * a multi-megabyte inline image produces, where the record's own closing
+ * newline sits past whatever small chunk was read, so the old bare head
+ * reader dropped the WHOLE record (and with it, the real original request)
+ * rather than the oversized value inside it.
+ *
+ * Only invoked when the cheap path already failed to find a complete line
+ * (bounded — see {@link readSessionHeadChunk}'s `sawEof`), so an ordinary
+ * transcript never pays this cost. Reads up to {@link HEAD_ELISION_MAX_READ_BYTES}
+ * from byte 0, runs it through {@link elideOversizedJsonStrings} (bounded by
+ * {@link HEAD_ELISION_MAX_MS}), and returns the first complete elided line —
+ * text before and after the oversized value is preserved verbatim (only the
+ * oversized value itself is shortened), UTF-8 decoding and escape handling
+ * both go through the exact same path an unelided record would. Returns ''
+ * (a partial result, not a guess) when the scan is cut off by either budget
+ * before a complete line was ever produced — never a followup/tail turn
+ * substituted for it.
+ */
+export function readSessionHeadContentBounded(filePath, maxReadBytes = HEAD_ELISION_MAX_READ_BYTES) {
+    const chunk = readSessionHeadChunk(filePath, maxReadBytes);
+    if (!chunk || !chunk.content)
+        return '';
+    const { text, truncatedByBudget } = elideOversizedJsonStrings(chunk.content, Date.now() + HEAD_ELISION_MAX_MS);
+    const firstNl = text.indexOf('\n');
+    if (firstNl >= 0)
+        return text.slice(0, firstNl);
+    // No line terminator found anywhere in the elided text: either the record
+    // (minus its oversized values) is STILL bigger than the read budget, or the
+    // elision scan itself hit its time budget first, or we reached real EOF
+    // with no trailing newline at all (a truncated/interrupted write).
+    if (truncatedByBudget)
+        return '';
+    return chunk.sawEof ? text : '';
+}
+/**
+ * Read the FIRST `maxEvents` normalized events from a JSONL transcript's
+ * head — the session's actual opening turns, bounded and cheap (one small
+ * read from byte 0, the same shared Claude/Codex content parsers `readSessionTail`
+ * uses, zero duplicated parse logic). Only Claude and Codex are supported,
+ * matching {@link readSessionTailWithRaw}; other agents return no events.
+ *
+ * When the plain bounded chunk holds no complete first line at all — an
+ * opening user turn embedding a multi-megabyte inline image is the real case
+ * this covers — falls back to {@link readSessionHeadContentBounded}'s
+ * JSON-aware elision scan rather than returning nothing: the same content
+ * parsers then see a syntactically valid record with the oversized value
+ * shortened, so a text block before or after an elided image block is
+ * recovered exactly as if the image had never been oversized (the parser's
+ * own image-handling path, e.g. Claude's `normalizedAttachmentEvent`, still
+ * runs — it just sees a short placeholder `source.data` instead of the real
+ * payload, so an attachment's derived byte size is not meaningful when this
+ * fallback fired, only the surrounding TEXT is trustworthy).
+ */
+export function readSessionHead(filePath, agent, maxBytes = DEFAULT_HEAD_MAX_BYTES, maxEvents = DEFAULT_MAX_EVENTS) {
+    if (agent !== 'claude' && agent !== 'codex')
+        return [];
+    let content = readSessionHeadContent(filePath, maxBytes);
+    if (!content.trim())
+        content = readSessionHeadContentBounded(filePath);
+    if (!content.trim())
+        return [];
+    const events = agent === 'codex' ? parseCodexContent(content) : parseClaudeContent(content);
+    sanitizeEvents(events);
+    return events.length > maxEvents ? events.slice(0, maxEvents) : events;
+}

package/dist/lib/sessions-client.js

@@ -70,12 +70,9 @@ const ENGINE_VERBS = new Set([
     'tail',
     'watch',
     'preview',
-    'attach',
     'focus',
     'render',
     'stats',
-    'go',
-    'reconnect',
     'migrations',
     'export',
 ]);

package/dist/lib/setup-tool-install.d.ts

@@ -0,0 +1,3 @@
+import { type SetupTool } from './setup-tool-status.js';
+/** Use the host installer; setup must not install or start a tool from a read. */
+export declare function installSetupTool(tool: Exclude<SetupTool, 'secrets'>): Promise<boolean>;

package/dist/lib/setup-tool-install.js

@@ -0,0 +1,27 @@
+import { installCli, resolveCliManifest } from './cli-resources.js';
+import { getCachedToolSetup, refreshToolSetup } from './setup-tool-status.js';
+const PACKAGES = {
+    browser: '@phnx-labs/browser-cli@0.1.5',
+    computer: '@phnx-labs/computer-cli@0.1.5',
+    term: '@phnx-labs/term-cli@0.1.0',
+};
+/** Use the host installer; setup must not install or start a tool from a read. */
+export async function installSetupTool(tool) {
+    if (getCachedToolSetup().find((row) => row.tool === tool)?.installed)
+        return true;
+    const manifest = resolveCliManifest(tool) ?? {
+        name: tool,
+        check: { kind: 'which', cmd: tool },
+        install: [{ npm: PACKAGES[tool] }],
+        source: 'builtin',
+        path: '',
+    };
+    const result = installCli(manifest);
+    if (result.error)
+        console.error(result.error);
+    const rows = await refreshToolSetup(tool);
+    const installed = rows[0]?.installed === true;
+    if (!installed && !result.error)
+        console.error(`${tool} installation did not produce a standalone executable on PATH.`);
+    return result.installed && installed;
+}

package/dist/lib/setup-tool-status.d.ts

@@ -0,0 +1,22 @@
+export declare const SETUP_TOOLS: readonly ["browser", "computer", "secrets", "term"];
+export type SetupTool = typeof SETUP_TOOLS[number];
+export interface ToolSetupRow {
+    tool: SetupTool;
+    installed: boolean | null;
+    executable?: string;
+    version?: string;
+    readiness: 'ready' | 'needs-setup' | 'permission-required' | 'stopped' | 'unsupported' | 'unknown';
+    detail: string;
+    checkedAtMs: number | null;
+}
+export interface ToolSetupOptions {
+    cacheDir?: string;
+}
+export declare function toolSetupCacheDir(options?: ToolSetupOptions): string;
+/** Presence is metadata; health is the last explicit check, never a timer probe. */
+export declare function getCachedToolSetup(options?: ToolSetupOptions): ToolSetupRow[];
+export declare function toolReadiness(tool: SetupTool, status: unknown): Pick<ToolSetupRow, 'readiness' | 'detail'>;
+/** A shared disk lock coalesces overlapping requests from separate CLI clients. */
+export declare function refreshToolSetup(tool?: SetupTool | 'all', options?: ToolSetupOptions): Promise<ToolSetupRow[]>;
+/** File notifications are shared by the daemon collector; no background probes. */
+export declare function subscribeToolSetup(listener: (rows: ToolSetupRow[]) => void, options?: ToolSetupOptions): () => void;

package/dist/lib/setup-tool-status.js

@@ -0,0 +1,220 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { findInPath } from './agent-spec/agents.js';
+import { getCacheDir, getDeviceMetaPath, getHelpersDir, getUserAgentsDir } from './state.js';
+import { atomicWriteJsonSync, withFileLockAsync } from './fs-atomic.js';
+import { probeCapture } from './probe.js';
+import { invocation, isStandaloneComputer } from './computer-client.js';
+import { getSocketPath as browserSocketPath } from './browser/ipc.js';
+export const SETUP_TOOLS = ['browser', 'computer', 'secrets', 'term'];
+export function toolSetupCacheDir(options = {}) {
+    return path.join(options.cacheDir ?? getCacheDir(), 'setup-tools');
+}
+function cachePath(tool, options) {
+    return path.join(toolSetupCacheDir(options), `${tool}.json`);
+}
+function setupInputs(tool) {
+    const inputs = [path.join(getUserAgentsDir(), 'agents.yaml'), getDeviceMetaPath()];
+    if (tool === 'browser')
+        inputs.push(browserSocketPath());
+    if (tool === 'computer')
+        inputs.push(process.env.COMPUTER_HELPER_SOCKET || path.join(getHelpersDir(), 'computer.sock'));
+    return inputs;
+}
+function inputStamp(tool) {
+    return setupInputs(tool).map((file) => {
+        try {
+            const stat = fs.statSync(file);
+            return `${file}:${stat.ino}:${stat.mtimeMs}:${stat.size}`;
+        }
+        catch {
+            return `${file}:missing`;
+        }
+    }).join('|');
+}
+function binaryMetadata(tool) {
+    const empty = { tool, installed: false, readiness: 'needs-setup', detail: 'CLI is not installed.', checkedAtMs: null };
+    try {
+        const explicit = process.env[`${tool.toUpperCase()}_BIN`]?.trim();
+        const accept = (candidate) => {
+            if (tool === 'computer')
+                return isStandaloneComputer(candidate);
+            if (tool === 'browser') {
+                try {
+                    return !fs.realpathSync(candidate).endsWith(path.join('dist', 'browser.js'));
+                }
+                catch {
+                    return false;
+                }
+            }
+            return true;
+        };
+        let executable = explicit ? (accept(explicit) ? explicit : null) : findInPath(tool, { accept });
+        if (!executable)
+            return { row: empty, fingerprint: 'missing' };
+        if (/\.(cmd|ps1)$/i.test(executable)) {
+            const packageDir = path.join(path.dirname(executable), 'node_modules', '@phnx-labs', `${tool}-cli`);
+            const pkg = JSON.parse(fs.readFileSync(path.join(packageDir, 'package.json'), 'utf8'));
+            const entry = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.[tool];
+            if (pkg.name !== `@phnx-labs/${tool}-cli` || typeof entry !== 'string')
+                throw new Error('unrecognized npm launcher');
+            const resolved = path.resolve(packageDir, entry);
+            if (!resolved.startsWith(`${path.resolve(packageDir)}${path.sep}`))
+                throw new Error('invalid npm entrypoint');
+            executable = resolved;
+        }
+        fs.accessSync(executable, process.platform === 'win32' || /\.[cm]?js$/i.test(executable) ? fs.constants.R_OK : fs.constants.X_OK);
+        const real = fs.realpathSync(executable);
+        const stat = fs.statSync(real);
+        if (!stat.isFile())
+            throw new Error('not a file');
+        let version;
+        let dir = path.dirname(real);
+        for (let depth = 0; depth < 5; depth++) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+                if (pkg.name === `@phnx-labs/${tool}-cli` && typeof pkg.version === 'string') {
+                    version = pkg.version;
+                    break;
+                }
+            }
+            catch { /* Executables need not be npm packages. */ }
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        return {
+            fingerprint: `${real}:${stat.size}:${stat.mtimeMs}:${version ?? ''}|${inputStamp(tool)}`,
+            row: { tool, installed: true, executable, version, readiness: 'unknown', detail: 'Installed. Health has not been checked.', checkedAtMs: null },
+        };
+    }
+    catch {
+        return { fingerprint: 'unavailable', row: { ...empty, installed: null, readiness: 'unknown', detail: 'Executable could not be inspected.' } };
+    }
+}
+function readCache(tool, options) {
+    try {
+        const cached = JSON.parse(fs.readFileSync(cachePath(tool, options), 'utf8'));
+        if (cached.v === 1 && cached.row?.tool === tool && typeof cached.fingerprint === 'string')
+            return cached;
+    }
+    catch { /* No health result yet. */ }
+    return null;
+}
+/** Presence is metadata; health is the last explicit check, never a timer probe. */
+export function getCachedToolSetup(options = {}) {
+    return SETUP_TOOLS.map((tool) => {
+        const { row, fingerprint } = binaryMetadata(tool);
+        const cached = readCache(tool, options);
+        return cached?.fingerprint === fingerprint ? { ...cached.row, executable: row.executable, version: row.version } : row;
+    });
+}
+export function toolReadiness(tool, status) {
+    if (!status || typeof status !== 'object')
+        return { readiness: 'unknown', detail: 'The CLI returned an unreadable health result.' };
+    const value = status;
+    if (tool === 'computer') {
+        if (value.installed === false)
+            return { readiness: 'needs-setup', detail: 'CLI installed; computer helper needs setup.' };
+        if (value.running === true && value.trusted === true)
+            return { readiness: 'ready', detail: 'Helper is running and Accessibility is granted. Screen Recording is checked when capturing.' };
+        if (value.running === true && value.trusted === false)
+            return { readiness: 'permission-required', detail: 'Grant Accessibility to Agents Computer in System Settings.' };
+        if (value.running === false)
+            return { readiness: 'stopped', detail: 'Computer helper is stopped or unreachable.' };
+    }
+    if (tool === 'browser') {
+        if (value.running === true)
+            return { readiness: 'ready', detail: 'Browser service is running.' };
+        if (value.running === false)
+            return { readiness: 'stopped', detail: 'Browser service is stopped.' };
+    }
+    return { readiness: 'unknown', detail: typeof value.error === 'string' && value.error.trim() ? value.error.slice(0, 500) : 'The CLI did not report a recognized health state.' };
+}
+async function checkTool(row) {
+    if (!row.installed || !row.executable)
+        return { ...row, checkedAtMs: Date.now() };
+    // The standalone has no non-interactive health JSON. Do not list bundles or
+    // unlock the broker merely to paint a settings row.
+    if (row.tool === 'secrets')
+        return { ...row, checkedAtMs: Date.now(), detail: 'Installed. Secret access is checked when used; this check does not unlock secrets.' };
+    // term is a headless PTY engine with no `status --json` health surface; it is
+    // spawned on demand by the OAuth device-code driver (fleet login / auth mint).
+    // Presence on PATH is the whole readiness signal — do not probe it.
+    if (row.tool === 'term')
+        return { ...row, readiness: 'ready', detail: 'Installed. Spawned on demand by fleet login and auth mint.', checkedAtMs: Date.now() };
+    try {
+        const { command, prefix } = invocation(row.executable);
+        const { stdout } = await probeCapture(command, [...prefix, 'status', '--json'], 8000, { acceptedExitCodes: [0, 1], maxOutputBytes: 256 * 1024 });
+        return { ...row, ...toolReadiness(row.tool, JSON.parse(stdout)), checkedAtMs: Date.now() };
+    }
+    catch {
+        return { ...row, readiness: 'unknown', detail: 'Health check failed or timed out. Check again to retry.', checkedAtMs: Date.now() };
+    }
+}
+/** A shared disk lock coalesces overlapping requests from separate CLI clients. */
+export async function refreshToolSetup(tool = 'all', options = {}) {
+    const requestedAt = Date.now();
+    const dir = toolSetupCacheDir(options);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    for (const selected of tool === 'all' ? SETUP_TOOLS : [tool]) {
+        const file = cachePath(selected, options);
+        await withFileLockAsync(file, async () => {
+            const metadata = binaryMetadata(selected);
+            const cached = readCache(selected, options);
+            if (cached?.fingerprint === metadata.fingerprint && (cached.row.checkedAtMs ?? 0) >= requestedAt)
+                return;
+            const row = await checkTool(metadata.row);
+            atomicWriteJsonSync(file, { v: 1, fingerprint: metadata.fingerprint, row });
+        }, { realpath: false, acquireTimeoutMs: 20_000 });
+    }
+    return getCachedToolSetup(options).filter((row) => tool === 'all' || row.tool === tool);
+}
+/** File notifications are shared by the daemon collector; no background probes. */
+export function subscribeToolSetup(listener, options = {}) {
+    const dir = toolSetupCacheDir(options);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const paths = new Set([dir, ...(process.env.PATH ?? '').split(path.delimiter).filter(Boolean)]);
+    for (const tool of SETUP_TOOLS)
+        for (const input of setupInputs(tool))
+            paths.add(path.dirname(input));
+    for (const row of getCachedToolSetup(options)) {
+        if (row.executable) {
+            paths.add(path.dirname(row.executable));
+            try {
+                paths.add(path.dirname(fs.realpathSync(row.executable)));
+            }
+            catch { /* Removed since discovery. */ }
+        }
+    }
+    let previous = JSON.stringify(getCachedToolSetup(options));
+    let debounce;
+    const changed = () => {
+        if (debounce)
+            return;
+        debounce = setTimeout(() => {
+            debounce = undefined;
+            const rows = getCachedToolSetup(options);
+            const next = JSON.stringify(rows);
+            if (next !== previous) {
+                previous = next;
+                listener(rows);
+            }
+        }, 150);
+        debounce.unref();
+    };
+    const watchers = [];
+    for (const target of paths) {
+        try {
+            const watcher = fs.watch(target, { persistent: false }, changed);
+            watcher.on('error', changed);
+            watchers.push(watcher);
+        }
+        catch { /* Absent PATH entries have no executable to report. */ }
+    }
+    changed();
+    return () => { if (debounce)
+        clearTimeout(debounce); for (const watcher of watchers)
+        watcher.close(); };
+}

package/dist/lib/share-runtime.d.ts

@@ -0,0 +1,11 @@
+/** Best-effort runtime env for spawned agents. Never throws AND never prompts.
+ *
+ * Auto-injecting the share write token on every `agents run` is a background
+ * convenience, NOT a user-initiated secret access — so it MUST NOT raise a Touch
+ * ID sheet (SEC-13: an agent launch never pops biometry on its own). The read is
+ * always `agentOnly`: it resolves the token only from the injected env or an
+ * already-held / no-ACL bundle, and silently returns undefined otherwise (the
+ * agent can still publish via its own `artifacts share` credentials). For
+ * zero-friction auto-share with no prompt: unlock once (`agents secrets unlock
+ * share`) or make it no-ACL (`agents secrets policy share never`). */
+export declare function shareRuntimeEnv(): Record<string, string> | undefined;

package/dist/lib/share-runtime.js

@@ -0,0 +1,63 @@
+// Runtime share-token injection for spawned agents.
+//
+// The artifact share ENGINE moved to `@phnx-labs/artifacts-cli` (PHNX-3992);
+// agents-cli no longer publishes artifacts itself. What stays here is the thin
+// glue that lets a dispatched agent inherit the operator's BYO write token so
+// its own `artifacts share` can publish headlessly: `run`/`teams`/`cloud`
+// dispatch call `shareRuntimeEnv()` and forward the result into the agent env.
+// artifacts-cli honors the same `SHARE_WRITE_TOKEN` variable, so the injection
+// contract is unchanged by the extraction.
+//
+// The endpoint config still lives in `agents.yaml` under `share:` (Meta.share)
+// so a previously-provisioned BYO endpoint keeps syncing fleet-wide; the raw
+// write token lives in the keychain-backed `share` secrets bundle, never on disk.
+import { readMeta } from './state.js';
+import { bundleExistsSync as bundleExists, readAndResolveBundleEnvSync as readAndResolveBundleEnv, } from './secrets-client.js';
+const SHARE_BUNDLE = 'share';
+const SHARE_TOKEN_KEY = 'WRITE_TOKEN';
+const SHARE_TOKEN_ENV_KEY = 'SHARE_WRITE_TOKEN';
+/** Trim; empty / whitespace-only strings are absent. */
+function nonempty(v) {
+    const t = v?.trim();
+    return t ? t : undefined;
+}
+/** Whether a BYO share endpoint is still configured in `agents.yaml`. */
+function hasShareEndpoint() {
+    return !!nonempty(readMeta().share?.baseUrl);
+}
+/** The write token as injected ephemerally into fleet/cloud agents. */
+function readWriteTokenEnv(env = process.env) {
+    const token = env[SHARE_TOKEN_ENV_KEY]?.trim();
+    return token ? token : null;
+}
+/** Best-effort runtime env for spawned agents. Never throws AND never prompts.
+ *
+ * Auto-injecting the share write token on every `agents run` is a background
+ * convenience, NOT a user-initiated secret access — so it MUST NOT raise a Touch
+ * ID sheet (SEC-13: an agent launch never pops biometry on its own). The read is
+ * always `agentOnly`: it resolves the token only from the injected env or an
+ * already-held / no-ACL bundle, and silently returns undefined otherwise (the
+ * agent can still publish via its own `artifacts share` credentials). For
+ * zero-friction auto-share with no prompt: unlock once (`agents secrets unlock
+ * share`) or make it no-ACL (`agents secrets policy share never`). */
+export function shareRuntimeEnv() {
+    if (!hasShareEndpoint())
+        return undefined;
+    const fromEnv = readWriteTokenEnv();
+    if (fromEnv)
+        return { [SHARE_TOKEN_ENV_KEY]: fromEnv };
+    try {
+        if (!bundleExists(SHARE_BUNDLE))
+            return undefined;
+        const { env } = readAndResolveBundleEnv(SHARE_BUNDLE, {
+            caller: 'share',
+            keys: [SHARE_TOKEN_KEY],
+            agentOnly: true, // never raise a Touch ID sheet on an agent launch (SEC-13)
+        });
+        const token = env[SHARE_TOKEN_KEY];
+        return token ? { [SHARE_TOKEN_ENV_KEY]: token } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/lib/signin-badge.d.ts

@@ -6,15 +6,30 @@ export type AccountProvisioning = 'portable' | 'per-device';
 /**
  * The exact command that logs a given agent in — for warn banners and nudges.
  * Driven off the registry `cliCommand` with the per-agent subcommand overrides
- * (verified against the real CLIs): codex/grok use `<cli> login`, opencode uses
- * `<cli> auth login`, claude logs in from inside its TUI via `/login`, and the
- * remaining agents (kimi, gemini, …) start their device/oauth flow on launch.
+ * (verified against the real CLIs): codex/grok/opencode run the finite login
+ * subcommand `HARNESS_AUTH` wires (`loginSubcommand`), claude logs in from
+ * inside its TUI via `/login`, and the remaining agents (kimi, gemini, …) start
+ * their device/oauth flow on launch.
  */
 export declare function loginHint(agentId: AgentId): string;
+/**
+ * Harnesses that log back in through a finite native subcommand runnable via
+ * `agents run <agent>@<version> -- <args>`. Claude logs in from inside its TUI
+ * (`/login`); cursor and the rest start their device/oauth flow on launch.
+ */
+export declare const SUBCOMMAND_LOGIN_AGENTS: readonly AgentId[];
+/**
+ * The finite native login subcommand (`login`, `login --device-auth`,
+ * `auth login`) for a {@link SUBCOMMAND_LOGIN_AGENTS} harness, read from the one
+ * `HARNESS_AUTH` row so every surface that spells it — the hint, the per-version
+ * fix, `agents doctor` — agrees. Null for every other harness.
+ */
+export declare function loginSubcommand(agent: AgentId): string | null;
 /**
  * Exact action shown beside a non-live account. Every emitted command exists
  * today — never a planned surface and never a hidden verb:
- * - Per-device harnesses repair per box via `agents devices login`.
+ * - Per-device harnesses (kimi/antigravity) repair on the box itself: run the
+ *   harness there (`loginHint`) and complete its native login.
  * - Named accounts re-auth through `agents accounts login <harness>#<name>`.
  *   A known account with no slot on a headed device is onboarded with
  *   `agents accounts add <harness> <name>`. A worker never runs an