@phnx-labs/agents-cli 1.20.14 → 1.20.16

package/dist/lib/migrate.d.ts

@@ -25,6 +25,28 @@
  * LEGACY_SYSTEM_DIR" without duplicating data.
  */
 export declare function foldLegacySystemRepo(): void;
+/**
+ * Repair self-referential agent binary symlinks.
+ *
+ * Some installScript-based agents — notably Factory's `droid`, whose installer
+ * drops a standalone native binary at ~/.local/bin/droid — were registered at
+ * install time by resolving the post-install binary with `which <cli>`. Because
+ * ~/.agents/.cache/shims sits ahead of ~/.local/bin on PATH, `which` could
+ * return OUR OWN dispatcher shim, and the install step symlinked
+ *   ~/.agents/.history/versions/<agent>/<version>/node_modules/.bin/<cli>
+ * back at ~/.agents/.cache/shims/<cli>. Launching that agent then re-execs the
+ * dispatcher forever (an infinite exec loop that hangs the terminal).
+ *
+ * This walks every installed version's node_modules/.bin and, for any entry
+ * whose symlink resolves into the shims dir, re-points it at the real binary
+ * (found on PATH with the shims dir excluded) — or removes it when no real
+ * binary can be found, letting getBinaryPath's per-agent resolver take over.
+ * Idempotent: a correctly-pointed link is left untouched on re-run.
+ *
+ * Params default to the real on-disk locations; they are injectable so tests
+ * can drive a fixture tree without touching the user's ~/.agents.
+ */
+export declare function repairSelfReferentialBinShims(versionsRoot?: string, shimsDir?: string): void;
 /**
  * Rename the legacy `extras-extras/` plugin-marketplace dir to `agents-extras/`
  * inside every installed agent version-home, and rewrite cross-references in

package/dist/lib/migrate.js

@@ -8,7 +8,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
-import { AGENTS, agentConfigDirName } from './agents.js';
+import { AGENTS, agentConfigDirName, findInPath } from './agents.js';
 const HOME = process.env.HOME ?? os.homedir();
 const USER_DIR = path.join(HOME, '.agents');
 /** Canonical system-repo location (post-fold). */
@@ -715,6 +715,100 @@ function repairAgentConfigSymlinks() {
         console.error(`Repaired ${repaired} agent config symlink${repaired === 1 ? '' : 's'} to point at ~/.agents/versions/`);
     }
 }
+/**
+ * Repair self-referential agent binary symlinks.
+ *
+ * Some installScript-based agents — notably Factory's `droid`, whose installer
+ * drops a standalone native binary at ~/.local/bin/droid — were registered at
+ * install time by resolving the post-install binary with `which <cli>`. Because
+ * ~/.agents/.cache/shims sits ahead of ~/.local/bin on PATH, `which` could
+ * return OUR OWN dispatcher shim, and the install step symlinked
+ *   ~/.agents/.history/versions/<agent>/<version>/node_modules/.bin/<cli>
+ * back at ~/.agents/.cache/shims/<cli>. Launching that agent then re-execs the
+ * dispatcher forever (an infinite exec loop that hangs the terminal).
+ *
+ * This walks every installed version's node_modules/.bin and, for any entry
+ * whose symlink resolves into the shims dir, re-points it at the real binary
+ * (found on PATH with the shims dir excluded) — or removes it when no real
+ * binary can be found, letting getBinaryPath's per-agent resolver take over.
+ * Idempotent: a correctly-pointed link is left untouched on re-run.
+ *
+ * Params default to the real on-disk locations; they are injectable so tests
+ * can drive a fixture tree without touching the user's ~/.agents.
+ */
+export function repairSelfReferentialBinShims(versionsRoot = path.join(HISTORY_DIR, 'versions'), shimsDir = path.resolve(CACHE_DIR, 'shims')) {
+    // Normalize the shims dir through realpath so the prefix check below survives
+    // a symlinked ~/.agents (or macOS's /tmp -> /private/tmp): fs.realpathSync on
+    // the link target resolves those symlinks, so the dir we compare against must
+    // too, or every loop would read as "points at a real binary" and be skipped.
+    shimsDir = path.resolve(shimsDir);
+    try {
+        shimsDir = fs.realpathSync(shimsDir);
+    }
+    catch {
+        /* shims dir absent — leave the resolved path; nothing will match it */
+    }
+    let agents;
+    try {
+        agents = fs.readdirSync(versionsRoot);
+    }
+    catch {
+        return; // no versions installed yet
+    }
+    let repaired = 0;
+    for (const agent of agents) {
+        const cli = agent in AGENTS ? AGENTS[agent].cliCommand : agent;
+        let versions;
+        try {
+            versions = fs.readdirSync(path.join(versionsRoot, agent));
+        }
+        catch {
+            continue;
+        }
+        for (const version of versions) {
+            const binLink = path.join(versionsRoot, agent, version, 'node_modules', '.bin', cli);
+            let stat;
+            try {
+                stat = fs.lstatSync(binLink);
+            }
+            catch {
+                continue; // no .bin entry for this version
+            }
+            if (!stat.isSymbolicLink())
+                continue;
+            let real;
+            try {
+                real = fs.realpathSync(binLink);
+            }
+            catch {
+                // Dangling symlink — if it was aimed at the shims dir it's the loop
+                // residue; drop it either way so getBinaryPath reports honestly.
+                try {
+                    fs.unlinkSync(binLink);
+                    repaired++;
+                }
+                catch { /* best-effort */ }
+                continue;
+            }
+            if (!path.resolve(real).startsWith(shimsDir + path.sep))
+                continue; // points at a real binary — fine
+            // Self-referential: the link resolves back into our own shims dir.
+            // findInPath does a pure-Node PATH scan (no subprocess) and already
+            // skips our shims dir, so it returns the genuine install if one exists.
+            const realBinary = findInPath(cli);
+            try {
+                fs.unlinkSync(binLink);
+                if (realBinary)
+                    fs.symlinkSync(realBinary, binLink);
+                repaired++;
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    if (repaired > 0) {
+        console.error(`Repaired ${repaired} self-referential agent binary symlink${repaired === 1 ? '' : 's'} (infinite exec-loop fix).`);
+    }
+}
 /**
  * Move a directory from `src` to `dest`. No-op when src is absent. When dest
  * already exists, merge by copying everything that isn't already there, then
@@ -1733,4 +1827,8 @@ export async function runMigration() {
     migrateExtrasExtrasToAgentsExtras();
     // Symlink repair runs LAST so it can find the post-move version homes.
     repairAgentConfigSymlinks();
+    // Repair self-referential node_modules/.bin/<cli> symlinks (the droid
+    // infinite-exec-loop). Also runs after the bucket moves so it scans the
+    // canonical HISTORY_DIR/versions tree.
+    repairSelfReferentialBinShims();
 }

package/dist/lib/plugin-marketplace.d.ts

@@ -98,6 +98,21 @@ export declare function knownMarketplacesPath(agent: AgentId, versionHome: strin
  * Internal symlinks (target stays inside the plugin root) are preserved.
  */
 export declare function copyPluginToMarketplace(plugin: DiscoveredPlugin, spec: MarketplaceSpec | string, agent: AgentId, versionHome: string): string;
+/**
+ * Claude Code's plugin-manifest schema requires the resource path fields to be
+ * relative paths starting with "./" — `skills`/`commands`/`agents` are
+ * `union([startsWith("./"), array(startsWith("./"))])` (verified against the
+ * Claude Code binary). Bare names like "loop" fail validation and Claude rejects
+ * the ENTIRE plugin at load time, surfacing only in its `/plugin` > Errors tab.
+ *
+ * agents-cli copies plugin.json verbatim into the marketplace, so a malformed
+ * manifest ships looking fully installed while loading nothing. This catches the
+ * unambiguous type violation (non-"./" string entries) and returns one warning
+ * per offending field so the caller can surface it loudly. `hooks`/`mcpServers`
+ * are intentionally skipped — they legitimately accept inline objects, so a path
+ * check would false-positive.
+ */
+export declare function validateClaudePluginManifest(manifest: unknown): string[];
 /**
  * Re-synthesize <marketplace>/.claude-plugin/marketplace.json from the plugins
  * already installed under <marketplace>/plugins/. Always run after add or remove

package/dist/lib/plugin-marketplace.js

@@ -185,6 +185,47 @@ export function copyPluginToMarketplace(plugin, spec, agent, versionHome) {
     }
     return dest;
 }
+// ─── Manifest validation ─────────────────────────────────────────────────────
+/**
+ * Claude Code's plugin-manifest schema requires the resource path fields to be
+ * relative paths starting with "./" — `skills`/`commands`/`agents` are
+ * `union([startsWith("./"), array(startsWith("./"))])` (verified against the
+ * Claude Code binary). Bare names like "loop" fail validation and Claude rejects
+ * the ENTIRE plugin at load time, surfacing only in its `/plugin` > Errors tab.
+ *
+ * agents-cli copies plugin.json verbatim into the marketplace, so a malformed
+ * manifest ships looking fully installed while loading nothing. This catches the
+ * unambiguous type violation (non-"./" string entries) and returns one warning
+ * per offending field so the caller can surface it loudly. `hooks`/`mcpServers`
+ * are intentionally skipped — they legitimately accept inline objects, so a path
+ * check would false-positive.
+ */
+export function validateClaudePluginManifest(manifest) {
+    const warnings = [];
+    if (!manifest || typeof manifest !== 'object')
+        return warnings;
+    const m = manifest;
+    for (const field of ['skills', 'commands', 'agents']) {
+        const value = m[field];
+        if (value === undefined || value === null)
+            continue;
+        const entries = Array.isArray(value) ? value : [value];
+        for (const entry of entries) {
+            if (typeof entry !== 'string') {
+                warnings.push(`plugin.json field "${field}" must contain relative paths starting with "./" ` +
+                    `(e.g. "./${field}/<name>"); found a non-string value. Claude Code will reject the whole plugin.`);
+                break;
+            }
+            if (!entry.startsWith('./')) {
+                warnings.push(`plugin.json field "${field}" entry "${entry}" must be a relative path starting with "./" ` +
+                    `(e.g. "./${field}/${entry}"). Claude Code rejects the entire plugin otherwise — ` +
+                    `remove the field to auto-discover from ${field}/, or use relative paths.`);
+                break;
+            }
+        }
+    }
+    return warnings;
+}
 // ─── Catalog synthesis ──────────────────────────────────────────────────────
 /**
  * Re-synthesize <marketplace>/.claude-plugin/marketplace.json from the plugins
@@ -226,6 +267,9 @@ export function syncMarketplaceManifest(spec, agent, versionHome) {
         catch {
             continue;
         }
+        for (const warning of validateClaudePluginManifest(manifest)) {
+            process.stderr.write(`agents-cli: plugin '${manifest.name ?? entry.name}': ${warning}\n`);
+        }
         entries.push({
             name: manifest.name,
             source: `./plugins/${manifest.name}`,

package/dist/lib/secrets/index.js

@@ -236,6 +236,26 @@ export function setKeychainToken(item, value) {
         linuxBackend.set(item, value);
         return;
     }
+    // Bare (non-`agents-cli.`) items are written WITHOUT the biometry ACL so
+    // they round-trip with the no-prompt read path in getKeychainToken (which
+    // also uses /usr/bin/security for non-our items). This is what lets a
+    // SessionStart hook read e.g. `linear-api-key` silently on every launch.
+    // Routing these through the helper would attach a Touch ID ACL that the
+    // /usr/bin/security read can't satisfy without popping the legacy password
+    // sheet. -U upserts so repeated sets overwrite in place.
+    if (!isOurItem(item)) {
+        const sec = spawnSync('/usr/bin/security', [
+            'add-generic-password', '-U',
+            '-a', os.userInfo().username,
+            '-s', item,
+            '-w', value,
+        ], { stdio: ['ignore', 'pipe', 'pipe'] });
+        if (sec.status !== 0) {
+            const msg = sec.stderr?.toString().trim();
+            throw new Error(msg || `Failed to write keychain item '${item}'.`);
+        }
+        return;
+    }
     const bin = getKeychainHelperPath();
     const result = spawnSync(bin, ['set', item, os.userInfo().username], {
         input: value,

package/dist/lib/session/parse.d.ts

@@ -49,3 +49,5 @@ export declare function parseOpenCode(filePath: string): SessionEvent[];
 export declare function parseRush(filePath: string): SessionEvent[];
 /** Parse a Hermes session JSON file into normalized events. */
 export declare function parseHermes(filePath: string): SessionEvent[];
+/** Parse a Kimi session state.json file by reading its agents/main/wire.jsonl. */
+export declare function parseKimi(filePath: string): SessionEvent[];

package/dist/lib/session/parse.js

@@ -6,6 +6,7 @@
  * objects suitable for rendering, filtering, and summarization.
  */
 import * as fs from 'fs';
+import * as path from 'path';
 import { execFileSync } from 'child_process';
 /**
  * Largest session file we will load into memory. Above this we throw a clean
@@ -106,8 +107,8 @@ export function parseSession(filePath, agent) {
             events = parseHermes(filePath);
             break;
         case 'kimi':
-            events = [];
-            break; // Kimi event parsing not implemented yet — discover.ts builds metadata only
+            events = parseKimi(filePath);
+            break;
     }
     // Chokepoint: every string field that originated in an untrusted session
     // file gets stripped of terminal escapes here, so renderers downstream can
@@ -130,6 +131,8 @@ export function detectAgent(filePath) {
         return 'rush';
     if (filePath.includes('/.hermes/') || filePath.includes('\\.hermes\\'))
         return 'hermes';
+    if (filePath.includes('/.kimi-code/') || filePath.includes('\\.kimi-code\\'))
+        return 'kimi';
     // Cloud convention: cloud-sessions/<id>/session.<format>.jsonl
     const cloudMatch = filePath.match(/session\.(claude|codex|rush)\.jsonl(?:$|[?#])/);
     if (cloudMatch)
@@ -958,3 +961,166 @@ function hermesContentToText(content) {
         .join('\n')
         .trim();
 }
+// ---------------------------------------------------------------------------
+// Kimi parser
+//
+// Kimi stores session metadata in state.json and the conversation transcript
+// in agents/main/wire.jsonl under ~/.kimi-code/sessions/<workdir>/session_<uuid>/.
+// wire.jsonl uses a role-based schema:
+//   - "context.append_message" with role=user/assistant -> messages
+//   - "context.append_loop_event" with content.part type=text/think -> message/thinking
+//   - "context.append_loop_event" with event.type=tool.call -> tool_use
+//   - "context.append_loop_event" with event.type=tool.result -> tool_result
+//   - "usage.record" -> usage
+// ---------------------------------------------------------------------------
+/** Parse a Kimi session state.json file by reading its agents/main/wire.jsonl. */
+export function parseKimi(filePath) {
+    const sessionDir = path.dirname(filePath);
+    const wirePath = path.join(sessionDir, 'agents', 'main', 'wire.jsonl');
+    if (!fs.existsSync(wirePath)) {
+        return [];
+    }
+    const content = safeReadSessionFile(wirePath);
+    const lines = content.split('\n').filter(l => l.trim());
+    const events = [];
+    // Map tool.call uuid -> tool name so tool.result can carry the tool name.
+    const toolCallMap = new Map();
+    function extractMessageText(rawContent) {
+        if (typeof rawContent === 'string')
+            return rawContent.trim();
+        if (Array.isArray(rawContent)) {
+            return rawContent
+                .map((part) => (typeof part?.text === 'string' ? part.text : ''))
+                .join('')
+                .trim();
+        }
+        return '';
+    }
+    function timestampFrom(raw) {
+        const t = raw?.time;
+        if (typeof t === 'number' && t > 0) {
+            return new Date(t).toISOString();
+        }
+        return new Date().toISOString();
+    }
+    for (const line of lines) {
+        let raw;
+        try {
+            raw = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const type = raw?.type;
+        const timestamp = timestampFrom(raw);
+        if (type === 'context.append_message') {
+            const message = raw.message || {};
+            const role = message.role === 'user' ? 'user' : 'assistant';
+            const text = extractMessageText(message.content);
+            if (!text)
+                continue;
+            events.push({
+                type: 'message',
+                agent: 'kimi',
+                timestamp,
+                role,
+                content: text,
+            });
+        }
+        else if (type === 'context.append_loop_event') {
+            const event = raw.event || {};
+            const eventType = event.type;
+            if (eventType === 'content.part') {
+                const part = event.part || {};
+                const partType = part.type;
+                if (partType === 'text') {
+                    const text = typeof part.text === 'string' ? part.text.trim() : '';
+                    if (text) {
+                        events.push({
+                            type: 'message',
+                            agent: 'kimi',
+                            timestamp,
+                            role: 'assistant',
+                            content: text,
+                        });
+                    }
+                }
+                else if (partType === 'think') {
+                    const think = typeof part.think === 'string' ? part.think.trim() : '';
+                    if (think) {
+                        events.push({
+                            type: 'thinking',
+                            agent: 'kimi',
+                            timestamp,
+                            content: think,
+                        });
+                    }
+                }
+            }
+            else if (eventType === 'tool.call') {
+                const fn = event.function || {};
+                const toolName = typeof event.name === 'string' ? event.name : (fn.name || 'unknown');
+                let args = {};
+                if (typeof fn.arguments === 'string') {
+                    try {
+                        args = JSON.parse(fn.arguments);
+                    }
+                    catch {
+                        args = { _raw: fn.arguments };
+                    }
+                }
+                else if (fn.arguments && typeof fn.arguments === 'object') {
+                    args = fn.arguments;
+                }
+                const callId = event.toolCallId || event.uuid;
+                if (callId) {
+                    toolCallMap.set(callId, toolName);
+                }
+                events.push({
+                    type: 'tool_use',
+                    agent: 'kimi',
+                    timestamp,
+                    tool: toolName,
+                    args,
+                    path: args.path || args.file_path || undefined,
+                    command: toolName === 'Bash' ? args.command : undefined,
+                });
+            }
+            else if (eventType === 'tool.result') {
+                const callId = event.toolCallId || event.parentUuid;
+                const toolName = (callId && toolCallMap.get(callId)) || 'unknown';
+                const result = event.result || {};
+                const output = typeof result.output === 'string' ? result.output : '';
+                const isError = result.isError === true || (output && output.startsWith('Error:'));
+                events.push({
+                    type: isError ? 'error' : 'tool_result',
+                    agent: 'kimi',
+                    timestamp,
+                    tool: toolName,
+                    success: !isError,
+                    output: output.length > 500 ? output.slice(0, 497) + '...' : output,
+                });
+                if (callId) {
+                    toolCallMap.delete(callId);
+                }
+            }
+        }
+        else if (type === 'usage.record') {
+            const usage = raw.usage || {};
+            const inputTokens = usage.inputOther ?? usage.input_tokens;
+            const outputTokens = usage.output ?? usage.output_tokens;
+            if ((typeof inputTokens === 'number' && inputTokens >= 0) ||
+                (typeof outputTokens === 'number' && outputTokens >= 0)) {
+                events.push({
+                    type: 'usage',
+                    agent: 'kimi',
+                    timestamp,
+                    model: raw.model || usage.model,
+                    inputTokens: typeof inputTokens === 'number' ? inputTokens : undefined,
+                    outputTokens: typeof outputTokens === 'number' ? outputTokens : undefined,
+                });
+            }
+        }
+    }
+    return events;
+}

package/dist/lib/session/sync/agents.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Per-agent adapter for sync. Each supported agent declares where its
+ * transcripts live and how to derive a session id and storage-relative key
+ * from a file path. The merge (crdt.ts) and transport (r2.ts) are fully
+ * agent-agnostic — adding a new agent is just another entry in SYNC_AGENTS.
+ *
+ * Mirror layout: synced-in transcripts land under
+ *   ~/.agents/.history/backups/<agent>/<machine>/<subdir>/<relKey>
+ * which is already a scan root (getAgentSessionDirs scans backups/<agent>/<ts>),
+ * so the existing incremental scanner indexes them with no changes. Because the
+ * scanner dedups by session id with the live home scanned first, a session that
+ * also exists locally always wins — the mirror only ever fills in sessions
+ * originated on other machines.
+ */
+export interface LocalTranscript {
+    /** Absolute path on this machine. */
+    absPath: string;
+    /** Globally-unique session id (the grouping key across machines). */
+    sessionId: string;
+    /** Path relative to the agent's subdir root — preserved in the mirror layout. */
+    relKey: string;
+}
+export interface SyncAgentSpec {
+    id: string;
+    /** Config subdir under the agent home that holds transcripts. */
+    subdir: string;
+    /** Derive the session id from a storage-relative key. */
+    sessionIdFromRelKey(relKey: string): string;
+}
+export declare const SYNC_AGENTS: SyncAgentSpec[];
+/**
+ * List this machine's own transcript files for an agent, EXCLUDING the sync
+ * mirror (we never re-upload another machine's files under our prefix). Dedups
+ * by session id so a session present in multiple version homes is uploaded once.
+ */
+export declare function listLocalTranscripts(spec: SyncAgentSpec): LocalTranscript[];
+/** Session ids this machine holds locally (live home), used to skip mirror writes. */
+export declare function localSessionIds(spec: SyncAgentSpec): Set<string>;
+/** Absolute mirror path for a remote machine's transcript — lands in a scan root. */
+export declare function mirrorPath(spec: SyncAgentSpec, machine: string, relKey: string): string;
+/** R2 object key for a transcript: sessions/<machine>/<agent>/<sessionId>.jsonl */
+export declare function objectKey(machine: string, agentId: string, sessionId: string): string;
+/** R2 object key for a machine's manifest. */
+export declare function manifestKey(machine: string): string;
+/** Prefix under which all machine manifests live (for discovery). */
+export declare const SESSIONS_PREFIX = "sessions/";

package/dist/lib/session/sync/agents.js

@@ -0,0 +1,94 @@
+/**
+ * Per-agent adapter for sync. Each supported agent declares where its
+ * transcripts live and how to derive a session id and storage-relative key
+ * from a file path. The merge (crdt.ts) and transport (r2.ts) are fully
+ * agent-agnostic — adding a new agent is just another entry in SYNC_AGENTS.
+ *
+ * Mirror layout: synced-in transcripts land under
+ *   ~/.agents/.history/backups/<agent>/<machine>/<subdir>/<relKey>
+ * which is already a scan root (getAgentSessionDirs scans backups/<agent>/<ts>),
+ * so the existing incremental scanner indexes them with no changes. Because the
+ * scanner dedups by session id with the live home scanned first, a session that
+ * also exists locally always wins — the mirror only ever fills in sessions
+ * originated on other machines.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getHistoryDir } from '../../state.js';
+import { getAgentSessionDirs } from '../discover.js';
+import { walkForFiles } from '../../fs-walk.js';
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+export const SYNC_AGENTS = [
+    {
+        id: 'claude',
+        subdir: 'projects',
+        // Claude transcripts are <projectDir>/<sessionId>.jsonl.
+        sessionIdFromRelKey: rel => path.basename(rel).replace(/\.jsonl$/, ''),
+    },
+    {
+        id: 'codex',
+        subdir: 'sessions',
+        // Codex transcripts are rollout-<ts>-<uuid>.jsonl under date dirs; the uuid
+        // is the session id (matches session_meta.payload.id).
+        sessionIdFromRelKey: rel => path.basename(rel).match(UUID_RE)?.[0] ?? rel,
+    },
+];
+let cachedMirrorRoot = null;
+function mirrorRootReal() {
+    if (cachedMirrorRoot)
+        return cachedMirrorRoot;
+    const root = path.join(getHistoryDir(), 'backups');
+    cachedMirrorRoot = safeReal(root);
+    return cachedMirrorRoot;
+}
+function safeReal(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/**
+ * List this machine's own transcript files for an agent, EXCLUDING the sync
+ * mirror (we never re-upload another machine's files under our prefix). Dedups
+ * by session id so a session present in multiple version homes is uploaded once.
+ */
+export function listLocalTranscripts(spec) {
+    const mirror = mirrorRootReal();
+    const out = [];
+    const seen = new Set();
+    for (const dir of getAgentSessionDirs(spec.id, spec.subdir)) {
+        if (safeReal(dir).startsWith(mirror))
+            continue; // skip synced-in mirror dirs
+        for (const abs of walkForFiles(dir, '.jsonl', 100_000)) {
+            const relKey = path.relative(dir, abs);
+            if (!relKey || relKey.startsWith('..'))
+                continue;
+            const sessionId = spec.sessionIdFromRelKey(relKey);
+            if (seen.has(sessionId))
+                continue;
+            seen.add(sessionId);
+            out.push({ absPath: abs, sessionId, relKey });
+        }
+    }
+    return out;
+}
+/** Session ids this machine holds locally (live home), used to skip mirror writes. */
+export function localSessionIds(spec) {
+    return new Set(listLocalTranscripts(spec).map(t => t.sessionId));
+}
+/** Absolute mirror path for a remote machine's transcript — lands in a scan root. */
+export function mirrorPath(spec, machine, relKey) {
+    return path.join(getHistoryDir(), 'backups', spec.id, machine, spec.subdir, relKey);
+}
+/** R2 object key for a transcript: sessions/<machine>/<agent>/<sessionId>.jsonl */
+export function objectKey(machine, agentId, sessionId) {
+    return `sessions/${machine}/${agentId}/${sessionId}.jsonl`;
+}
+/** R2 object key for a machine's manifest. */
+export function manifestKey(machine) {
+    return `sessions/${machine}/manifest.json`;
+}
+/** Prefix under which all machine manifests live (for discovery). */
+export const SESSIONS_PREFIX = 'sessions/';

package/dist/lib/session/sync/config.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Configuration for cross-machine session sync: R2 credentials and this
+ * machine's stable identity. Credentials come from the `r2.backups` secrets
+ * bundle (OS keychain on macOS, libsecret on Linux) — never from env or disk.
+ */
+/** Secrets bundle holding the R2 credentials. */
+export declare const SYNC_BUNDLE = "r2.backups";
+export interface R2Config {
+    accountId: string;
+    bucket: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** S3-compatible endpoint for the account (no bucket, no trailing slash). */
+    endpoint: string;
+}
+/**
+ * Resolve R2 credentials from the `r2.backups` bundle. Throws a clear,
+ * actionable error if the bundle or any key is missing — sync cannot proceed
+ * without real credentials (no silent fallback).
+ */
+export declare function loadR2Config(): R2Config;
+/** True when the sync bundle exists and looks resolvable, without throwing. */
+export declare function isSyncConfigured(): boolean;
+/**
+ * This machine's stable, human-readable id, used as its R2 prefix and mirror
+ * directory name. Tailnet hostnames (zion, yosemite-s0, mac-mini) are already
+ * unique and readable; we lowercase and strip any domain suffix. Overridable
+ * via AGENTS_SYNC_MACHINE_ID for tests and unusual setups.
+ */
+export declare function machineId(): string;