@phnx-labs/agents-cli 1.20.4 → 1.20.6

package/dist/lib/secrets/install-helper.js

@@ -14,14 +14,23 @@
  */
 import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
+import { createHash } from 'crypto';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 const APP_BUNDLE_NAME = 'Agents CLI.app';
 const INSTALL_DIR_NAME = 'agents-cli';
+let installRootOverride = null;
+/** Redirect the install root (test only). Returns the previous override so callers can restore. */
+export function setInstallRootForTest(dir) {
+    const prev = installRootOverride;
+    installRootOverride = dir;
+    return prev;
+}
 /** Absolute path to the installed `.app` bundle directory (not the executable). */
 function installedAppPath() {
-    return path.join(os.homedir(), 'Library', 'Application Support', INSTALL_DIR_NAME, APP_BUNDLE_NAME);
+    const root = installRootOverride ?? os.homedir();
+    return path.join(root, 'Library', 'Application Support', INSTALL_DIR_NAME, APP_BUNDLE_NAME);
 }
 /** Absolute path to the executable inside the installed `.app` bundle. */
 function installedExecutablePath() {
@@ -57,6 +66,33 @@ function assertDarwin() {
         throw new Error('Keychain helper is macOS only.');
     }
 }
+function sha256File(filePath) {
+    return createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+/**
+ * True when the installed helper executable differs byte-for-byte from the
+ * bundled source helper. A stale-but-validly-signed helper is exactly how the
+ * broken 1.20.4 build (signed, but missing the keychain-access-groups
+ * entitlement) survived upgrades: codesign --verify passes on it, so the
+ * "exists and verifies" early-return kept it installed forever. Returns false
+ * when there is no bundled source to compare against (dev installs) or no
+ * installed copy yet — both cases are decided by the existence checks in the
+ * callers, not by staleness.
+ */
+function installedHelperIsStale() {
+    let srcApp;
+    try {
+        srcApp = sourceAppPath();
+    }
+    catch {
+        return false;
+    }
+    const srcExec = path.join(srcApp, 'Contents', 'MacOS', 'Agents CLI');
+    const destExec = installedExecutablePath();
+    if (!fs.existsSync(srcExec) || !fs.existsSync(destExec))
+        return false;
+    return sha256File(srcExec) !== sha256File(destExec);
+}
 function codesignVerify(appPath) {
     const r = spawnSync('codesign', ['--verify', '--deep', '--strict', appPath], {
         stdio: ['ignore', 'pipe', 'pipe'],
@@ -86,8 +122,10 @@ function copyAppBundle(src, dest) {
 }
 /**
  * Idempotent install. Copies the bundled `.app` to the stable user path. Skips
- * if the destination already exists and `codesign --verify` passes, unless
- * `forceReinstall=true`.
+ * if the destination already exists, `codesign --verify` passes, AND the
+ * installed executable matches the bundled one byte-for-byte — a valid
+ * signature alone is not enough, because an outdated helper signs clean too.
+ * `forceReinstall=true` skips all checks and always copies.
  *
  * Notarization is checked via `spctl --assess` after install — a failure is
  * logged as a warning but does NOT throw. Notarization checks require network
@@ -99,7 +137,7 @@ export function ensureKeychainHelperInstalled(opts = {}) {
     const dest = installedAppPath();
     if (!opts.forceReinstall && fs.existsSync(dest)) {
         const { ok } = codesignVerify(dest);
-        if (ok)
+        if (ok && !installedHelperIsStale())
             return;
     }
     const src = sourceAppPath();
@@ -119,14 +157,18 @@ export function ensureKeychainHelperInstalled(opts = {}) {
 }
 /**
  * Return the absolute path to the helper executable. If the installed bundle
- * is missing, performs a lazy install first.
+ * is missing, or is stale relative to the bundled source helper, performs a
+ * lazy (re)install first. The staleness check is what lets an upgraded CLI
+ * replace a helper a previous version installed — `agents helper install`
+ * never runs on `npm i -g`, so this call site is the only one every machine
+ * is guaranteed to pass through.
  *
  * Throws on non-darwin.
  */
 export function getKeychainHelperPath() {
     assertDarwin();
     const exec = installedExecutablePath();
-    if (!fs.existsSync(exec)) {
+    if (!fs.existsSync(exec) || installedHelperIsStale()) {
         ensureKeychainHelperInstalled();
     }
     return exec;

package/dist/lib/secrets/linux.d.ts

@@ -1,27 +1,74 @@
 /**
  * Linux secret storage via libsecret (GNOME Keyring / Secret Service API).
  *
- * Uses `secret-tool` CLI which is part of libsecret-tools package.
- * On Ubuntu: apt install libsecret-tools
+ * Primary backend: `secret-tool` CLI (libsecret-tools package).
  *
- * Secrets are stored with:
+ * Headless fallback: when the default Secret Service collection is locked
+ * (common on server-class Linux — no graphical login means the keyring
+ * passphrase never enters the daemon, so `secret-tool store` fails with
+ * "Cannot create an item in a locked collection"), we transparently switch
+ * to a file-based AES-256-GCM encrypted store under
+ * `~/.agents/.cache/secrets/`. The encryption key is scrypt-derived from a
+ * passphrase read from `AGENTS_SECRETS_PASSPHRASE` (preferred) or a TTY
+ * prompt. The decision is cached per process; one stderr line is emitted
+ * the first time the fallback activates.
+ *
+ * Secrets stored via secret-tool use:
  *   service = "agents-cli"
  *   account = username
- *   item = the secret identifier
+ *   item    = the secret identifier
+ *
+ * File-fallback layout: one `<item>.enc` JSON file per item, mode 0600.
  */
 import type { KeychainBackend } from './index.js';
-/**
- * secret-tool lookup attributes:
- *   service=agents-cli account=<user> item=<itemName>
- */
+/** Encrypted-file on-disk shape. Exported for tests. */
+export interface EncFile {
+    salt: string;
+    iv: string;
+    authTag: string;
+    ciphertext: string;
+}
+/** Encrypt plaintext under a passphrase using AES-256-GCM with a random
+ *  scrypt salt and a random 96-bit IV. Exported for tests. */
+export declare function encryptForFallback(plaintext: string, passphrase: string): EncFile;
+/** Decrypt an EncFile under a passphrase. Throws on wrong key or tampered
+ *  ciphertext (auth-tag mismatch). Exported for tests. */
+export declare function decryptForFallback(enc: EncFile, passphrase: string): string;
+/** File-only KeychainBackend (exported for tests; the public surface uses
+ *  the secret-tool-with-fallback `linuxBackend` below). */
+export declare const fileBackend: KeychainBackend;
+/** secret-tool lookup attributes:
+ *   service=agents-cli account=<user> item=<itemName> */
 export declare function hasSecretToolToken(item: string): boolean;
 export declare function getSecretToolToken(item: string): string;
 export declare function setSecretToolToken(item: string, value: string): void;
 export declare function deleteSecretToolToken(item: string): boolean;
+/**
+ * Parse the item names out of `secret-tool search --all` output, keeping only
+ * those starting with `prefix`. Exported for tests.
+ *
+ * `output` must be the combined stdout+stderr of the search: libsecret splits
+ * the dump across both streams — the value/label/schema lines go to stdout
+ * while the `attribute.*` lines (which carry `attribute.item`, the only place
+ * the item name is reliably machine-readable) go to stderr (observed on
+ * libsecret 0.21.4). Which stream each line lands on has varied across
+ * libsecret versions, so callers concatenate both rather than bet on one.
+ */
+export declare function parseSecretToolItems(output: string, prefix: string): string[];
 /**
  * List secrets by prefix. secret-tool doesn't have a list command,
  * so we use secret-tool search which outputs in a specific format.
  */
 export declare function listSecretToolItems(prefix: string): string[];
-/** KeychainBackend implementation for Linux using secret-tool */
+/** KeychainBackend implementation for Linux. Routes through secret-tool
+ *  with a transparent encrypted-file fallback when the default Secret
+ *  Service collection is locked (or libsecret-tools is not installed but
+ *  AGENTS_SECRETS_PASSPHRASE is set). */
 export declare const linuxBackend: KeychainBackend;
+/** Test-only: reset module state so independent test cases don't bleed
+ *  passphrase / fallback decisions across each other. */
+export declare function _resetForTest(opts?: {
+    fileDir?: string | null;
+    forceFileFallback?: boolean;
+    passphrase?: string | null;
+}): void;

package/dist/lib/secrets/linux.js

@@ -1,17 +1,32 @@
 /**
  * Linux secret storage via libsecret (GNOME Keyring / Secret Service API).
  *
- * Uses `secret-tool` CLI which is part of libsecret-tools package.
- * On Ubuntu: apt install libsecret-tools
+ * Primary backend: `secret-tool` CLI (libsecret-tools package).
  *
- * Secrets are stored with:
+ * Headless fallback: when the default Secret Service collection is locked
+ * (common on server-class Linux — no graphical login means the keyring
+ * passphrase never enters the daemon, so `secret-tool store` fails with
+ * "Cannot create an item in a locked collection"), we transparently switch
+ * to a file-based AES-256-GCM encrypted store under
+ * `~/.agents/.cache/secrets/`. The encryption key is scrypt-derived from a
+ * passphrase read from `AGENTS_SECRETS_PASSPHRASE` (preferred) or a TTY
+ * prompt. The decision is cached per process; one stderr line is emitted
+ * the first time the fallback activates.
+ *
+ * Secrets stored via secret-tool use:
  *   service = "agents-cli"
  *   account = username
- *   item = the secret identifier
+ *   item    = the secret identifier
+ *
+ * File-fallback layout: one `<item>.enc` JSON file per item, mode 0600.
  */
-import { spawnSync } from 'child_process';
+import { spawnSync, execSync } from 'child_process';
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'crypto';
+import * as fs from 'fs';
 import * as os from 'os';
+import * as path from 'path';
 const SERVICE = 'agents-cli';
+// ---------- secret-tool availability ----------
 function secretToolAvailable() {
     const result = spawnSync('which', ['secret-tool'], {
         stdio: ['ignore', 'pipe', 'pipe'],
@@ -20,111 +35,328 @@ function secretToolAvailable() {
 }
 let checkedAvailability = false;
 let isAvailable = false;
-function ensureSecretTool() {
+// ---------- file fallback state ----------
+let useFileFallback = false;
+let warnedFallback = false;
+let fileDirOverride = null;
+let cachedPassphrase = null;
+function fileDir() {
+    return fileDirOverride ?? path.join(os.homedir(), '.agents', '.cache', 'secrets');
+}
+function activateFileFallback() {
+    if (useFileFallback)
+        return;
+    useFileFallback = true;
+    if (!warnedFallback) {
+        warnedFallback = true;
+        process.stderr.write(`[agents] secret-service collection locked, using file-based store at ${fileDir()}\n`);
+    }
+}
+function isLockedCollectionError(stderr) {
+    return /locked collection/i.test(stderr) ||
+        /Prompt was dismissed/i.test(stderr);
+}
+/** True if the fallback dir has any committed encrypted items. Means an
+ *  earlier process (this one or another) already routed writes to the file
+ *  store, so this process must keep reading/writing from the same store —
+ *  otherwise `list` / `get` / `has` would silently miss them. */
+function fileFallbackPreviouslyActivated() {
+    try {
+        return fs.readdirSync(fileDir()).some((e) => e.endsWith('.enc'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Decide which backend a given op should use. Activates file fallback if
+ * `secret-tool` is missing and `AGENTS_SECRETS_PASSPHRASE` is set, OR if a
+ * previous run already committed to the file fallback (encrypted items on
+ * disk). The latter check is what makes the fallback persistent across the
+ * many short-lived `agents secrets ...` Node processes a user invokes.
+ */
+function preflight() {
+    if (useFileFallback)
+        return 'file';
+    if (fileFallbackPreviouslyActivated()) {
+        activateFileFallback();
+        return 'file';
+    }
     if (!checkedAvailability) {
         isAvailable = secretToolAvailable();
         checkedAvailability = true;
     }
     if (!isAvailable) {
+        if (process.env.AGENTS_SECRETS_PASSPHRASE) {
+            activateFileFallback();
+            return 'file';
+        }
         throw new Error('secret-tool not found. Install libsecret-tools:\n' +
             '  Ubuntu/Debian: sudo apt install libsecret-tools\n' +
             '  Fedora: sudo dnf install libsecret\n' +
-            '  Arch: sudo pacman -S libsecret');
+            '  Arch: sudo pacman -S libsecret\n' +
+            '\n' +
+            'Alternative: set AGENTS_SECRETS_PASSPHRASE to use the encrypted-file fallback.');
     }
+    return 'secret-tool';
 }
-/**
- * secret-tool lookup attributes:
- *   service=agents-cli account=<user> item=<itemName>
- */
+// ---------- passphrase ----------
+function readPassphraseFromTty() {
+    const fd = fs.openSync('/dev/tty', 'r+');
+    let echoDisabled = false;
+    try {
+        fs.writeSync(fd, 'Enter AGENTS_SECRETS_PASSPHRASE: ');
+        try {
+            execSync('stty -echo < /dev/tty', { stdio: 'ignore' });
+            echoDisabled = true;
+        }
+        catch {
+            // stty not available — fall through; passphrase will echo. Better
+            // than refusing to function.
+        }
+        let pass = '';
+        const buf = Buffer.alloc(1);
+        while (true) {
+            const n = fs.readSync(fd, buf, 0, 1, null);
+            if (n === 0)
+                break;
+            const ch = buf.toString('utf8', 0, n);
+            if (ch === '\n' || ch === '\r')
+                break;
+            pass += ch;
+        }
+        return pass;
+    }
+    finally {
+        if (echoDisabled) {
+            try {
+                execSync('stty echo < /dev/tty', { stdio: 'ignore' });
+            }
+            catch { /* best effort */ }
+        }
+        try {
+            fs.writeSync(fd, '\n');
+        }
+        catch { /* best effort */ }
+        fs.closeSync(fd);
+    }
+}
+function getPassphrase() {
+    if (cachedPassphrase !== null)
+        return cachedPassphrase;
+    const env = process.env.AGENTS_SECRETS_PASSPHRASE;
+    if (env && env.length > 0) {
+        cachedPassphrase = env;
+        return env;
+    }
+    if (!process.stdin.isTTY) {
+        throw new Error('Secret-service collection is locked and no AGENTS_SECRETS_PASSPHRASE is set.\n' +
+            'Set AGENTS_SECRETS_PASSPHRASE in your environment to use the encrypted-file fallback,\n' +
+            'or unlock the keyring (e.g. configure pam_gnome_keyring for SSH login).');
+    }
+    const p = readPassphraseFromTty();
+    if (!p)
+        throw new Error('No passphrase entered.');
+    cachedPassphrase = p;
+    return p;
+}
+function deriveKey(passphrase, salt) {
+    return scryptSync(passphrase, salt, 32);
+}
+/** Encrypt plaintext under a passphrase using AES-256-GCM with a random
+ *  scrypt salt and a random 96-bit IV. Exported for tests. */
+export function encryptForFallback(plaintext, passphrase) {
+    const salt = randomBytes(16);
+    const iv = randomBytes(12);
+    const key = deriveKey(passphrase, salt);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    return {
+        salt: salt.toString('hex'),
+        iv: iv.toString('hex'),
+        authTag: cipher.getAuthTag().toString('hex'),
+        ciphertext: ciphertext.toString('hex'),
+    };
+}
+/** Decrypt an EncFile under a passphrase. Throws on wrong key or tampered
+ *  ciphertext (auth-tag mismatch). Exported for tests. */
+export function decryptForFallback(enc, passphrase) {
+    const salt = Buffer.from(enc.salt, 'hex');
+    const iv = Buffer.from(enc.iv, 'hex');
+    const authTag = Buffer.from(enc.authTag, 'hex');
+    const ciphertext = Buffer.from(enc.ciphertext, 'hex');
+    const key = deriveKey(passphrase, salt);
+    const decipher = createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(authTag);
+    const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return plaintext.toString('utf8');
+}
+// ---------- file backend ----------
+function fileFor(item) {
+    return path.join(fileDir(), `${item}.enc`);
+}
+function ensureFileDir() {
+    fs.mkdirSync(fileDir(), { recursive: true, mode: 0o700 });
+}
+function fileHas(item) {
+    return fs.existsSync(fileFor(item));
+}
+function fileGet(item) {
+    const fp = fileFor(item);
+    if (!fs.existsSync(fp)) {
+        throw new Error(`Secret '${item}' not found in encrypted store.`);
+    }
+    const raw = fs.readFileSync(fp, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Encrypted secret file ${fp} is corrupt (not valid JSON).`);
+    }
+    try {
+        return decryptForFallback(parsed, getPassphrase());
+    }
+    catch {
+        throw new Error(`Failed to decrypt '${item}'. Wrong AGENTS_SECRETS_PASSPHRASE or tampered file.`);
+    }
+}
+function fileSet(item, value) {
+    ensureFileDir();
+    const enc = encryptForFallback(value, getPassphrase());
+    fs.writeFileSync(fileFor(item), JSON.stringify(enc), { mode: 0o600 });
+}
+function fileDelete(item) {
+    const fp = fileFor(item);
+    if (!fs.existsSync(fp))
+        return true; // idempotent, matches secret-tool clear
+    fs.unlinkSync(fp);
+    return true;
+}
+function fileList(prefix) {
+    const dir = fileDir();
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir)
+        .filter((f) => f.endsWith('.enc'))
+        .map((f) => f.slice(0, -'.enc'.length))
+        .filter((name) => name.startsWith(prefix));
+}
+/** File-only KeychainBackend (exported for tests; the public surface uses
+ *  the secret-tool-with-fallback `linuxBackend` below). */
+export const fileBackend = {
+    has: fileHas,
+    get: fileGet,
+    set: fileSet,
+    delete: fileDelete,
+    list: fileList,
+};
+// ---------- secret-tool ops with fallback ----------
+/** secret-tool lookup attributes:
+ *   service=agents-cli account=<user> item=<itemName> */
 export function hasSecretToolToken(item) {
-    ensureSecretTool();
+    if (preflight() === 'file')
+        return fileHas(item);
     const user = os.userInfo().username;
     const result = spawnSync('secret-tool', [
         'lookup',
         'service', SERVICE,
         'account', user,
         'item', item,
-    ], {
-        stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    return result.status === 0 && result.stdout?.toString().trim().length > 0;
+    ], { stdio: ['ignore', 'pipe', 'pipe'] });
+    if (result.status === 0) {
+        return result.stdout?.toString().trim().length > 0;
+    }
+    const stderr = result.stderr?.toString() ?? '';
+    if (isLockedCollectionError(stderr)) {
+        activateFileFallback();
+        return fileHas(item);
+    }
+    return false;
 }
 export function getSecretToolToken(item) {
-    ensureSecretTool();
+    if (preflight() === 'file')
+        return fileGet(item);
     const user = os.userInfo().username;
     const result = spawnSync('secret-tool', [
         'lookup',
         'service', SERVICE,
         'account', user,
         'item', item,
-    ], {
-        stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    if (result.status !== 0) {
-        throw new Error(`Secret '${item}' not found in keyring.`);
+    ], { stdio: ['ignore', 'pipe', 'pipe'] });
+    if (result.status === 0) {
+        const token = result.stdout?.toString().trim();
+        if (!token)
+            throw new Error(`Secret '${item}' exists but is empty.`);
+        return token;
     }
-    const token = result.stdout?.toString().trim();
-    if (!token) {
-        throw new Error(`Secret '${item}' exists but is empty.`);
+    const stderr = result.stderr?.toString() ?? '';
+    if (isLockedCollectionError(stderr)) {
+        activateFileFallback();
+        return fileGet(item);
     }
-    return token;
+    throw new Error(`Secret '${item}' not found in keyring.`);
 }
 export function setSecretToolToken(item, value) {
-    ensureSecretTool();
     if (!value || !value.trim())
         throw new Error('Secret value is empty.');
+    if (preflight() === 'file')
+        return fileSet(item, value);
     const user = os.userInfo().username;
     const label = `agents-cli: ${item}`;
-    // secret-tool store reads value from stdin
     const result = spawnSync('secret-tool', [
         'store',
         '--label', label,
         'service', SERVICE,
         'account', user,
         'item', item,
-    ], {
-        input: value,
-        stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    if (result.status !== 0) {
-        const stderr = result.stderr?.toString().trim();
-        throw new Error(`Failed to store secret '${item}': ${stderr || 'unknown error'}\n` +
-            'Make sure GNOME Keyring or another Secret Service provider is running.');
+    ], { input: value, stdio: ['pipe', 'pipe', 'pipe'] });
+    if (result.status === 0)
+        return;
+    const stderr = result.stderr?.toString().trim() ?? '';
+    if (isLockedCollectionError(stderr)) {
+        activateFileFallback();
+        fileSet(item, value);
+        return;
     }
+    throw new Error(`Failed to store secret '${item}': ${stderr || 'unknown error'}\n` +
+        'Make sure GNOME Keyring or another Secret Service provider is running,\n' +
+        'or set AGENTS_SECRETS_PASSPHRASE to use the encrypted-file fallback.');
 }
 export function deleteSecretToolToken(item) {
-    ensureSecretTool();
+    if (preflight() === 'file')
+        return fileDelete(item);
     const user = os.userInfo().username;
     const result = spawnSync('secret-tool', [
         'clear',
         'service', SERVICE,
         'account', user,
         'item', item,
-    ], {
-        stdio: ['ignore', 'pipe', 'pipe'],
-    });
+    ], { stdio: ['ignore', 'pipe', 'pipe'] });
+    if (result.status === 0)
+        return true;
+    const stderr = result.stderr?.toString() ?? '';
+    if (isLockedCollectionError(stderr)) {
+        activateFileFallback();
+        return fileDelete(item);
+    }
     // secret-tool clear returns 0 whether the item existed or not.
-    // This matches the macOS behavior where delete is idempotent.
-    return result.status === 0;
+    // A non-zero exit that isn't a locked-collection error is a real failure;
+    // surface that rather than silently swallowing.
+    return false;
 }
 /**
- * List secrets by prefix. secret-tool doesn't have a list command,
- * so we use secret-tool search which outputs in a specific format.
+ * Parse the item names out of `secret-tool search --all` output, keeping only
+ * those starting with `prefix`. Exported for tests.
+ *
+ * `output` must be the combined stdout+stderr of the search: libsecret splits
+ * the dump across both streams — the value/label/schema lines go to stdout
+ * while the `attribute.*` lines (which carry `attribute.item`, the only place
+ * the item name is reliably machine-readable) go to stderr (observed on
+ * libsecret 0.21.4). Which stream each line lands on has varied across
+ * libsecret versions, so callers concatenate both rather than bet on one.
  */
-export function listSecretToolItems(prefix) {
-    ensureSecretTool();
-    // secret-tool search outputs attributes, one item per block
-    const result = spawnSync('secret-tool', [
-        'search',
-        '--all',
-        'service', SERVICE,
-    ], {
-        stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    if (result.status !== 0) {
-        return [];
-    }
-    const output = result.stdout?.toString() || '';
+export function parseSecretToolItems(output, prefix) {
     const items = [];
     // Parse output format:
     // [/org/freedesktop/secrets/collection/login/1]
@@ -141,7 +373,33 @@ export function listSecretToolItems(prefix) {
     }
     return [...new Set(items)]; // dedupe
 }
-/** KeychainBackend implementation for Linux using secret-tool */
+/**
+ * List secrets by prefix. secret-tool doesn't have a list command,
+ * so we use secret-tool search which outputs in a specific format.
+ */
+export function listSecretToolItems(prefix) {
+    if (preflight() === 'file')
+        return fileList(prefix);
+    const result = spawnSync('secret-tool', [
+        'search',
+        '--all',
+        'service', SERVICE,
+    ], { stdio: ['ignore', 'pipe', 'pipe'] });
+    if (result.status !== 0) {
+        const stderr = result.stderr?.toString() ?? '';
+        if (isLockedCollectionError(stderr)) {
+            activateFileFallback();
+            return fileList(prefix);
+        }
+        return [];
+    }
+    const output = `${result.stdout?.toString() || ''}\n${result.stderr?.toString() || ''}`;
+    return parseSecretToolItems(output, prefix);
+}
+/** KeychainBackend implementation for Linux. Routes through secret-tool
+ *  with a transparent encrypted-file fallback when the default Secret
+ *  Service collection is locked (or libsecret-tools is not installed but
+ *  AGENTS_SECRETS_PASSPHRASE is set). */
 export const linuxBackend = {
     has(item) {
         return hasSecretToolToken(item);
@@ -159,3 +417,13 @@ export const linuxBackend = {
         return listSecretToolItems(prefix);
     },
 };
+/** Test-only: reset module state so independent test cases don't bleed
+ *  passphrase / fallback decisions across each other. */
+export function _resetForTest(opts = {}) {
+    fileDirOverride = opts.fileDir ?? null;
+    useFileFallback = opts.forceFileFallback ?? false;
+    warnedFallback = false;
+    cachedPassphrase = opts.passphrase ?? null;
+    checkedAvailability = false;
+    isAvailable = false;
+}

package/dist/lib/session/db.js

@@ -605,10 +605,23 @@ function buildSessionWhere(options) {
 export function querySessions(options = {}) {
     const db = getDB();
     const { clause, params } = buildSessionWhere(options);
-    const limitClause = options.limit ? `LIMIT ${Math.max(1, Math.floor(options.limit))}` : '';
+    // When a LIMIT is in play, we still need to filter stale rows AFTER the query,
+    // so over-fetch a small buffer. Without this, a page of 50 rows where the first
+    // 5 are stale would return only 45 to the caller even when there are more.
+    const limitClause = options.limit
+        ? `LIMIT ${Math.max(1, Math.floor(options.limit)) + 16}`
+        : '';
     const sql = `SELECT * FROM sessions ${clause} ORDER BY timestamp DESC ${limitClause}`;
     const rows = db.prepare(sql).all(...params);
-    return rows.map(rowToMeta);
+    // Belt-and-suspenders: drop rows whose JSONL no longer exists on disk. The
+    // authoritative fix is to keep file_path in sync (see updateSessionFilePaths
+    // callers), but skipping vanished rows here prevents phantom sessions from
+    // surfacing in the Factory UI if any code path forgets to rewrite (#136).
+    // Synthetic rows (OpenClaw channels/cron — see scanOpenClawIncremental) carry
+    // an empty file_path and are exempt; they're keyed by CLI output, not files.
+    const live = rows.filter(r => !r.file_path || fs.existsSync(r.file_path));
+    const trimmed = options.limit ? live.slice(0, options.limit) : live;
+    return trimmed.map(rowToMeta);
 }
 /** Count sessions matching the given filter options. */
 export function countSessions(options = {}) {