@phnx-labs/agents-cli 1.20.61 → 1.20.63

package/dist/lib/browser/sessions-list.js

@@ -0,0 +1,190 @@
+/**
+ * Read-only listing of a browser profile's on-disk captures — screenshots, PDFs,
+ * recordings (`<profile>/sessions/<task>/`) and downloads (`<profile>/downloads/`).
+ * Reads straight from `.cache/browser/<profile>/`, so it works whether or not the
+ * browser daemon is running. Backs both `agents browser sessions` and the
+ * `agents sessions --browser` alias.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+import { getBrowserRuntimeDir, getProfileRuntimeDir } from './profiles.js';
+import { formatRelativeTime } from '../session/relative-time.js';
+const EXT_KIND = {
+    '.png': 'screenshot',
+    '.jpg': 'screenshot',
+    '.jpeg': 'screenshot',
+    '.webp': 'screenshot',
+    '.pdf': 'pdf',
+    '.webm': 'recording',
+};
+function statSafe(p) {
+    try {
+        return fs.statSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+function walkFiles(dir) {
+    let out = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory())
+            out = out.concat(walkFiles(full));
+        else if (e.isFile())
+            out.push(full);
+    }
+    return out;
+}
+/** Every capture for one profile, newest first. */
+export function listProfileArtifacts(profile) {
+    const root = getProfileRuntimeDir(profile);
+    const artifacts = [];
+    const sessionsRoot = path.join(root, 'sessions');
+    let taskDirs = [];
+    try {
+        taskDirs = fs.readdirSync(sessionsRoot, { withFileTypes: true });
+    }
+    catch { /* none */ }
+    for (const t of taskDirs) {
+        if (!t.isDirectory())
+            continue;
+        for (const file of walkFiles(path.join(sessionsRoot, t.name))) {
+            const kind = EXT_KIND[path.extname(file).toLowerCase()];
+            if (!kind)
+                continue;
+            const st = statSafe(file);
+            if (!st)
+                continue;
+            artifacts.push({ kind, task: t.name, name: path.basename(file), path: file, bytes: st.size, mtimeMs: st.mtimeMs });
+        }
+    }
+    for (const file of walkFiles(path.join(root, 'downloads'))) {
+        const st = statSafe(file);
+        if (!st)
+            continue;
+        artifacts.push({ kind: 'download', name: path.basename(file), path: file, bytes: st.size, mtimeMs: st.mtimeMs });
+    }
+    artifacts.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return artifacts;
+}
+/**
+ * Captures grouped by profile. With `only` set, returns just that profile (even
+ * when empty); otherwise every profile dir on disk that has at least one capture.
+ */
+export function listBrowserSessions(only) {
+    let profiles;
+    if (only) {
+        profiles = [only];
+    }
+    else {
+        try {
+            profiles = fs.readdirSync(getBrowserRuntimeDir(), { withFileTypes: true })
+                .filter((e) => e.isDirectory() && e.name !== 'sessions')
+                .map((e) => e.name)
+                .sort();
+        }
+        catch {
+            profiles = [];
+        }
+    }
+    return profiles
+        .map((p) => ({ profile: p, artifacts: listProfileArtifacts(p) }))
+        .filter((r) => !!only || r.artifacts.length > 0);
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    const units = ['KB', 'MB', 'GB'];
+    let val = n / 1024;
+    let i = 0;
+    while (val >= 1024 && i < units.length - 1) {
+        val /= 1024;
+        i++;
+    }
+    return `${val < 10 ? val.toFixed(1) : Math.round(val)} ${units[i]}`;
+}
+/** Human table for the CLI. Returns lines (no trailing newline). */
+export function renderBrowserSessions(groups) {
+    if (groups.length === 0)
+        return 'No browser profiles found.';
+    const lines = [];
+    for (const g of groups) {
+        const counts = { screenshot: 0, pdf: 0, recording: 0, download: 0 };
+        for (const a of g.artifacts)
+            counts[a.kind]++;
+        lines.push(`${g.profile}  ` +
+            `screenshots ${counts.screenshot}  pdfs ${counts.pdf}  recordings ${counts.recording}  downloads ${counts.download}`);
+        if (g.artifacts.length === 0) {
+            lines.push('  (no captures yet)');
+            continue;
+        }
+        for (const a of g.artifacts) {
+            const when = formatRelativeTime(new Date(a.mtimeMs).toISOString());
+            const where = a.kind === 'download' ? 'downloads/' : `sessions/${a.task}/`;
+            lines.push(`  ${when.padEnd(12)}  ${a.name.padEnd(28)}  ${formatBytes(a.bytes).padStart(8)}  ${where}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Resolve `--open <sel>`: `latest` (newest across the groups) or a filename
+ * substring match. Returns the absolute path, or null if nothing matched.
+ */
+export function resolveArtifact(groups, selector) {
+    const all = groups.flatMap((g) => g.artifacts).sort((a, b) => b.mtimeMs - a.mtimeMs);
+    if (all.length === 0)
+        return null;
+    if (selector === 'latest')
+        return all[0].path;
+    const hit = all.find((a) => a.name === selector) ?? all.find((a) => a.name.includes(selector));
+    return hit ? hit.path : null;
+}
+/** Open a file in the OS default app. Returns true on success. */
+export function openArtifact(filePath) {
+    const openers = process.platform === 'darwin'
+        ? [['open', [filePath]]]
+        : process.platform === 'win32'
+            ? [['cmd', ['/c', 'start', '""', filePath]]]
+            : [['xdg-open', [filePath]], ['gnome-open', [filePath]]];
+    for (const [cmd, args] of openers) {
+        if (spawnSync(cmd, args, { stdio: 'ignore' }).status === 0)
+            return true;
+    }
+    return false;
+}
+/**
+ * Shared CLI action for `agents browser sessions` and `agents sessions --browser`.
+ * `open` is the Commander value for `--open [selector]`: undefined when the flag
+ * is absent, `true` when passed bare (defaults to 'latest'), or the selector string.
+ */
+export function runBrowserSessions(opts) {
+    const groups = listBrowserSessions(opts.profile);
+    if (opts.open !== undefined && opts.open !== false) {
+        const selector = opts.open === true ? 'latest' : opts.open;
+        const target = resolveArtifact(groups, selector);
+        if (!target) {
+            console.error(`No capture matching "${selector}".`);
+            process.exit(1);
+        }
+        console.log(target);
+        if (!openArtifact(target)) {
+            console.error(`Could not open ${target}`);
+            process.exit(1);
+        }
+        return;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(groups, null, 2));
+        return;
+    }
+    console.log(renderBrowserSessions(groups));
+}

package/dist/lib/commands.js

@@ -15,6 +15,7 @@ import { markdownToToml } from './convert.js';
 import { getCommandsDir, getUserCommandsDir, getEnabledExtraRepos, getProjectAgentsDir, getSkillsDir, getTrashCommandsDir } from './state.js';
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions, resolveVersion } from './versions.js';
 import { commandSkillMatches, installCommandSkillToVersion, listCommandSkillsInVersion, removeCommandSkillFromVersion, shouldInstallCommandAsSkill, } from './command-skills.js';
+import { installGooseCommandToVersion, listGooseCommandsInVersion, gooseCommandMatches, removeGooseCommandFromVersion, } from './goose-commands.js';
 function compareVersions(a, b) {
     const aParts = a.split('.').map((n) => parseInt(n, 10) || 0);
     const bParts = b.split('.').map((n) => parseInt(n, 10) || 0);
@@ -209,6 +210,19 @@ export function installCommand(sourcePath, agentId, commandName, method = 'symli
     const agent = AGENTS[agentId];
     ensureCommandsDir(agentId);
     const home = getEffectiveHome(agentId);
+    // Goose: a slash command is a recipe YAML registered in config.yaml, not a
+    // native command file under commandsSubdir.
+    if (agentId === 'goose') {
+        const result = installGooseCommandToVersion(home, commandName, sourcePath);
+        if (!result.success) {
+            return { path: '', method: 'copy', error: result.error, warnings: validation.warnings };
+        }
+        return {
+            path: path.join(home, '.config', 'goose', 'commands', `${commandName}.yaml`),
+            method: 'copy',
+            warnings: validation.warnings,
+        };
+    }
     const commandsDir = path.join(home, agentConfigDirName(agentId), agent.commandsSubdir);
     fs.mkdirSync(commandsDir, { recursive: true });
     const ext = agent.format === 'toml' ? '.toml' : '.md';
@@ -248,6 +262,9 @@ export function listCommandsInVersionHome(agent, version) {
     if (shouldInstallCommandAsSkill(agent, version)) {
         return listCommandSkillsInVersion(agentDir);
     }
+    if (agent === 'goose') {
+        return listGooseCommandsInVersion(versionHome);
+    }
     const dir = getVersionCommandsDir(agent, version);
     if (!fs.existsSync(dir))
         return [];
@@ -270,6 +287,9 @@ function versionCommandMatches(agent, version, commandName) {
     if (shouldInstallCommandAsSkill(agent, version)) {
         return commandSkillMatches(agentDir, commandName, sourcePath);
     }
+    if (agent === 'goose') {
+        return gooseCommandMatches(versionHome, commandName, sourcePath);
+    }
     const agentConfig = AGENTS[agent];
     const ext = agentConfig.format === 'toml' ? '.toml' : '.md';
     const installedPath = path.join(getVersionCommandsDir(agent, version), `${commandName}${ext}`);
@@ -357,6 +377,11 @@ export function installCommandToVersion(agent, version, commandName, method = 'c
             ...getEnabledExtraRepos().map((repo) => path.join(repo.dir, 'skills')),
         ]);
     }
+    // Goose: a slash command is a recipe YAML registered in config.yaml, not a
+    // native command file. Write the recipe + slash_commands entry.
+    if (agent === 'goose') {
+        return installGooseCommandToVersion(versionHome, commandName, sourcePath);
+    }
     const agentConfig = AGENTS[agent];
     const commandsDir = getVersionCommandsDir(agent, version);
     fs.mkdirSync(commandsDir, { recursive: true });
@@ -392,6 +417,10 @@ export function removeCommandFromVersion(agent, version, commandName) {
     if (shouldInstallCommandAsSkill(agent, version)) {
         return removeCommandSkillFromVersion(agentDir, commandName);
     }
+    if (agent === 'goose') {
+        const trashDir = path.join(getTrashCommandsDir(), agent, version, commandName);
+        return removeGooseCommandFromVersion(versionHome, commandName, trashDir);
+    }
     const ext = AGENTS[agent].format === 'toml' ? '.toml' : '.md';
     const targetPath = path.join(getVersionCommandsDir(agent, version), `${commandName}${ext}`);
     if (!fs.existsSync(targetPath) && !fs.lstatSync(targetPath, { throwIfNoEntry: false })) {

package/dist/lib/convert.d.ts

@@ -16,5 +16,16 @@ export declare function parseMarkdownFrontmatter(content: string): {
 };
 /** Convert a Markdown command file to Gemini's TOML format, translating $ARGUMENTS to {{args}}. */
 export declare function markdownToToml(skillName: string, markdown: string): string;
+/**
+ * Convert a Markdown command file to a Goose recipe YAML object.
+ *
+ * Goose has no native slash-command file format — a slash command is a recipe
+ * (registered in `config.yaml` under `slash_commands`). The recipe schema matches
+ * the one agents-cli already emits for Goose workflow/subagent recipes:
+ * `version`, `title`, `description`, `instructions`, `prompt`. The Markdown body
+ * (with `$ARGUMENTS` preserved) becomes both `instructions` and `prompt`.
+ * Returns a plain object so the caller can `yaml.stringify` it.
+ */
+export declare function markdownToGooseRecipe(commandName: string, markdown: string): Record<string, unknown>;
 /** Convert a Gemini TOML command file back to Markdown format, translating {{args}} to $ARGUMENTS. */
 export declare function tomlToMarkdown(toml: string): string;

package/dist/lib/convert.js

@@ -40,6 +40,28 @@ export function markdownToToml(skillName, markdown) {
     ];
     return lines.join('\n');
 }
+/**
+ * Convert a Markdown command file to a Goose recipe YAML object.
+ *
+ * Goose has no native slash-command file format — a slash command is a recipe
+ * (registered in `config.yaml` under `slash_commands`). The recipe schema matches
+ * the one agents-cli already emits for Goose workflow/subagent recipes:
+ * `version`, `title`, `description`, `instructions`, `prompt`. The Markdown body
+ * (with `$ARGUMENTS` preserved) becomes both `instructions` and `prompt`.
+ * Returns a plain object so the caller can `yaml.stringify` it.
+ */
+export function markdownToGooseRecipe(commandName, markdown) {
+    const { frontmatter, body } = parseMarkdownFrontmatter(markdown);
+    const description = frontmatter.description || `Run ${commandName} command`;
+    const prompt = body.trim() || description;
+    return {
+        version: '1.0.0',
+        title: commandName,
+        description,
+        instructions: prompt,
+        prompt,
+    };
+}
 /** Convert a Gemini TOML command file back to Markdown format, translating {{args}} to $ARGUMENTS. */
 export function tomlToMarkdown(toml) {
     const nameMatch = toml.match(/name\s*=\s*"([^"]+)"/);

package/dist/lib/daemon.js

@@ -419,6 +419,8 @@ export async function runDaemon() {
                 log('INFO', `sessions sync: pushed ${r.pushed}, pulled ${r.pulled}, merged ${r.merged}` +
                     (r.errors.length ? `, ${r.errors.length} error(s): ${r.errors[0]}` : ''));
             }
+            if (r.warnings.length)
+                log('WARN', `sessions sync: ${r.warnings[0]}`);
         }
         catch (err) {
             log('ERROR', `sessions sync failed: ${err.message}`);

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

@@ -0,0 +1,62 @@
+/**
+ * Fleet-wide device operations — pick online targets and run a command on each.
+ *
+ * Used by `agents fleet update` / `agents fleet run` (aliases of the same
+ * subcommands under `agents devices`). Offline devices are skipped with a
+ * reason so a single dead node never blocks the rest of the rollout. Per-device
+ * throws (misconfigured auth, etc.) become `failed` rows — they never abort
+ * the remaining devices.
+ */
+import type { DeviceProfile, DeviceRegistry } from './registry.js';
+export type FleetSkipReason = 'offline' | 'no-address';
+/** npm dist-tags / semver pins only — rejects shell metacharacters. */
+export declare const FLEET_VERSION_RE: RegExp;
+export interface FleetTarget {
+    device: DeviceProfile;
+    /** When set, this device is not reached (skip with reason). */
+    skip?: FleetSkipReason;
+}
+export interface FleetRunResult {
+    name: string;
+    status: 'ok' | 'failed' | 'skipped';
+    code: number | null;
+    reason?: FleetSkipReason | string;
+    /** Truncated combined stderr/stdout for failures. */
+    detail?: string;
+}
+/**
+ * Classify each registered device for a fleet operation.
+ *
+ * - Tailscale-offline → skip `offline`
+ * - No address → skip `no-address`
+ * - Everything else is a target (including this machine, reached over ssh when
+ *   it has a registry address — same path as any other box).
+ */
+export declare function planFleetTargets(reg: DeviceRegistry): FleetTarget[];
+/** Human label for a skip reason. */
+export declare function skipLabel(reason: FleetSkipReason): string;
+/**
+ * Run `cmd` on one device via the same ssh path as `agents ssh <name> …`.
+ * Captures stdout/stderr (not inherited) so the fleet table can summarize.
+ * Throws from buildSshInvocation are returned as a non-zero result so a single
+ * misconfigured device cannot abort the fleet loop.
+ */
+export declare function runOnDevice(device: DeviceProfile, cmd: string[], opts?: {
+    timeoutMs?: number;
+}): {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+};
+/**
+ * Build `agents upgrade --yes` argv, optionally pinned to a version/dist-tag.
+ * Rejects anything that is not a plain npm version/tag token so a version pin
+ * cannot inject shell metacharacters into the remote command line.
+ */
+export declare function upgradeCommand(version?: string): string[];
+/**
+ * Execute a command across planned targets. Pure orchestration over
+ * {@link runOnDevice}; testable by injecting `runner`. Per-device throws from
+ * the runner are recorded as `failed` so one bad device never aborts the rest.
+ */
+export declare function runFleet(targets: FleetTarget[], cmd: string[], runner?: typeof runOnDevice): FleetRunResult[];

package/dist/lib/devices/fleet.js

@@ -0,0 +1,128 @@
+/**
+ * Fleet-wide device operations — pick online targets and run a command on each.
+ *
+ * Used by `agents fleet update` / `agents fleet run` (aliases of the same
+ * subcommands under `agents devices`). Offline devices are skipped with a
+ * reason so a single dead node never blocks the rest of the rollout. Per-device
+ * throws (misconfigured auth, etc.) become `failed` rows — they never abort
+ * the remaining devices.
+ */
+import { spawnSync } from 'child_process';
+import { buildSshInvocation, sshTargetFor, writeAskpassShim } from './connect.js';
+/** npm dist-tags / semver pins only — rejects shell metacharacters. */
+export const FLEET_VERSION_RE = /^[A-Za-z0-9._-]+$/;
+/**
+ * Classify each registered device for a fleet operation.
+ *
+ * - Tailscale-offline → skip `offline`
+ * - No address → skip `no-address`
+ * - Everything else is a target (including this machine, reached over ssh when
+ *   it has a registry address — same path as any other box).
+ */
+export function planFleetTargets(reg) {
+    const names = Object.keys(reg).sort();
+    return names.map((name) => {
+        const device = reg[name];
+        if (device.tailscale && !device.tailscale.online) {
+            return { device, skip: 'offline' };
+        }
+        try {
+            sshTargetFor(device);
+        }
+        catch {
+            return { device, skip: 'no-address' };
+        }
+        return { device };
+    });
+}
+/** Human label for a skip reason. */
+export function skipLabel(reason) {
+    switch (reason) {
+        case 'offline':
+            return 'offline';
+        case 'no-address':
+            return 'no address';
+    }
+}
+/**
+ * Run `cmd` on one device via the same ssh path as `agents ssh <name> …`.
+ * Captures stdout/stderr (not inherited) so the fleet table can summarize.
+ * Throws from buildSshInvocation are returned as a non-zero result so a single
+ * misconfigured device cannot abort the fleet loop.
+ */
+export function runOnDevice(device, cmd, opts = {}) {
+    try {
+        const shim = writeAskpassShim();
+        const { args, env } = buildSshInvocation(device, cmd, shim);
+        const res = spawnSync('ssh', args, {
+            encoding: 'utf-8',
+            env: { ...process.env, ...env },
+            timeout: opts.timeoutMs ?? 600_000,
+        });
+        return {
+            code: res.status,
+            stdout: res.stdout?.toString() ?? '',
+            stderr: (res.stderr?.toString() ?? '') + (res.error ? String(res.error.message) : ''),
+        };
+    }
+    catch (err) {
+        return {
+            code: 1,
+            stdout: '',
+            stderr: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Build `agents upgrade --yes` argv, optionally pinned to a version/dist-tag.
+ * Rejects anything that is not a plain npm version/tag token so a version pin
+ * cannot inject shell metacharacters into the remote command line.
+ */
+export function upgradeCommand(version) {
+    if (version !== undefined && version !== '') {
+        if (!FLEET_VERSION_RE.test(version)) {
+            throw new Error(`Invalid version '${version}'. Use a semver or dist-tag (letters, digits, . _ - only).`);
+        }
+        return ['agents', 'upgrade', version, '--yes'];
+    }
+    return ['agents', 'upgrade', '--yes'];
+}
+/**
+ * Execute a command across planned targets. Pure orchestration over
+ * {@link runOnDevice}; testable by injecting `runner`. Per-device throws from
+ * the runner are recorded as `failed` so one bad device never aborts the rest.
+ */
+export function runFleet(targets, cmd, runner = runOnDevice) {
+    const results = [];
+    for (const t of targets) {
+        if (t.skip) {
+            results.push({
+                name: t.device.name,
+                status: 'skipped',
+                code: null,
+                reason: t.skip,
+            });
+            continue;
+        }
+        try {
+            const res = runner(t.device, cmd);
+            const ok = res.code === 0;
+            const detail = (res.stderr || res.stdout).trim().slice(0, 200);
+            results.push({
+                name: t.device.name,
+                status: ok ? 'ok' : 'failed',
+                code: res.code,
+                detail: ok ? undefined : detail || undefined,
+            });
+        }
+        catch (err) {
+            results.push({
+                name: t.device.name,
+                status: 'failed',
+                code: 1,
+                detail: (err instanceof Error ? err.message : String(err)).slice(0, 200),
+            });
+        }
+    }
+    return results;
+}

package/dist/lib/doctor-diff.js

@@ -30,6 +30,7 @@ import { markdownToToml } from './convert.js';
 import { resolveImports, supportsRulesImports } from './rules/compile.js';
 import { listCommandsInVersionHome, getVersionCommandsDir } from './commands.js';
 import { shouldInstallCommandAsSkill, commandSkillMatches, commandSkillName } from './command-skills.js';
+import { gooseCommandMatches, gooseCommandsDir } from './goose-commands.js';
 import { supports } from './capabilities.js';
 import { listSkillsInVersionHome, getVersionSkillsDir } from './skills.js';
 import { listHooksInVersionHome, listHookEntriesFromDir } from './hooks.js';
@@ -141,6 +142,19 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
             });
             continue;
         }
+        if (agent === 'goose') {
+            // Compare against the installed Goose recipe YAML + slash_commands registration.
+            const matches = gooseCommandMatches(getVersionHomePath(agent, version), name, src.path);
+            rows.push({
+                kind: 'commands',
+                name,
+                status: matches ? 'ok' : 'diff',
+                source: src.layer,
+                sourcePath: src.path,
+                homePath: path.join(gooseCommandsDir(getVersionHomePath(agent, version)), `${name}.yaml`),
+            });
+            continue;
+        }
         const homePath = path.join(homeDir, `${name}${ext}`);
         const installedContent = readSafe(homePath);
         const sourceContent = readSafe(src.path);
@@ -164,7 +178,9 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
             continue;
         const extraHome = asSkill
             ? path.join(agentDir, 'skills', commandSkillName(name), 'SKILL.md')
-            : path.join(homeDir, `${name}${ext}`);
+            : agent === 'goose'
+                ? path.join(gooseCommandsDir(getVersionHomePath(agent, version)), `${name}.yaml`)
+                : path.join(homeDir, `${name}${ext}`);
         rows.push({ kind: 'commands', name, status: 'extra', homePath: extraHome });
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));

package/dist/lib/funnel.d.ts

@@ -0,0 +1,5 @@
+export declare const FUNNEL_PORTS: readonly [443, 8443, 10000];
+export type FunnelPort = typeof FUNNEL_PORTS[number];
+export declare function parseFunnelPort(value: string | number): FunnelPort;
+export declare function buildFunnelStatusCommand(): string;
+export declare function buildFunnelUpCommand(publicPort: FunnelPort, localPort: number): string;

package/dist/lib/funnel.js

@@ -0,0 +1,23 @@
+import { shellQuote } from './ssh-exec.js';
+export const FUNNEL_PORTS = [443, 8443, 10000];
+export function parseFunnelPort(value) {
+    const port = typeof value === 'number' ? value : Number.parseInt(value, 10);
+    if (FUNNEL_PORTS.includes(port))
+        return port;
+    throw new Error(`Tailscale Funnel public port must be one of: ${FUNNEL_PORTS.join(', ')}`);
+}
+export function buildFunnelStatusCommand() {
+    return 'tailscale funnel status';
+}
+export function buildFunnelUpCommand(publicPort, localPort) {
+    if (!Number.isInteger(localPort) || localPort <= 0 || localPort > 65535) {
+        throw new Error('Local port must be between 1 and 65535');
+    }
+    return [
+        'tailscale',
+        'funnel',
+        '--bg',
+        `--https=${publicPort}`,
+        `http://localhost:${localPort}`,
+    ].map(shellQuote).join(' ');
+}

package/dist/lib/git.d.ts

@@ -76,13 +76,24 @@ export declare function setRemoteUrl(repoPath: string, url: string): Promise<voi
  * Check if a GitHub repo exists.
  */
 export declare function checkGitHubRepoExists(owner: string, repo: string): Promise<boolean>;
-/**
- * Commit and push changes in a repo.
- */
-export declare function commitAndPush(repoPath: string, message: string): Promise<{
+/** Result of {@link commitAndPush}. */
+export type CommitAndPushResult = {
     success: boolean;
     error?: string;
-}>;
+    /** Human detail for success: "already up to date", "pushed abc..def", "committed and pushed …". */
+    detail?: string;
+    branch?: string;
+    committed?: boolean;
+    pushed?: boolean;
+};
+/**
+ * Commit (if dirty) and push a repo.
+ *
+ * Clean tree + local ahead of origin still pushes — "nothing to commit" is not
+ * "nothing to push". Reports "already up to date" only when `ahead === 0` and
+ * there is nothing to commit.
+ */
+export declare function commitAndPush(repoPath: string, message: string): Promise<CommitAndPushResult>;
 /**
  * Check if repo has uncommitted changes.
  */
@@ -166,11 +177,16 @@ export declare function displayHomePath(dir: string): string;
 /**
  * Pull changes in an existing repo.
  * Refuses to pull if the working tree is dirty -- user must commit or discard changes first.
+ *
+ * Uses `git pull --rebase` (same strategy as {@link syncRepoGit}) so a diverged
+ * branch reconciles instead of failing with "Need to specify how to reconcile
+ * divergent branches".
  */
 export declare function pullRepo(dir: string): Promise<{
     success: boolean;
     commit: string;
     error?: string;
+    branch?: string;
 }>;
 /**
  * Rebase a repo onto its remote, optionally pushing local commits back up.