@phnx-labs/agents-cli 1.20.53 → 1.20.55

package/dist/lib/daemon.js

@@ -23,10 +23,13 @@ import { redactSecrets } from './redact.js';
 const PID_FILE = 'daemon.pid';
 const LOCK_FILE = 'daemon.lock';
 const LOG_FILE = 'logs.jsonl';
+const HEARTBEAT_FILE = 'heartbeat.json';
 const LOG_MAX_SIZE = 5 * 1024 * 1024; // 5 MB
 const LOG_ROTATE_COUNT = 3;
 const PLIST_NAME = 'com.phnx-labs.agents-daemon';
 const SYSTEMD_UNIT = 'agents-daemon.service';
+const MONITOR_TICK_MS = 60_000;
+const WEDGE_THRESHOLD_TICKS = 3;
 // A long-lived `claude setup-token` value stored in this secrets bundle/key is
 // baked into the daemon's service-manager environment so headless routine runs
 // authenticate without depending on the short-lived interactive Keychain OAuth
@@ -118,6 +121,48 @@ export function removeDaemonPid() {
         fs.unlinkSync(pidPath);
     }
 }
+function getHeartbeatPath() {
+    return path.join(getDaemonDir(), HEARTBEAT_FILE);
+}
+export function writeHeartbeat(pid = process.pid) {
+    const hb = { lastTick: new Date().toISOString(), pid };
+    try {
+        fs.writeFileSync(getHeartbeatPath(), JSON.stringify(hb), 'utf-8');
+    }
+    catch { /* best effort */ }
+}
+export function readHeartbeat() {
+    try {
+        const raw = fs.readFileSync(getHeartbeatPath(), 'utf-8');
+        const hb = JSON.parse(raw);
+        if (!hb.lastTick || !hb.pid)
+            return null;
+        return hb;
+    }
+    catch {
+        return null;
+    }
+}
+export function removeHeartbeat() {
+    try {
+        fs.unlinkSync(getHeartbeatPath());
+    }
+    catch { /* already removed */ }
+}
+export function isDaemonWedged() {
+    const pid = readDaemonPid();
+    if (!pid)
+        return false;
+    if (!isAlive(pid))
+        return false;
+    const hb = readHeartbeat();
+    if (!hb)
+        return false;
+    if (hb.pid !== pid)
+        return false;
+    const elapsed = Date.now() - Date.parse(hb.lastTick);
+    return elapsed > WEDGE_THRESHOLD_TICKS * MONITOR_TICK_MS;
+}
 /** Check if the daemon process is alive by sending signal 0 to the stored PID. */
 export function isDaemonRunning() {
     const pid = readDaemonPid();
@@ -323,9 +368,11 @@ export async function runDaemon() {
     catch (err) {
         log('ERROR', `Browser IPC failed to start: ${err.message}`);
     }
+    writeHeartbeat();
     const monitorInterval = setInterval(() => {
+        writeHeartbeat();
         monitorRunningJobs();
-    }, 60_000);
+    }, MONITOR_TICK_MS);
     // Cross-machine session sync: push this machine's transcripts to R2 and pull
     // every other machine's, ~every 90s. Skipped silently when the r2.backups
     // bundle is absent. An overlap guard prevents a slow cycle from stacking.
@@ -548,6 +595,7 @@ export async function runDaemon() {
         clearInterval(launchHealthInterval);
         clearTimeout(launchHealthKickoff);
         removeDaemonPid();
+        removeHeartbeat();
         process.exit(0);
     };
     process.on('SIGHUP', handleReload);
@@ -605,6 +653,7 @@ export function writeOwnerOnlyServiceManifest(filePath, content) {
 /** Generate a macOS launchd plist for auto-starting the daemon. */
 export function generateLaunchdPlist(oauthToken = readDaemonClaudeOAuthToken()) {
     const agentsBin = getAgentsBinPath();
+    const launch = getDaemonLaunch(agentsBin);
     const logPath = getLogPath();
     const oauthEntry = oauthToken
         ? `
@@ -619,9 +668,7 @@ export function generateLaunchdPlist(oauthToken = readDaemonClaudeOAuthToken())
   <string>${PLIST_NAME}</string>
   <key>ProgramArguments</key>
   <array>
-    <string>${agentsBin}</string>
-    <string>daemon</string>
-    <string>_run</string>
+${[launch.command, ...launch.args].map((arg) => `    <string>${xmlEscape(arg)}</string>`).join('\n')}
   </array>
   <key>RunAtLoad</key>
   <true/>
@@ -639,9 +686,15 @@ export function generateLaunchdPlist(oauthToken = readDaemonClaudeOAuthToken())
 </dict>
 </plist>`;
 }
+/** Quote one systemd ExecStart argument without delegating parsing to a shell. */
+function systemdExecArg(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
 /** Generate a Linux systemd user unit for auto-starting the daemon. */
 export function generateSystemdUnit(oauthToken = readDaemonClaudeOAuthToken()) {
     const agentsBin = getAgentsBinPath();
+    const launch = getDaemonLaunch(agentsBin);
+    const execStart = [launch.command, ...launch.args].map(systemdExecArg).join(' ');
     const oauthLine = oauthToken
         ? `\nEnvironment=${DAEMON_OAUTH_KEY}=${oauthToken}`
         : '';
@@ -651,7 +704,7 @@ After=network.target
 
 [Service]
 Type=simple
-ExecStart=${agentsBin} daemon _run
+ExecStart=${execStart}
 Restart=always
 RestartSec=10
 Environment=PATH=/usr/local/bin:/usr/bin:/bin:${os.homedir()}/.nvm/versions/node/v24.0.0/bin${oauthLine}
@@ -842,11 +895,29 @@ export function buildDetachedDaemonEnv(baseEnv = process.env, oauthToken = readD
  * `which agents`), run it directly — it owns its own runtime resolution.
  */
 export function getDaemonLaunch(agentsBin = getAgentsBinPath()) {
+    const { warnings } = validateDaemonBinary(agentsBin);
+    for (const w of warnings)
+        process.stderr.write(`[agents] ${w}\n`);
     if (/\.(c|m)?js$/.test(agentsBin)) {
         return { command: process.execPath, args: [agentsBin, 'daemon', '_run'] };
     }
     return { command: agentsBin, args: ['daemon', '_run'] };
 }
+export function validateDaemonBinary(binPath) {
+    const warnings = [];
+    if (/\/\$bunfs\/root\//.test(binPath)) {
+        throw new Error(`Refusing to supervise daemon: resolved binary is a bun virtual path (${binPath}). ` +
+            `Install agents globally (npm i -g @phnx-labs/agents-cli) and restart.`);
+    }
+    if (/[/\\]\.agents[/\\]worktrees[/\\]/.test(binPath)) {
+        warnings.push(`Warning: daemon binary is inside a git worktree (${binPath}). ` +
+            `A worktree deletion will wedge the daemon. Use the globally installed binary instead.`);
+    }
+    if (!fs.existsSync(binPath) && !/\.(c|m)?js$/.test(binPath)) {
+        warnings.push(`Warning: daemon binary does not exist on disk (${binPath}).`);
+    }
+    return { warnings };
+}
 export function startDetached(opts = {}) {
     const agentsBin = opts.agentsBin ?? getAgentsBinPath();
     const logPath = opts.logPath ?? getLogPath();
@@ -948,13 +1019,27 @@ export function stopDaemon() {
 /** Get current daemon status including running state, PID, and enabled job count. */
 export function getDaemonStatus() {
     const running = isDaemonRunning();
+    const wedged = running && isDaemonWedged();
     const pid = readDaemonPid();
     let jobCount = 0;
     try {
         jobCount = listAllJobs().filter((j) => j.enabled).length;
     }
     catch { /* job listing failed */ }
-    return { running, pid, jobCount, logPath: getLogPath() };
+    let binaryPath = null;
+    try {
+        binaryPath = getAgentsBinPath();
+    }
+    catch { /* resolution failed */ }
+    return {
+        state: wedged ? 'wedged' : running ? 'running' : 'stopped',
+        running,
+        pid,
+        jobCount,
+        logPath: getLogPath(),
+        binaryPath,
+        heartbeat: readHeartbeat(),
+    };
 }
 /** Read the daemon log, optionally limited to the last N lines. */
 export function readDaemonLog(lines) {

package/dist/lib/devices/resolve-target.d.ts

@@ -1,4 +1,4 @@
-import { type DeviceRegistry } from './registry.js';
+import { type DeviceProfile, type DeviceRegistry } from './registry.js';
 /** A dialable peer: the ssh target, the machine id used to tag its rows, a
  * display name, and the OS family that picks the remote shell dialect. */
 export interface ResolvedSshTarget {
@@ -7,14 +7,31 @@ export interface ResolvedSshTarget {
     name: string;
     os?: string;
 }
+/** Split a `user@host` / `host` token into its login user (if any) and host part. */
+export declare function splitUserHost(token: string): {
+    user?: string;
+    host: string;
+};
 /**
  * Resolve one `--host`/`--device` token to a concrete ssh target through the
  * registry. Registry hit → the device's real address + platform (so the machine
- * id, route, and OS all match the auto-discovery sweep). Miss → a literal
- * `user@host` fallback, its OS taken from the host overlay if enrolled. Returns
- * undefined only when the token fails the shared ssh-target injection guard.
+ * id, route, and OS all match the auto-discovery sweep), with any `user@`
+ * overriding the login account. Miss → a literal `user@host` fallback, its OS
+ * taken from the host overlay if enrolled. Returns undefined only when the token
+ * fails the shared ssh-target injection guard.
  */
 export declare function resolveSshTarget(token: string, reg: DeviceRegistry): ResolvedSshTarget | undefined;
+/**
+ * Resolve a target token to a full {@link DeviceProfile} for `agents ssh`. Same
+ * grammar as {@link resolveSshTarget}, but returns the whole profile (auth,
+ * shell, tailscale metadata) `buildSshInvocation` needs — not just a target
+ * string. A registered `name` or `user@device` yields that profile (with the
+ * login user overridden by any `user@`); an ad-hoc `user@host`/`host` literal
+ * yields a synthesized key-auth profile. A bare unregistered alias (no `@`/dot)
+ * returns undefined so the caller reports "Unknown device" rather than dialing a
+ * literal — the strict behaviour the interactive wrapper has always had.
+ */
+export declare function resolveDeviceTarget(token: string, reg: DeviceRegistry): DeviceProfile | undefined;
 /**
  * Resolve an explicit `--host`/`--device` list to dialable targets, reading the
  * registry once. A token that fails the injection guard is skipped with a

package/dist/lib/devices/resolve-target.js

@@ -13,8 +13,12 @@
  * `%C` hash → a cold dial every time) and could read a perfectly reachable box
  * as "unreachable" when only the non-Tailscale route was down.
  *
- * A raw `user@host` that matches no registered device falls back to a literal
- * target so ad-hoc boxes still work.
+ * The grammar is uniform across the fleet: `mac-mini` (device name), and
+ * `muqsit@mac-mini` (same device, login user overridden) both resolve through
+ * the registry to the device's Tailscale route — the `user@` form no longer
+ * short-circuits to a bare `ssh muqsit@mac-mini` (LAN DNS). A `user@host` that
+ * matches no registered device falls back to a literal target so ad-hoc boxes
+ * still work.
  */
 import chalk from 'chalk';
 import { assertValidSshTarget } from '../ssh-exec.js';
@@ -22,12 +26,28 @@ import { normalizeHost } from '../machine-id.js';
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
 import { sshTargetFor } from './connect.js';
 import { loadDevices } from './registry.js';
+/** Split a `user@host` / `host` token into its login user (if any) and host part. */
+export function splitUserHost(token) {
+    const at = token.indexOf('@');
+    return at === -1 ? { host: token } : { user: token.slice(0, at), host: token.slice(at + 1) };
+}
+/**
+ * Match a host part (the piece after any `user@`) to a registered device: exact
+ * registry key first, then a normalized-host match so `yosemite-s0` and
+ * `yosemite-s0.<tailnet>.ts.net` land on the same profile. The single source of
+ * truth both `resolveSshTarget` (fan-out) and `resolveDeviceTarget` (`agents
+ * ssh`) share, so a `user@device` can never resolve two different routes.
+ */
+function matchDevice(host, reg) {
+    return reg[host] ?? Object.values(reg).find((d) => normalizeHost(d.name) === normalizeHost(host));
+}
 /**
  * Resolve one `--host`/`--device` token to a concrete ssh target through the
  * registry. Registry hit → the device's real address + platform (so the machine
- * id, route, and OS all match the auto-discovery sweep). Miss → a literal
- * `user@host` fallback, its OS taken from the host overlay if enrolled. Returns
- * undefined only when the token fails the shared ssh-target injection guard.
+ * id, route, and OS all match the auto-discovery sweep), with any `user@`
+ * overriding the login account. Miss → a literal `user@host` fallback, its OS
+ * taken from the host overlay if enrolled. Returns undefined only when the token
+ * fails the shared ssh-target injection guard.
  */
 export function resolveSshTarget(token, reg) {
     try {
@@ -36,22 +56,70 @@ export function resolveSshTarget(token, reg) {
     catch {
         return undefined;
     }
-    const bare = token.split('@').pop() || token;
-    // An explicit `user@host` names an exact account/target — honour it literally.
-    // A bare alias (`yosemite-s0`) resolves through the registry to the device's
-    // real address, so it never diverges from the auto-discovery sweep.
-    const device = token.includes('@')
-        ? undefined
-        : reg[token] ?? Object.values(reg).find((d) => normalizeHost(d.name) === normalizeHost(bare));
+    const { user, host } = splitUserHost(token);
+    // A device and a `user@device` are the same box; resolve the host part through
+    // the registry so both dial the Tailscale route, and let an explicit `user@`
+    // override only the login account.
+    const device = matchDevice(host, reg);
     if (device) {
         try {
-            return { target: sshTargetFor(device), machine: normalizeHost(device.name), name: device.name, os: device.platform };
+            const effective = user ? { ...device, user } : device;
+            return { target: sshTargetFor(effective), machine: normalizeHost(device.name), name: device.name, os: device.platform };
         }
         catch {
             // Registered but has no address to dial — fall through to the literal token.
         }
     }
-    return { target: token, machine: normalizeHost(bare), name: token, os: resolveRemoteOsSync(token) };
+    return { target: token, machine: normalizeHost(host), name: token, os: resolveRemoteOsSync(token) };
+}
+/** Timestamps for a synthesized ad-hoc profile — never persisted, so a constant
+ * keeps the value deterministic (and side-effect free) without reading the clock. */
+const SYNTH_TS = '1970-01-01T00:00:00.000Z';
+/** True when a token is clearly a network target (a `user@`, or a dotted/IPv6
+ * host / IP) rather than a bare alias. A bare unknown word is a typo, so `agents
+ * ssh foo` still says "Unknown device" instead of dialing a literal `foo`. */
+function looksLikeHostLiteral(token) {
+    return token.includes('@') || token.includes('.') || token.includes(':');
+}
+/** Synthesize a throwaway device profile for an ad-hoc `user@host` / `host`
+ * literal so `agents ssh` can dial a box that was never registered. */
+function adHocDevice(token, host, user) {
+    const isIp = /^\d{1,3}(\.\d{1,3}){3}$/.test(host);
+    return {
+        name: token,
+        platform: 'unknown',
+        shell: 'posix',
+        user,
+        address: { via: 'manual', dnsName: isIp ? undefined : host, ip: isIp ? host : undefined },
+        auth: { method: 'key' },
+        createdAt: SYNTH_TS,
+        updatedAt: SYNTH_TS,
+    };
+}
+/**
+ * Resolve a target token to a full {@link DeviceProfile} for `agents ssh`. Same
+ * grammar as {@link resolveSshTarget}, but returns the whole profile (auth,
+ * shell, tailscale metadata) `buildSshInvocation` needs — not just a target
+ * string. A registered `name` or `user@device` yields that profile (with the
+ * login user overridden by any `user@`); an ad-hoc `user@host`/`host` literal
+ * yields a synthesized key-auth profile. A bare unregistered alias (no `@`/dot)
+ * returns undefined so the caller reports "Unknown device" rather than dialing a
+ * literal — the strict behaviour the interactive wrapper has always had.
+ */
+export function resolveDeviceTarget(token, reg) {
+    try {
+        assertValidSshTarget(token);
+    }
+    catch {
+        return undefined;
+    }
+    const { user, host } = splitUserHost(token);
+    const device = matchDevice(host, reg);
+    if (device)
+        return user ? { ...device, user } : device;
+    if (looksLikeHostLiteral(token))
+        return adHocDevice(token, host, user);
+    return undefined;
 }
 /**
  * Resolve an explicit `--host`/`--device` list to dialable targets, reading the

package/dist/lib/devices/sync.d.ts

@@ -1,5 +1,30 @@
+import { type DeviceInput } from './registry.js';
 import { type TailscaleNode } from './tailscale.js';
 import type { PendingDevice } from './pending.js';
+/**
+ * The login user to stamp onto newly-synced devices. Tailscale status carries a
+ * node's OS and address but NOT the account you ssh in as, so we materialize the
+ * local operator's username — tailnet devices are overwhelmingly one person's
+ * boxes, and this is exactly the account ssh would already fall back to. Pinning
+ * it in the registry makes `--host <device>` dial that account no matter which
+ * machine launches the fan-out (a peer whose local user differs otherwise dials
+ * the wrong account). Returns undefined when the username isn't a safe ssh
+ * identifier, so a weird value never lands in the registry. */
+export declare function localLoginUser(): string | undefined;
+/**
+ * Reduce a raw OS username to a safe ssh account, or undefined. Windows reports
+ * the login as `COMPUTER\user` / `DOMAIN\user`; the ssh account is the bare name
+ * after the backslash — without this strip the `\` fails the charset guard and
+ * Windows boxes never pin a user. Pure, so the platform-specific munging is
+ * unit-tested without reading the real OS user. */
+export declare function sanitizeLoginUser(raw: string | undefined): string | undefined;
+/**
+ * Fill in a device's login user during sync WITHOUT ever clobbering an account
+ * the user pinned. Precedence: an existing registered user wins; else the local
+ * operator's username; else leave it unset (ssh's implicit local default still
+ * applies). Pure so the "never overwrite an explicit user" guard is unit-tested
+ * without a tailnet. */
+export declare function withDefaultUser(input: DeviceInput, prevUser: string | undefined, localUser: string | undefined): DeviceInput;
 /**
  * bootstrap — register every non-ignored node (opt-out). First-run `agents
  *   setup` and manual `agents devices sync`, so the fleet is usable out of box.

package/dist/lib/devices/sync.js

@@ -14,8 +14,51 @@
  *   - soft (`soft: true`): auto-callers must never abort setup/sync because a
  *     machine has no tailscale — they get a result with `ok: false` instead.
  */
+import * as os from 'os';
 import { loadDevices, loadIgnored, upsertDevice, } from './registry.js';
 import { nodeToDeviceInput, parseTailscaleStatus, tailscaleStatusJson, } from './tailscale.js';
+/**
+ * The login user to stamp onto newly-synced devices. Tailscale status carries a
+ * node's OS and address but NOT the account you ssh in as, so we materialize the
+ * local operator's username — tailnet devices are overwhelmingly one person's
+ * boxes, and this is exactly the account ssh would already fall back to. Pinning
+ * it in the registry makes `--host <device>` dial that account no matter which
+ * machine launches the fan-out (a peer whose local user differs otherwise dials
+ * the wrong account). Returns undefined when the username isn't a safe ssh
+ * identifier, so a weird value never lands in the registry. */
+export function localLoginUser() {
+    let u;
+    try {
+        u = os.userInfo().username;
+    }
+    catch {
+        u = process.env.USER || process.env.USERNAME || undefined;
+    }
+    return sanitizeLoginUser(u);
+}
+/**
+ * Reduce a raw OS username to a safe ssh account, or undefined. Windows reports
+ * the login as `COMPUTER\user` / `DOMAIN\user`; the ssh account is the bare name
+ * after the backslash — without this strip the `\` fails the charset guard and
+ * Windows boxes never pin a user. Pure, so the platform-specific munging is
+ * unit-tested without reading the real OS user. */
+export function sanitizeLoginUser(raw) {
+    if (!raw)
+        return undefined;
+    const bare = raw.includes('\\') ? raw.slice(raw.lastIndexOf('\\') + 1) : raw;
+    return /^[a-zA-Z0-9._-]+$/.test(bare) ? bare : undefined;
+}
+/**
+ * Fill in a device's login user during sync WITHOUT ever clobbering an account
+ * the user pinned. Precedence: an existing registered user wins; else the local
+ * operator's username; else leave it unset (ssh's implicit local default still
+ * applies). Pure so the "never overwrite an explicit user" guard is unit-tested
+ * without a tailnet. */
+export function withDefaultUser(input, prevUser, localUser) {
+    if (input.user || prevUser || !localUser)
+        return input;
+    return { ...input, user: localUser };
+}
 /**
  * Node names present on the tailnet but neither already in the registry nor on
  * the ignore-list — i.e. genuinely new devices worth surfacing. Pure so the
@@ -68,8 +111,10 @@ export async function runDeviceSync(opts = {}) {
             platform: byName.get(name)?.platform ?? 'unknown',
         }));
         const toUpsert = selectNodesToUpsert(nodes, registered, ignored, mode);
+        const localUser = localLoginUser();
         for (const node of toUpsert) {
-            await upsertDevice(node.name, nodeToDeviceInput(node));
+            const input = withDefaultUser(nodeToDeviceInput(node), registeredBefore[node.name]?.user, localUser);
+            await upsertDevice(node.name, input);
         }
         return { ok: true, synced: toUpsert.length, pending };
     }

package/dist/lib/exec.js

@@ -927,14 +927,16 @@ async function runInTmux(options, executable, args) {
         // When the AGENT pane dies, detach the client (don't kill) so the session
         // survives just long enough to read the dead pane's exit status below. The
         // `#{hook_pane}` guard scopes this to the agent pane only: if the user splits
-        // the window and exits one of THEIR panes, the else-branch `kill-pane` closes
-        // that split in place instead of detaching everyone (the pane-died hook runs
-        // in the dead pane's context, so bare `kill-pane` targets it). Without the
-        // guard, exiting any split kicked the user clean out of tmux.
-        await setSessionHook(name, 'pane-died', agentPaneDiedHook(name, pane), socket);
-        // Stamp the schema marker so the daemon reconcile (which retrofits older
-        // sessions) recognizes this one as already current and skips it.
-        await markSessionHookSchema(name, socket);
+        // the window and exits one of THEIR panes, the else-branch closes that split
+        // in place instead of detaching everyone (`run-shell -C` executes the
+        // targeted kill inside tmux's server command queue, avoiding a second
+        // client racing the same socket under load, #965). Without the guard,
+        // exiting any split kicked the user clean out of tmux.
+        const hookInstalled = await setSessionHook(name, 'pane-died', agentPaneDiedHook(name, pane), socket);
+        // Stamp the schema marker only after tmux accepted the hook. A failed
+        // install stays unmarked so daemon reconciliation retries it later.
+        if (hookInstalled)
+            await markSessionHookSchema(name, socket);
         // Record the agent's OS pid (the pane leaf, thanks to `exec`) WITH its tmux
         // pane so the active-scan attributes it exactly and shows the %pane.
         let panePid = 0;

package/dist/lib/overdue.js

@@ -14,7 +14,7 @@
 import { Cron } from 'croner';
 import * as os from 'os';
 import { spawn } from 'child_process';
-import { listJobs, getLatestRun } from './routines.js';
+import { listJobs, getLatestRun, jobRunsOnThisDevice } from './routines.js';
 // Tolerance between "expected fire" and "recorded run start" — accounts for
 // the small gap between the cron tick and when the runner writes meta.json.
 const GRACE_MS = 60_000;
@@ -47,6 +47,11 @@ export function detectOverdueJobs(now = new Date()) {
         // Trigger-only jobs (no cron schedule) never have an expected fire time.
         if (!job.schedule)
             continue;
+        // A job pinned to another device is that device's to run, notify, and
+        // catch up — flagging it here would make every machine in the fleet nag
+        // (and `catchup` fire) for a job that must not run locally.
+        if (!jobRunsOnThisDevice(job))
+            continue;
         let expected = null;
         try {
             const cronOptions = { paused: true };

package/dist/lib/profiles-presets.js

@@ -88,6 +88,58 @@ export const PRESETS = [
             ANTHROPIC_SMALL_FAST_MODEL: 'deepseek/deepseek-chat-v3-0324',
         },
     },
+    {
+        name: 'open-claude',
+        description: 'Open-weight coding via OpenRouter inside Claude Code (Qwen3 Coder Next, 256K ctx, $0.15/$0.80 per 1M). HEADLESS-SAFE — best general preset for open-claude usage with Claude Code harness.',
+        ...OPENROUTER_AUTH,
+        env: {
+            ANTHROPIC_BASE_URL: OPENROUTER_BASE,
+            ANTHROPIC_MODEL: 'qwen/qwen3-coder-next',
+            ANTHROPIC_SMALL_FAST_MODEL: 'qwen/qwen3-coder-next',
+        },
+    },
+    {
+        name: 'claude-spark',
+        description: 'Meta Claude Spark 1.1 via OpenRouter inside Claude Code (open alternative). Model: meta/claude-spark-1.1 — free via opencode, now usable in Claude Code UI. HEADLESS-SAFE. For open-claude spark usage.',
+        ...OPENROUTER_AUTH,
+        env: {
+            ANTHROPIC_BASE_URL: OPENROUTER_BASE,
+            ANTHROPIC_MODEL: 'meta/claude-spark-1.1',
+            ANTHROPIC_SMALL_FAST_MODEL: 'meta/claude-spark-1.1',
+        },
+    },
+    // ----- OpenCode CLI (open-claude harness) -----
+    {
+        name: 'opencode',
+        description: 'OpenCode default — uses your configured model via opencode auth. Run `opencode auth` to login, then `agents run opencode --model meta/claude-spark-1.1 "prompt"` for spark usage.',
+        provider: 'opencode',
+        host: 'opencode',
+        authEnvVar: 'OPENCODE_API_KEY',
+        authOptional: true,
+        env: {},
+    },
+    {
+        name: 'opencode-spark',
+        description: 'Meta Claude Spark 1.1 via OpenCode (free, headless-safe). Pinned to meta/claude-spark-1.1 — best for open-claude usage with opencode harness.',
+        provider: 'opencode',
+        host: 'opencode',
+        authEnvVar: 'OPENCODE_API_KEY',
+        authOptional: true,
+        env: {
+            OPENCODE_MODEL: 'meta/claude-spark-1.1',
+        },
+    },
+    {
+        name: 'opencode-qwen',
+        description: 'Qwen3 Coder Next via OpenCode (open-claude path). Use `agents run opencode-qwen "prompt"` — free via opencode provider.',
+        provider: 'opencode',
+        host: 'opencode',
+        authEnvVar: 'OPENCODE_API_KEY',
+        authOptional: true,
+        env: {
+            OPENCODE_MODEL: 'qwen/qwen3-coder-next',
+        },
+    },
     // ----- xAI Grok Build CLI (native host) -----
     {
         name: 'grok-fast',

package/dist/lib/registry.d.ts

@@ -44,6 +44,30 @@ export declare function mcpEntryToInstallSpec(entry: McpServerEntry): {
 } | null;
 /** Look up detailed info for an MCP server by exact name. */
 export declare function getMcpServerInfo(serverName: string, registryName?: string): Promise<McpServerEntry | null>;
+/** One row of a skill index document. */
+export interface SkillIndexEntry {
+    name: string;
+    description?: string;
+    source?: string;
+    identifier?: string;
+    trust_level?: string;
+    repo?: string;
+    path?: string;
+    tags?: string[];
+    author?: string;
+    installs?: number;
+    /** Lowercase hex sha256 of the skill's SKILL.md — written by `agents publish`. */
+    sha256?: string;
+}
+/** Raw shape of the skill index document served by Hermes and compatible registries. */
+export interface SkillIndexDocument {
+    version?: number;
+    generated_at?: string;
+    skill_count?: number;
+    skills: SkillIndexEntry[];
+}
+/** Map a raw skill-index row into the canonical SkillEntry shape. */
+export declare function normalizeSkillEntry(raw: SkillIndexEntry): SkillEntry;
 /** Search skill registries for entries matching a query string. */
 export declare function searchSkillRegistries(query: string, options?: {
     registry?: string;
@@ -66,3 +90,34 @@ export declare function parsePackageIdentifier(identifier: string): {
 };
 /** Resolve a package identifier to an installable package with source metadata. */
 export declare function resolvePackage(identifier: string): Promise<ResolvedPackage | null>;
+/** Lowercase hex sha256 of a file's bytes. Small files only (SKILL.md). */
+export declare function sha256OfFile(file: string): string;
+/**
+ * Parse an 'owner/repo' slug from a git remote URL (https or scp-style ssh).
+ * Returns null if the URL is not a recognizable GitHub-style remote.
+ */
+export declare function parseOwnerRepoFromRemote(remoteUrl: string): string | null;
+/**
+ * Walk a repo's skills/ and build a flat {@link SkillIndexDocument}. Each entry
+ * carries the sha256 of its SKILL.md so install can verify integrity after
+ * cloning — this is the artifact `agents publish` commits + pushes.
+ *
+ * `repoSlug` is the 'owner/repo' the skills are published under, written into
+ * each entry's `repo` field so {@link skillEntryToGitSource} resolves it to
+ * `gh:owner/repo`. `identifier` is set to the skill's directory name so
+ * `agents install skill:<name>` resolves against this index.
+ */
+export declare function buildSkillIndex(repoPath: string, repoSlug: string, opts?: {
+    generatedAt?: string;
+}): SkillIndexDocument;
+/**
+ * Verify a cloned skill's SKILL.md against the sha256 recorded in its registry
+ * entry. Returns ok when the entry carries no sha256 — indexes published before
+ * integrity hashes (or by third parties) simply skip the check. Returns an
+ * error when the file is missing or its hash differs, so install can abort
+ * rather than silently trusting a tampered artifact.
+ */
+export declare function verifySkillIntegrity(repoPath: string, entry: Pick<SkillEntry, 'name' | 'path' | 'sha256'>): {
+    ok: boolean;
+    error?: string;
+};