@ishlabs/cli 0.8.5 → 0.10.0

package/dist/connect.js

@@ -2,11 +2,11 @@
  * Localhost connect CLI — wraps cloudflared and registers with Ish backend.
  */
 import { spawn, execSync } from "node:child_process";
-import { existsSync, mkdirSync, chmodSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, chmodSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { loadConfig, saveConfig } from "./config.js";
 import { refreshTokens, isTokenExpired, decodeJwtExp, AuthRefreshPermanentError } from "./auth.js";
-import { binDir, cloudflaredBin, simulationsDir } from "./lib/paths.js";
+import { binDir, cloudflaredBin, simulationsDir, connectLockPath, ishDir } from "./lib/paths.js";
 import { c } from "./lib/colors.js";
 const TUNNEL_URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
 const HEARTBEAT_INTERVAL = 10_000;
@@ -233,8 +233,14 @@ async function resolveToken(tokenArg, apiUrl, tokenFileArg) {
         let accessToken = config.access_token;
         // Refresh if expired or close to expiry
         if (isTokenExpired(accessToken)) {
+            if (!config.oauth_client_id) {
+                throw new Error('Saved tokens are missing oauth_client_id. Run "ish login" to re-authenticate.');
+            }
             try {
-                const tokens = await refreshTokens(config.refresh_token);
+                const tokens = await refreshTokens(config.refresh_token, {
+                    accessToken,
+                    clientId: config.oauth_client_id,
+                });
                 accessToken = tokens.accessToken;
                 config.access_token = tokens.accessToken;
                 config.refresh_token = tokens.refreshToken;
@@ -250,7 +256,12 @@ async function resolveToken(tokenArg, apiUrl, tokenFileArg) {
                 const cfg = loadConfig();
                 if (!cfg.refresh_token)
                     throw new Error("No refresh token");
-                const tokens = await refreshTokens(cfg.refresh_token);
+                if (!cfg.oauth_client_id)
+                    throw new Error('Missing oauth_client_id; run "ish login" again.');
+                const tokens = await refreshTokens(cfg.refresh_token, {
+                    accessToken: cfg.access_token,
+                    clientId: cfg.oauth_client_id,
+                });
                 cfg.access_token = tokens.accessToken;
                 cfg.refresh_token = tokens.refreshToken;
                 saveConfig(cfg);
@@ -382,25 +393,48 @@ function startCloudflared(port, binPath, json) {
 }
 // --- API calls ---
 async function registerTunnel(apiUrl, token, tunnelUrl, port) {
-    try {
-        const resp = await fetch(`${apiUrl}${API_BASE}/connect`, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${token}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({ tunnel_url: tunnelUrl, local_port: port }),
-            signal: AbortSignal.timeout(10_000),
-        });
-        if (!resp.ok)
-            throw new Error(`HTTP ${resp.status}`);
-        return true;
-    }
-    catch (e) {
-        console.error(`Warning: Failed to register connection: ${e}`);
-        console.error("Connection is still active — you can retry manually.");
-        return false;
+    // M6 / Pattern G: registration sometimes 5xxs / 404s on the first POST
+    // after a backend bounce or a routing-cache miss; the previous
+    // single-shot attempt left `--detach` clients writing the lock with
+    // `registered: false`, then the heartbeat would 404 and burn through
+    // the 3-strike countdown. Retry up to 4 times with exponential backoff
+    // (~0.5s + 1s + 2s + 4s = ~7.5s of wall time worst-case) before
+    // giving up. 4xx other than 404/408/429 fail fast — they're permanent.
+    const maxAttempts = 4;
+    let lastErr;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        if (attempt > 0) {
+            const delayMs = Math.min(4_000, 500 * Math.pow(2, attempt - 1));
+            await new Promise((r) => setTimeout(r, delayMs));
+        }
+        try {
+            const resp = await fetch(`${apiUrl}${API_BASE}/connect`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({ tunnel_url: tunnelUrl, local_port: port }),
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (resp.ok)
+                return true;
+            // 4xx (except 404/408/429) are permanent — don't keep retrying.
+            if (resp.status >= 400 && resp.status < 500
+                && resp.status !== 404 && resp.status !== 408 && resp.status !== 429) {
+                console.error(`Warning: Failed to register connection: HTTP ${resp.status}`);
+                console.error("Connection is still active — you can retry manually.");
+                return false;
+            }
+            lastErr = new Error(`HTTP ${resp.status}`);
+        }
+        catch (e) {
+            lastErr = e;
+        }
     }
+    console.error(`Warning: Failed to register connection after ${maxAttempts} attempts: ${lastErr}`);
+    console.error("Connection is still active — you can retry manually.");
+    return false;
 }
 /**
  * Best-effort deregister. When `suppressAuthFailures` is true (we're already
@@ -463,9 +497,21 @@ function processHeartbeatResponse(resp, renderCards) {
         // Non-fatal: response parsing failed, silently continue
     });
 }
-function startHeartbeat(apiUrl, getToken, doRefresh, onTokenRefreshed, onFatal, onAuthPermanent, json) {
+function startHeartbeat(apiUrl, getToken, doRefresh, onTokenRefreshed, onFatal, onAuthPermanent, json, reRegister) {
     let consecutiveFailures = 0;
     let stopped = false;
+    // D1 / PC-M2: track repeated 404→re-register cycles. If the backend
+    // keeps forgetting the registration between heartbeats (route bug,
+    // misconfigured DB, racing supervisor, etc.) we'd loop forever
+    // because every successful re-register resets the strike counter.
+    // After REREGISTER_CYCLE_BUDGET cycles, log a clear diagnostic and
+    // stop the strike countdown — the tunnel itself is still healthy,
+    // it just isn't being recognised by the backend's heartbeat path.
+    // The user / agent gets a single actionable message instead of a
+    // loop spamming "Tunnel registration restored." every 10s.
+    let reRegisterCycles = 0;
+    let reRegisterDiagnosticPrinted = false;
+    const REREGISTER_CYCLE_BUDGET = 6;
     const interval = setInterval(async () => {
         if (stopped)
             return;
@@ -475,6 +521,34 @@ function startHeartbeat(apiUrl, getToken, doRefresh, onTokenRefreshed, onFatal,
                 headers: { Authorization: `Bearer ${getToken()}` },
                 signal: AbortSignal.timeout(10_000),
             });
+            // M6 / Pattern G: a 404 here means the backend forgot the
+            // tunnel registration (cache miss, restart, or the original
+            // POST /connect raced with a backend bounce). Re-register and
+            // reset the strike count rather than counting it as a failure
+            // — `cfProcess` is still healthy, the *registration* is the
+            // soft state that needs repair.
+            if (resp.status === 404 && reRegister) {
+                reRegisterCycles += 1;
+                const ok = await reRegister();
+                if (ok) {
+                    consecutiveFailures = 0;
+                    // First few cycles are normal (transient backend hiccup).
+                    // After the budget, the route or registration model is
+                    // fundamentally broken — keep the tunnel up but say so.
+                    if (reRegisterCycles >= REREGISTER_CYCLE_BUDGET && !reRegisterDiagnosticPrinted) {
+                        reRegisterDiagnosticPrinted = true;
+                        console.error(`Notice: heartbeat path /api/v1/connect/heartbeat is repeatedly 404'ing despite successful re-registration ` +
+                            `(${reRegisterCycles} cycles). Backend appears to drop the active connection between heartbeats. ` +
+                            `Tunnel + cloudflared are still healthy; subsequent simulations may still hit TunnelInactive on dispatch. ` +
+                            `Investigate the backend's /connect route or restart the API service.`);
+                    }
+                    else if (!json) {
+                        console.error("Tunnel registration restored.");
+                    }
+                    return;
+                }
+                // Fall through to the strike-count path if re-register fails.
+            }
             // If 401 and we can refresh, try once
             if (resp.status === 401 && doRefresh) {
                 try {
@@ -645,13 +719,15 @@ export async function runTunnel(port, tokenArg, apiUrlArg, tokenFileArg, outputO
         }
         await deregisterTunnel(apiUrl, currentToken, json, true);
         cfProcess.kill();
+        clearLock();
         process.exit(3);
     };
     heartbeat = startHeartbeat(apiUrl, () => currentToken, serializedRefresh, onTokenRefreshed, async () => {
         await deregisterTunnel(apiUrl, currentToken, json);
         cfProcess.kill();
+        clearLock();
         process.exit(1);
-    }, onAuthPermanent, json);
+    }, onAuthPermanent, json, () => registerTunnel(apiUrl, currentToken, tunnelUrl, port));
     proactiveRefresh = scheduleProactiveRefresh(currentToken, serializedRefresh, onTokenRefreshed, onAuthPermanent, json);
     const shutdown = async () => {
         if (shuttingDown)
@@ -663,6 +739,7 @@ export async function runTunnel(port, tokenArg, apiUrlArg, tokenFileArg, outputO
         proactiveRefresh?.stop();
         cfProcess.kill();
         await deregisterTunnel(apiUrl, currentToken, json);
+        clearLock();
         process.exit(0);
     };
     process.on("SIGINT", shutdown);
@@ -675,7 +752,265 @@ export async function runTunnel(port, tokenArg, apiUrlArg, tokenFileArg, outputO
             heartbeat?.stop();
             proactiveRefresh?.stop();
             await deregisterTunnel(apiUrl, currentToken, json);
+            clearLock();
             process.exit(0);
         }
     });
+    // Detached mode: when this process was spawned by `connect --detach`, the
+    // parent needs the registration confirmation we already emitted as a
+    // {status:"connected", ...} line on stdout. Write the lock file now so
+    // `ish connect status` and `ish disconnect` can find this PID.
+    if (process.env.ISH_CONNECT_DETACHED === "1") {
+        writeLock({
+            pid: process.pid,
+            tunnel_url: tunnelUrl,
+            local_port: port,
+            registered_at: new Date().toISOString(),
+            api_url: apiUrl,
+        });
+    }
+}
+function writeLock(lock) {
+    mkdirSync(ishDir(), { recursive: true });
+    writeFileSync(connectLockPath(), JSON.stringify(lock, null, 2) + "\n");
+}
+function readLock() {
+    const path = connectLockPath();
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.pid !== "number")
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function clearLock() {
+    const path = connectLockPath();
+    if (existsSync(path)) {
+        try {
+            unlinkSync(path);
+        }
+        catch { /* best-effort */ }
+    }
+}
+function pidIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Detached connect — spawn a child running the same `ish connect <port>`
+// in JSON mode, wait for its first `{status:"connected", ...}` line on
+// stdout, then exit the parent. The child writes the lock file on its
+// own once detached (see ISH_CONNECT_DETACHED branch in runTunnel).
+// ---------------------------------------------------------------------------
+export async function runDetached(port, apiUrlArg, tokenArg, tokenFileArg) {
+    const existing = readLock();
+    if (existing && pidIsAlive(existing.pid)) {
+        throw new Error(`An active tunnel is already running (pid ${existing.pid}, ${existing.tunnel_url}). Run \`ish disconnect\` first.`);
+    }
+    if (existing) {
+        // Stale lock — process is gone. Clear before continuing.
+        clearLock();
+    }
+    // Re-invoke the same CLI binary with `--json connect <port>` minus
+    // `--detach`, in a detached child process so it survives this parent.
+    const exe = process.execPath;
+    const script = process.argv[1];
+    const childArgs = [];
+    // Preserve global flags the user passed at the program root (e.g.
+    // --api-url, --token-file). We rebuild minimally instead of slicing
+    // process.argv to avoid carrying --detach forward.
+    if (apiUrlArg)
+        childArgs.push("--api-url", apiUrlArg);
+    if (tokenArg)
+        childArgs.push("--token", tokenArg);
+    if (tokenFileArg)
+        childArgs.push("--token-file", tokenFileArg);
+    childArgs.push("--json", "connect", String(port));
+    const child = spawn(exe, [script, ...childArgs], {
+        detached: true,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: { ...process.env, ISH_CONNECT_DETACHED: "1" },
+    });
+    // Buffer the child's stdout until we see the connected JSON line.
+    // M6 / Pattern G: hold for `registered: true` specifically — a
+    // `registered: false` connected line means the cloudflared tunnel is
+    // up but the backend never accepted the registration POST. Returning
+    // before registration confirms used to leave the parent's reported
+    // `tunnel_url` orphaned (subsequent API calls would 404 against it),
+    // and the child's heartbeat would burn through the 3-strike countdown
+    // and exit before the agent even tried to use the URL. The child's
+    // `registerTunnel` already retries with backoff, so by the time it
+    // emits `registered: false` the situation is permanent on its end —
+    // surface it as a startup error rather than a half-success.
+    const connected = await new Promise((resolve, reject) => {
+        let buffered = "";
+        const onData = (chunk) => {
+            buffered += chunk.toString("utf-8");
+            let nl;
+            while ((nl = buffered.indexOf("\n")) !== -1) {
+                const line = buffered.slice(0, nl).trim();
+                buffered = buffered.slice(nl + 1);
+                if (!line)
+                    continue;
+                try {
+                    const parsed = JSON.parse(line);
+                    if (parsed.status === "connected" && typeof parsed.tunnel_url === "string") {
+                        if (!parsed.registered) {
+                            child.stdout?.off("data", onData);
+                            child.off("exit", onExit);
+                            reject(new Error(`Tunnel started (${parsed.tunnel_url}) but backend registration failed. ` +
+                                "Check API connectivity and re-run; the orphaned cloudflared process has been terminated."));
+                            return;
+                        }
+                        child.stdout?.off("data", onData);
+                        child.off("exit", onExit);
+                        resolve({
+                            tunnel_url: parsed.tunnel_url,
+                            registered: Boolean(parsed.registered),
+                        });
+                        return;
+                    }
+                }
+                catch {
+                    // Non-JSON line — ignore (older builds may emit progress).
+                }
+            }
+        };
+        const onExit = (code) => {
+            reject(new Error(`connect child exited before first heartbeat (code ${code ?? "?"}).`));
+        };
+        child.stdout?.on("data", onData);
+        child.on("exit", onExit);
+        // Surface child stderr so a connection failure isn't silent.
+        child.stderr?.on("data", (chunk) => {
+            process.stderr.write(chunk);
+        });
+        // Hard ceiling — cloudflared startup timeout is 30s; give the
+        // backend register call another 15s on top.
+        setTimeout(() => {
+            child.stdout?.off("data", onData);
+            child.off("exit", onExit);
+            reject(new Error("Timed out waiting for tunnel to come up."));
+        }, CLOUDFLARED_STARTUP_TIMEOUT + 15_000);
+    }).catch((err) => {
+        try {
+            child.kill();
+        }
+        catch { /* best-effort */ }
+        throw err;
+    });
+    // Detach the child from this parent so it survives. We deliberately
+    // don't unref stdio — the child's own SIGTERM handler does graceful
+    // shutdown via deregister.
+    child.unref();
+    console.log(JSON.stringify({
+        pid: child.pid,
+        tunnel_url: connected.tunnel_url,
+        registered: connected.registered,
+    }));
+}
+// ---------------------------------------------------------------------------
+// Status — read-only check of the active tunnel.
+// ---------------------------------------------------------------------------
+export function connectStatus(json) {
+    const lock = readLock();
+    if (!lock || !pidIsAlive(lock.pid)) {
+        if (lock && !pidIsAlive(lock.pid))
+            clearLock();
+        if (json) {
+            console.log(JSON.stringify({ active: false }));
+        }
+        else {
+            console.log("No active tunnel.");
+        }
+        return;
+    }
+    if (json) {
+        console.log(JSON.stringify({
+            active: true,
+            pid: lock.pid,
+            tunnel_url: lock.tunnel_url,
+            local_port: lock.local_port,
+            registered_at: lock.registered_at,
+            api_url: lock.api_url,
+        }));
+    }
+    else {
+        console.log(`Active tunnel: ${lock.tunnel_url} → http://localhost:${lock.local_port}`);
+        console.log(`  pid:           ${lock.pid}`);
+        console.log(`  registered_at: ${lock.registered_at}`);
+        console.log(`  api:           ${lock.api_url}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Disconnect — SIGTERM the tracked PID; the child's own handler does the
+// graceful deregister + cloudflared cleanup. We poll for exit, then clear
+// the lock if the child didn't already.
+// ---------------------------------------------------------------------------
+export async function disconnect(json) {
+    const lock = readLock();
+    if (!lock) {
+        if (json) {
+            console.log(JSON.stringify({ status: "no_active_tunnel" }));
+        }
+        else {
+            console.log("No active tunnel.");
+        }
+        return;
+    }
+    if (!pidIsAlive(lock.pid)) {
+        clearLock();
+        if (json) {
+            console.log(JSON.stringify({ status: "stale_lock_cleared", pid: lock.pid }));
+        }
+        else {
+            console.log(`Stale lock cleared (pid ${lock.pid} was not running).`);
+        }
+        return;
+    }
+    try {
+        process.kill(lock.pid, "SIGTERM");
+    }
+    catch (err) {
+        throw new Error(`Failed to signal pid ${lock.pid}: ${err instanceof Error ? err.message : err}`);
+    }
+    // Poll for graceful exit. The child's own shutdown handler does the
+    // backend deregister; once it exits, the lock file is the next thing
+    // we clear.
+    const deadline = Date.now() + 5_000;
+    while (Date.now() < deadline) {
+        if (!pidIsAlive(lock.pid))
+            break;
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    if (pidIsAlive(lock.pid)) {
+        // Hard fallback: if SIGTERM didn't take, escalate to SIGKILL so the
+        // user isn't left with an orphan tunnel.
+        try {
+            process.kill(lock.pid, "SIGKILL");
+        }
+        catch { /* best-effort */ }
+    }
+    clearLock();
+    if (json) {
+        console.log(JSON.stringify({
+            status: "disconnected",
+            pid: lock.pid,
+            tunnel_url: lock.tunnel_url,
+        }));
+    }
+    else {
+        console.log(`Disconnected (pid ${lock.pid}).`);
+    }
 }

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { program, Option } from "commander";
-import { runTunnel } from "./connect.js";
-import { login, getAppUrl, decodeJwtClaims } from "./auth.js";
+import { runTunnel, runDetached, connectStatus, disconnect } from "./connect.js";
+import { login, decodeJwtClaims } from "./auth.js";
 import { loadConfig, saveConfig } from "./config.js";
 import { upgrade } from "./upgrade.js";
 import { registerWorkspaceCommands } from "./commands/workspace.js";
@@ -11,8 +11,10 @@ import { registerProfileCommands } from "./commands/profile.js";
 import { registerSourceCommands } from "./commands/source.js";
 import { registerConfigCommands } from "./commands/config.js";
 import { registerAskCommands } from "./commands/ask.js";
+import { registerChatCommand } from "./commands/chat.js";
 import { registerDocsCommands } from "./commands/docs.js";
 import { registerInitCommands } from "./commands/init.js";
+import { registerSecretCommands } from "./commands/secret.js";
 import { AGENT_HELP_FOOTER } from "./lib/docs.js";
 import { runInline, EXIT_USAGE, injectGlobalWorkspaceOption } from "./lib/command-helpers.js";
 import { resolveApiUrl, resolveToken } from "./lib/auth.js";
@@ -80,14 +82,14 @@ program
 // --- Inline commands (from upstream) ---
 program
     .command("login")
-    .description("Authenticate with Ish via your browser")
+    .description("Authenticate with ish via your browser")
     .action(async (_opts, cmd) => {
     await runInline(cmd, async (globals) => {
-        const appUrl = globals.dev ? "http://localhost:3000" : getAppUrl();
-        const tokens = await login(appUrl);
+        const tokens = await login();
         const config = loadConfig();
         config.access_token = tokens.accessToken;
         config.refresh_token = tokens.refreshToken;
+        config.oauth_client_id = tokens.clientId;
         saveConfig(config);
         output({ message: "Login successful" }, globals.json);
     });
@@ -217,24 +219,58 @@ program
             console.error(`\nHint: ${payload.hint}`);
     });
 });
-program
+const connectCmd = program
     .command("connect")
     .description("Expose your localhost to Ish via a Cloudflare tunnel")
-    .argument("<port>", "Local port to connect (e.g. 3000)")
-    .addHelpText("after", "\nNote: --json emits structured one-line JSON for connected/disconnected events. --fields and --quiet have limited effect; use --json for machine-readable output.")
-    .action(async (port, _opts, cmd) => {
+    .argument("[port]", "Local port to connect (e.g. 3000)")
+    .option("--detach", "Fork after first heartbeat success; print {pid, tunnel_url, registered} JSON and exit")
+    .addHelpText("after", `
+Subcommands:
+  ish connect status         Read-only check of the active detached tunnel
+  ish disconnect             Graceful shutdown of the active detached tunnel
+
+Note: --json emits structured one-line JSON for connected/disconnected events.
+--fields and --quiet have limited effect; use --json for machine-readable output.
+
+Detach mode tracks the active tunnel in ~/.ish/connect.lock so \`ish connect
+status\` and \`ish disconnect\` can find it. Foreground (non-detached)
+connects do not write a lock — Ctrl+C is the shutdown verb in that mode.`)
+    .action(async (port, opts, cmd) => {
     await runInline(cmd, async (globals) => {
+        if (!port) {
+            throw new Error("Pass a port: `ish connect <port>` (e.g. `ish connect 3000`).");
+        }
         const portNum = parseInt(port, 10);
         if (isNaN(portNum) || portNum < 1 || portNum > 65535) {
             throw new Error(`Invalid port: ${port}`);
         }
         const apiUrl = globals.dev ? "http://localhost:8000" : globals.apiUrl;
+        if (opts.detach) {
+            await runDetached(portNum, apiUrl, globals.token, globals.tokenFile);
+            return;
+        }
         await runTunnel(portNum, globals.token, apiUrl, globals.tokenFile, {
             json: globals.json,
             quiet: globals.quiet,
         });
     });
 });
+connectCmd
+    .command("status")
+    .description("Show the active detached tunnel (or {active:false} when none)")
+    .action(async (_opts, cmd) => {
+    await runInline(cmd, async (globals) => {
+        connectStatus(globals.json);
+    });
+});
+program
+    .command("disconnect")
+    .description("Stop the active detached tunnel (graceful SIGTERM + backend deregister)")
+    .action(async (_opts, cmd) => {
+    await runInline(cmd, async (globals) => {
+        await disconnect(globals.json);
+    });
+});
 // --- Modular command groups ---
 registerWorkspaceCommands(program);
 registerStudyCommands(program);
@@ -243,8 +279,10 @@ registerProfileCommands(program);
 registerSourceCommands(program);
 registerConfigCommands(program);
 registerAskCommands(program);
+registerChatCommand(program);
 registerDocsCommands(program);
 registerInitCommands(program);
+registerSecretCommands(program);
 program
     .command("upgrade")
     .description("Update ish to the latest version")
@@ -254,4 +292,24 @@ program
     await upgrade(version, options.release);
 });
 injectGlobalWorkspaceOption(program);
+// L3 / Pattern J: surface --get and --fields on every verb's --help.
+// They're declared at the program root, so the per-verb help would
+// otherwise omit them — agents reach for `jq` instead of discovering the
+// in-CLI projection flags. This walks the command tree once at startup
+// and adds a one-line "Tips:" footer to every leaf verb that doesn't
+// already mention `--get`.
+function injectAgentTipsFooter(cmd) {
+    for (const sub of cmd.commands) {
+        injectAgentTipsFooter(sub);
+        // Skip groups (commands that themselves carry subcommands) — their own
+        // verbs render the footer; the group help would duplicate it.
+        if (sub.commands.length > 0)
+            continue;
+        const existing = sub.helpInformation();
+        if (existing.includes("--get <path>") || existing.includes("--get <field>"))
+            continue;
+        sub.addHelpText("after", `\nTips:\n  Use \`--get <path>\` to capture a single value (e.g. \`--get id\`),\n  \`--fields a,b,c\` to project the JSON output to listed fields.\n  See \`ish docs get-page reference/json-mode\` for the full output rules.`);
+    }
+}
+injectAgentTipsFooter(program);
 program.parse();

package/dist/lib/alias-hydrate.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Best-effort alias-cache hydration on alias-miss (Pattern F).
+ *
+ * The CLI persists aliases to ``~/.ish/aliases.json``, so the cache survives
+ * across processes. Where it bites: the file is missing/empty (fresh install,
+ * `rm ~/.ish/aliases.json`, agent running in a sandbox with a fresh
+ * `ISH_HOME`) and the agent has an alias from a prior process or the docs.
+ *
+ * ``resolveIdAsync(input, client, hints?)`` mirrors the sync ``resolveId``
+ * contract but, on alias-miss, attempts a single ``GET /list`` to repopulate
+ * the cache before retrying. The hydrate is BEST-EFFORT: a failing list
+ * call is swallowed and the canonical "Unknown alias" error fires with the
+ * actionable suggestion in the message.
+ *
+ * For prefixes whose list endpoint requires a parent ID (study/iteration/
+ * ask/etc), the caller passes ``hints`` carrying the parent (workspaceId,
+ * studyId). Without a parent we skip the hydrate — global N+1 fan-out is
+ * too expensive for a papercut.
+ */
+import { ApiClient } from "./api-client.js";
+export interface HydrateHints {
+    workspaceId?: string;
+    studyId?: string;
+}
+/**
+ * Best-effort hydrate of the alias cache for ``alias``'s entity type. Returns
+ * silently on success or any failure — the caller checks the cache after
+ * this returns.
+ */
+export declare function hydrateForAlias(client: ApiClient, alias: string, hints?: HydrateHints): Promise<void>;
+/**
+ * Async sibling of ``resolveId``: same UUID-or-alias contract, but on
+ * alias-miss attempts a best-effort hydrate via the matching list endpoint
+ * before retrying. Falls back to the canonical "Unknown alias" error
+ * (with named list-command suggestion) when the alias is still missing
+ * after the hydrate.
+ *
+ * Use this at command-handler entry points where the agent supplies an
+ * alias and the same call carries enough context (workspace / study) to
+ * scope the hydrate cheaply.
+ */
+export declare function resolveIdAsync(input: string, client: ApiClient, hints?: HydrateHints): Promise<string>;