@cydm/happy-elves 0.1.0-beta.3 → 0.1.0-beta.5

package/apps/cli/dist/index.js

@@ -21,12 +21,15 @@ const valueFlags = new Set([
     "machine-id",
     "name",
     "port",
+    "permission",
+    "permission-mode",
     "prompt",
     "every",
     "reason",
     "relay",
     "actions",
     "expires-in",
+    "format",
     "loops",
     "machines",
     "sessions",
@@ -37,6 +40,7 @@ const valueFlags = new Set([
     "text",
     "text-file",
     "timeout",
+    "runtime-timeout",
     "to",
     "token",
     "ttl",
@@ -50,14 +54,44 @@ const configDir = process.env.HAPPY_ELVES_HOME
     ? path.resolve(process.env.HAPPY_ELVES_HOME)
     : path.join(os.homedir(), ".happy-elves");
 const configPath = path.join(configDir, "controller.json");
+const outputRoot = path.join(configDir, "outputs");
 const defaultHostedRelayUrl = process.env.HAPPY_ELVES_DEFAULT_RELAY_URL ?? "https://relay.happyelves.ai";
 const defaultHostedControllerUrl = process.env.HAPPY_ELVES_DEFAULT_CONTROLLER_URL ?? "https://happyelves.ai";
 const startDaemonTimeoutMs = 10_000;
-function usage() {
-    writeError("USAGE", `happy-elves
+function usageText() {
+    return `happy-elves
+
+What it is:
+  Happy Elves is a remote control plane for coding agents. Use it to discover
+  machines, inspect workspaces, resume existing runtime sessions, create worker
+  sessions, run prompts, collect outputs, and manage scoped automation tokens.
+
+When to use it:
+  Use happy-elves when a user asks you to work with Happy Elves machines,
+  projects, workspaces, sessions, or remote agents. Do not bypass Happy Elves by
+  operating on a local checkout just because a similarly named project exists on
+  your machine.
+
+Agent usage guidance:
+  Prefer id-first commands and --json output when another agent will parse the
+  result. Use human output for direct terminal inspection.
+
+Recommended agent workflow:
+  1. machine list --json
+  2. workspace sessions --machine <machineId> --cwd <path> --json
+  3. session list [--machine <machineId>] --json
+  4. session create --machine <machineId> --agent codex --cwd <path> --json
+  5. run <sessionId> --text <prompt> --wait --json
+  6. result <sessionId> --json
+
+Output modes:
+  Human output is concise by default. Add --json when another program or agent
+  needs a stable envelope. Add --verbose to history/collect when raw events are
+  needed for debugging.
 
 Start:
   start [--relay <url>] [--controller <url>] [--cwd <path>] [--no-open] [--json]
+  status [--json]
   doctor [--relay <url>] [--json]
 
 Config:
@@ -79,22 +113,27 @@ Machines:
   machine show <machineId> --json
   machine status <machineId> --json
 
+Workspaces:
+  workspace sessions --cwd <path> [--machine <machineId>] [--agent codex] [--limit 50] [--json]
+
 Sessions:
-  session create --machine <machineId> [--agent codex] [--cwd <path>] [--name <name>] --json
-  session list [--machine <machineId>] [--agent <agent>] [--cwd <cwd>] [--name <name>] --json
+  session create --machine <machineId> [--agent codex] [--cwd <path>] [--name <name>] [--permission-mode <mode>] --json
+  session list [--machine <machineId>] [--agent <agent>] [--cwd <cwd>] [--name <name>] [--summary] [--verbose] [--json]
   session show <sessionId> --json
   session status <sessionId> --json
-  session history <sessionId> [--limit 20] --json
+  session history <sessionId> [--limit 20] [--verbose] [--json]   # debug/API events
+  session last-output <sessionId> [--json]
   session resume <sessionId> --json
   session rewind <sessionId> --to <turn-or-checkpoint-id> --json
   session fork <sessionId> --from <turn-or-checkpoint-id> --name <name> --json
   session close <sessionId> [--reason <reason>] --json
 
 Run:
-  run <sessionId> --text <prompt> [--no-wait] --json
-  run <sessionId> --text-file <path> [--no-wait] --json
+  run <sessionId> --text <prompt> [--wait|--detach] [--timeout 30m] [--runtime-timeout 30m] [--permission-mode approve-reads|approve-all|deny-all] [--json]
+  run <sessionId> --text-file <path> [--wait|--detach] [--timeout 30m] [--runtime-timeout 30m] [--permission-mode approve-reads|approve-all|deny-all] [--json]
+  result <sessionId> [--turn <turnId>] [--json]
   wait <sessionId> [--until idle|ready|running|completed|failed|cancelled|offline|closed] [--timeout 30m] --json
-  collect <sessionId> [--since <eventId>] [--limit 20] --json
+  collect <sessionId> [--since <eventId|event:id|cursor_id>] [--limit 20] [--verbose] [--json]   # debug/API events
   cancel <sessionId> [--turn <turnId>] [--reason <reason>] --json
 
 Scoped Tokens:
@@ -125,7 +164,19 @@ Relay:
   relay serve [--host 0.0.0.0] [--port 8787] --json
   relay status [--relay <url>] --json
   relay doctor [--relay <url>] --json
-`);
+
+Security notes:
+  Account secrets stay on controllers and daemons. Relay payloads are encrypted.
+  Scoped tokens should include only the actions they need, such as snapshot,
+  session.run, collect, directory.list, loop.create, or loop.run.
+`;
+}
+function usage() {
+    if (!process.argv.includes("--json")) {
+        console.error(usageText());
+        process.exit(1);
+    }
+    writeError("USAGE", usageText());
     process.exit(1);
 }
 function parseFlags(argv) {
@@ -367,6 +418,197 @@ function deriveOrchestration(session, events = []) {
 async function showSession(client, session, events = []) {
     return { ...session, metadata: await client.decodeSessionMetadata(session), orchestration: deriveOrchestration(session, events) };
 }
+function wantsJson(flags) {
+    return flags.json === true;
+}
+function wantsVerbose(flags) {
+    return flags.verbose === true || flags.format === "verbose";
+}
+function eventText(event) {
+    const payload = event.decoded;
+    if (!payload)
+        return event.decryptError ? `[decrypt error] ${event.decryptError}` : "";
+    if (payload.type === "user_prompt")
+        return payload.text.trim();
+    if (payload.type === "text_delta" && payload.stream !== "thought")
+        return payload.text.trim();
+    if (payload.type === "control")
+        return payload.text.trim();
+    if (payload.type === "done")
+        return payload.error?.trim() ?? payload.stopReason?.trim() ?? "";
+    return "";
+}
+function compactText(value, max = 220) {
+    const normalized = value.replace(/\s+/g, " ").trim();
+    return normalized.length > max ? `${normalized.slice(0, max - 1)}…` : normalized;
+}
+function lastAssistantOutput(events) {
+    let currentTurn = "";
+    const chunks = [];
+    for (const event of events) {
+        const payload = event.decoded;
+        if (payload?.type !== "text_delta" || payload.stream === "thought" || !payload.text)
+            continue;
+        if (event.turnId !== currentTurn) {
+            currentTurn = event.turnId;
+            chunks.length = 0;
+        }
+        chunks.push(payload.text);
+    }
+    return chunks.join("").trim();
+}
+function turnStatus(events, turnId) {
+    const done = [...events].reverse().find((event) => event.turnId === turnId && event.decoded?.type === "done")?.decoded;
+    if (done?.type !== "done")
+        return "unknown";
+    return done.status;
+}
+function assistantOutputForTurn(events, turnId) {
+    return events
+        .filter((event) => event.turnId === turnId && event.decoded?.type === "text_delta" && event.decoded.stream !== "thought")
+        .map((event) => event.decoded?.type === "text_delta" ? event.decoded.text : "")
+        .join("")
+        .trim();
+}
+function outputPaths(sessionId, turnId) {
+    const dir = path.join(outputRoot, sessionId);
+    const latest = path.join(dir, "latest.md");
+    return {
+        dir,
+        latest,
+        latestMetadata: path.join(dir, "latest.json"),
+        ...(turnId ? {
+            turn: path.join(dir, `${turnId}.md`),
+            metadata: path.join(dir, `${turnId}.json`),
+        } : {}),
+    };
+}
+function displayPath(filePath) {
+    const relative = path.relative(process.cwd(), filePath);
+    return relative.startsWith("..") ? filePath : relative || ".";
+}
+async function writeTurnOutput(sessionId, turnId, events) {
+    const paths = outputPaths(sessionId, turnId);
+    if (!paths.turn || !paths.metadata)
+        throw new CliError("Output path construction failed", "OUTPUT_FAILED");
+    await fs.mkdir(paths.dir, { recursive: true });
+    const output = assistantOutputForTurn(events, turnId);
+    const turnEvents = events.filter((event) => event.turnId === turnId);
+    const metadata = {
+        sessionId,
+        turnId,
+        status: turnStatus(events, turnId),
+        startedAt: turnEvents[0]?.createdAt,
+        completedAt: Date.now(),
+        eventCount: turnEvents.length,
+        outputPath: paths.turn,
+        latestPath: paths.latest,
+    };
+    await fs.writeFile(paths.turn, output ? `${output}\n` : "", "utf8");
+    await fs.writeFile(paths.metadata, `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
+    await fs.writeFile(paths.latestMetadata, `${JSON.stringify({ sessionId, turnId, metadataPath: paths.metadata, outputPath: paths.turn }, null, 2)}\n`, "utf8");
+    await fs.rm(paths.latest, { force: true });
+    try {
+        await fs.symlink(path.basename(paths.turn), paths.latest);
+    }
+    catch {
+        await fs.copyFile(paths.turn, paths.latest);
+    }
+    return { ...metadata, output, metadataPath: paths.metadata };
+}
+async function readStoredTurnOutput(sessionId, turnId) {
+    const paths = outputPaths(sessionId, turnId);
+    let outputPath = paths.turn;
+    let metadataPath = paths.metadata;
+    if (!turnId) {
+        outputPath = paths.latest;
+        const latest = await fs.readFile(paths.latestMetadata, "utf8").then((value) => JSON.parse(value)).catch(() => undefined);
+        if (latest && typeof latest.turnId === "string") {
+            metadataPath = typeof latest.metadataPath === "string" ? latest.metadataPath : path.join(paths.dir, `${latest.turnId}.json`);
+            outputPath = typeof latest.outputPath === "string" ? latest.outputPath : outputPath;
+        }
+        else {
+            const real = await fs.realpath(paths.latest).catch(() => paths.latest);
+            const match = path.basename(real).match(/^(.*)\.md$/);
+            if (match && match[1] !== "latest")
+                metadataPath = path.join(paths.dir, `${match[1]}.json`);
+        }
+    }
+    if (!outputPath)
+        return undefined;
+    const output = await fs.readFile(outputPath, "utf8").catch(() => undefined);
+    if (output === undefined)
+        return undefined;
+    const metadata = metadataPath ? await fs.readFile(metadataPath, "utf8").then((value) => JSON.parse(value)).catch(() => ({})) : {};
+    const resolvedTurnId = typeof metadata.turnId === "string" ? metadata.turnId : turnId ?? path.basename(outputPath, ".md");
+    return {
+        sessionId,
+        turnId: resolvedTurnId,
+        status: typeof metadata.status === "string" ? metadata.status : "unknown",
+        output: output.trimEnd(),
+        outputPath,
+        latestPath: paths.latest,
+        metadataPath: metadataPath ?? path.join(paths.dir, `${resolvedTurnId}.json`),
+        startedAt: typeof metadata.startedAt === "number" ? metadata.startedAt : undefined,
+        completedAt: typeof metadata.completedAt === "number" ? metadata.completedAt : 0,
+        eventCount: typeof metadata.eventCount === "number" ? metadata.eventCount : 0,
+    };
+}
+async function rebuildTurnOutput(client, sessionId, turnId) {
+    const events = await client.history(sessionId, 1000);
+    const resolvedTurnId = turnId ?? [...events].reverse().find((event) => event.decoded?.type === "text_delta" || event.decoded?.type === "done")?.turnId;
+    if (!resolvedTurnId)
+        throw new CliError("No turn output found for session", "RESULT_NOT_FOUND");
+    if (turnId && !events.some((event) => event.turnId === turnId)) {
+        throw new CliError(`Turn ${turnId} was not found in the latest 1000 relay events. Re-run without --turn for the latest result, or use a local output file from ${displayPath(outputPaths(sessionId).dir)} if available.`, "RESULT_HISTORY_WINDOW_EXCEEDED");
+    }
+    return await writeTurnOutput(sessionId, resolvedTurnId, events);
+}
+function conciseEvents(events) {
+    const result = [];
+    for (const event of events) {
+        const payload = event.decoded;
+        if (!payload)
+            continue;
+        if (payload.type === "user_prompt")
+            result.push({ id: event.id, turnId: event.turnId, role: "user", text: payload.text });
+        if (payload.type === "text_delta" && payload.stream !== "thought" && payload.text.trim()) {
+            result.push({ id: event.id, turnId: event.turnId, role: "assistant", text: payload.text });
+        }
+        if (payload.type === "control" || payload.type === "done") {
+            const text = eventText(event);
+            if (text)
+                result.push({ id: event.id, turnId: event.turnId, role: payload.type, text });
+        }
+    }
+    return result;
+}
+function printConciseEvents(events) {
+    const concise = conciseEvents(events);
+    if (concise.length === 0) {
+        console.log("No readable output.");
+        return;
+    }
+    for (const event of concise) {
+        console.log(`[${event.id}] ${event.role}: ${event.text.trim()}`);
+    }
+}
+async function conciseSessionSummary(client, session) {
+    const metadata = await client.decodeSessionMetadata(session);
+    const events = await client.history(session.id, 50);
+    const stored = await readStoredTurnOutput(session.id).catch(() => undefined);
+    return {
+        sessionId: session.id,
+        name: metadata.name ?? session.name,
+        agent: metadata.agent ?? session.agent,
+        machineId: session.machineId,
+        cwd: metadata.cwd ?? session.cwd,
+        status: session.status,
+        updatedAt: session.updatedAt,
+        lastOutput: lastAssistantOutput(events),
+        latestOutputPath: stored?.latestPath,
+    };
+}
 async function requireProjectedSession(client, sessionId, action) {
     const session = await client.getSession(sessionId);
     if (!session) {
@@ -408,6 +650,71 @@ async function machineSessionOverview(client, sessions, machineId) {
         sessions: projectedSessions,
     };
 }
+async function listWorkspaceHistoricalSessions(client, input) {
+    const snapshot = await client.snapshot();
+    const selectedMachines = snapshot.machines.filter((machine) => {
+        if (input.machineId)
+            return machine.id === input.machineId;
+        return machine.online;
+    });
+    if (input.machineId && selectedMachines.length === 0)
+        throw new CliError("Machine not found", "MACHINE_NOT_FOUND");
+    const machines = await Promise.all(selectedMachines.map(async (machine) => ({
+        machine,
+        projected: await showMachine(client, machine),
+    })));
+    const rows = await Promise.all(machines.map(async ({ machine, projected }) => {
+        const machineName = projected.metadata.name ?? projected.metadata.hostname ?? machine.name;
+        try {
+            const sessions = await client.listHistoricalSessions({
+                machineId: machine.id,
+                cwd: input.cwd,
+                agent: input.agent,
+                limit: input.limit,
+            });
+            return {
+                sessions: sessions.map((session) => ({ ...session, machineId: machine.id, machineName })),
+                error: undefined,
+                machine: { machineId: machine.id, machineName },
+            };
+        }
+        catch (error) {
+            const enriched = error;
+            return {
+                sessions: [],
+                error: {
+                    machineId: machine.id,
+                    machineName,
+                    code: enriched.code,
+                    message: error instanceof Error ? error.message : String(error),
+                },
+                machine: { machineId: machine.id, machineName },
+            };
+        }
+    }));
+    return {
+        sessions: rows.flatMap((row) => row.sessions).sort((left, right) => right.updatedAt - left.updatedAt),
+        errors: rows.flatMap((row) => row.error ? [row.error] : []),
+        machines: rows.map((row) => row.machine),
+    };
+}
+function printWorkspaceHistoricalSessions(sessions, errors) {
+    if (sessions.length === 0) {
+        console.log("No runtime sessions found for this workspace.");
+    }
+    else {
+        console.log("MACHINE | AGENT | UPDATED | RUNTIME SESSION | LOADED | SUMMARY");
+        for (const session of sessions) {
+            const updated = new Date(session.updatedAt).toISOString();
+            const loaded = session.loadedSessionId ?? "-";
+            const summary = compactText(session.summary ?? session.runtimeSessionName ?? "");
+            console.log(`${session.machineName} (${session.machineId}) | ${session.agent} | ${updated} | ${session.runtimeSessionId} | ${loaded} | ${summary}`);
+        }
+    }
+    for (const error of errors) {
+        console.error(`Warning: ${error.machineName} (${error.machineId}) ${error.code ? `${error.code}: ` : ""}${error.message}`);
+    }
+}
 function parseDurationMs(value, fallbackMs) {
     if (typeof value !== "string")
         return fallbackMs;
@@ -462,12 +769,29 @@ function parseEventCursor(value) {
     const match = normalized.match(/^cursor_(\d+)$/);
     if (match)
         return `cursor_${Number(match[1])}`;
+    const eventMatch = normalized.match(/^event:(\d+)$/);
+    if (eventMatch)
+        return Number(eventMatch[1]);
     const numeric = Number(normalized);
     if (!Number.isInteger(numeric) || numeric < 0) {
         throw new CliError(`Invalid --since cursor: ${value}`, "INVALID_ARGUMENT");
     }
     return numeric;
 }
+function parsePermissionMode(value) {
+    if (value === undefined || value === false)
+        return undefined;
+    if (value === true)
+        return "approve-reads";
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "yolo" || normalized === "approve-all")
+        return "approve-all";
+    if (normalized === "plan" || normalized === "deny-all" || normalized === "read-only")
+        return "deny-all";
+    if (normalized === "default" || normalized === "ask" || normalized === "accept-edits" || normalized === "approve-reads")
+        return "approve-reads";
+    throw new CliError(`Invalid permission mode: ${value}`, "INVALID_ARGUMENT");
+}
 function parseControllerJoinUrl(value) {
     let url;
     try {
@@ -969,7 +1293,8 @@ function startRelayUrl(flags, existing) {
     if (typeof flags.relay === "string") {
         return { relayUrl: requireRelayUrl(flags), explicit: true };
     }
-    return { relayUrl: existing?.relayUrl ?? normalizeRelayUrl(defaultHostedRelayUrl), explicit: false };
+    const relayUrl = normalizeRelayUrl(defaultHostedRelayUrl);
+    return { relayUrl, explicit: existing?.relayUrl !== undefined && existing.relayUrl !== relayUrl };
 }
 function writeHumanStartOutput(data) {
     console.log("Happy Elves is running.");
@@ -1126,11 +1451,55 @@ async function topLevelDoctor(flags) {
     checks.push({ name: "daemon-process", ok: local.running, message: local.running ? "running" : "not running", details: local });
     ok("doctor", { ok: checks.every((check) => check.ok), checks });
 }
+async function topLevelStatus(flags) {
+    const config = await readConfig(flags);
+    const client = new ControllerClient(config);
+    const [local, snapshot] = await Promise.all([localDaemonStatus(), client.snapshot()]);
+    const latestSession = [...snapshot.sessions].sort((left, right) => right.updatedAt - left.updatedAt)[0];
+    const latestOutput = latestSession ? await readStoredTurnOutput(latestSession.id).catch(() => undefined) : undefined;
+    const data = {
+        relayUrl: config.relayUrl,
+        daemon: local,
+        machines: {
+            count: snapshot.machines.length,
+            onlineCount: snapshot.machines.filter((machine) => machine.online).length,
+        },
+        sessions: {
+            count: snapshot.sessions.length,
+            runningCount: snapshot.sessions.filter((session) => session.status === "running").length,
+        },
+        latestSession: latestSession ? {
+            sessionId: latestSession.id,
+            status: latestSession.status,
+            latestOutputPath: latestOutput?.latestPath,
+            resultCommand: `happy-elves result ${latestSession.id}`,
+            runCommand: `happy-elves run ${latestSession.id} --text "..." --wait`,
+        } : undefined,
+    };
+    if (wantsJson(flags)) {
+        ok("status", data);
+        return;
+    }
+    console.log(`Relay: ${config.relayUrl}`);
+    console.log(`Daemon: ${local.running ? `running${local.pid ? ` pid ${local.pid}` : ""}` : "not running"}`);
+    console.log(`Machines: ${data.machines.onlineCount}/${data.machines.count} online`);
+    console.log(`Sessions: ${data.sessions.count} total, ${data.sessions.runningCount} running`);
+    if (latestSession) {
+        console.log(`Latest session: ${latestSession.id} ${latestSession.status}`);
+        console.log(`Latest output: ${latestOutput ? displayPath(latestOutput.latestPath) : "none"}`);
+        console.log(`Result: happy-elves result ${latestSession.id}`);
+        console.log(`Run: happy-elves run ${latestSession.id} --text "..." --wait`);
+    }
+}
 async function main() {
     const argv = process.argv.slice(2);
     const [domain] = argv;
     if (!domain)
         usage();
+    if (domain === "--help" || domain === "-h" || domain === "help") {
+        console.log(usageText());
+        return;
+    }
     if (domain === "start") {
         const { flags } = parseFlags(argv.slice(1));
         await startBootstrap(flags);
@@ -1141,6 +1510,11 @@ async function main() {
         await topLevelDoctor(flags);
         return;
     }
+    if (domain === "status") {
+        const { flags } = parseFlags(argv.slice(1));
+        await topLevelStatus(flags);
+        return;
+    }
     const [, action, ...rest] = argv;
     const { positional, flags } = parseFlags(rest);
     if (domain === "account" && action === "create") {
@@ -1639,12 +2013,33 @@ async function main() {
         }, { machineId: machine.id });
         return;
     }
+    if (domain === "workspace" && action === "sessions") {
+        const cwd = requireString(flags, "cwd");
+        const limit = typeof flags.limit === "string" ? Number(flags.limit) : 50;
+        if (!Number.isInteger(limit) || limit <= 0 || limit > 200) {
+            throw new CliError(`Invalid --limit: ${flags.limit}`, "INVALID_ARGUMENT");
+        }
+        const result = await listWorkspaceHistoricalSessions(client, {
+            cwd,
+            machineId: typeof flags.machine === "string" ? flags.machine : undefined,
+            agent: typeof flags.agent === "string" ? flags.agent : undefined,
+            limit,
+        });
+        if (wantsJson(flags)) {
+            ok("workspace.sessions", { cwd, agent: typeof flags.agent === "string" ? flags.agent : undefined, ...result });
+        }
+        else {
+            printWorkspaceHistoricalSessions(result.sessions, result.errors);
+        }
+        return;
+    }
     if (domain === "session" && action === "create") {
         const machineId = requireString(flags, "machine");
         const agent = typeof flags.agent === "string" ? flags.agent : "codex";
         const cwd = typeof flags.cwd === "string" ? flags.cwd : process.cwd();
         const name = typeof flags.name === "string" ? flags.name : "main";
-        const result = await client.createSession({ machineId, agent, cwd, name });
+        const permissionMode = parsePermissionMode(flags["permission-mode"] ?? flags.permission);
+        const result = await client.createSession({ machineId, agent, cwd, name, permissionMode });
         const session = result.sessionId ? await client.getSession(result.sessionId) : undefined;
         ok("session.create", {
             sessionId: result.sessionId,
@@ -1659,7 +2054,27 @@ async function main() {
             cwd: typeof flags.cwd === "string" ? flags.cwd : undefined,
             name: typeof flags.name === "string" ? flags.name : undefined,
         });
-        ok("session.list", { sessions: await Promise.all(sessions.map((session) => showSession(client, session))) });
+        if (wantsJson(flags) || wantsVerbose(flags)) {
+            const projected = await Promise.all(sessions.map(async (session) => ({
+                ...(await showSession(client, session)),
+                latestOutput: await readStoredTurnOutput(session.id).catch(() => undefined),
+            })));
+            ok("session.list", { sessions: projected });
+        }
+        else {
+            const summaries = await Promise.all(sessions.map((session) => conciseSessionSummary(client, session)));
+            if (summaries.length === 0) {
+                console.log("No sessions.");
+            }
+            else {
+                console.log("SESSION | AGENT | STATUS | NAME | CWD | LATEST");
+                for (const session of summaries) {
+                    const preview = session.lastOutput ? ` | ${compactText(session.lastOutput)}` : "";
+                    const latest = session.latestOutputPath ? displayPath(session.latestOutputPath) : "-";
+                    console.log(`${session.sessionId} | ${session.agent} | ${session.status} | ${session.name} | ${session.cwd} | ${latest}${preview}`);
+                }
+            }
+        }
         return;
     }
     if (domain === "session" && action === "show") {
@@ -1676,6 +2091,7 @@ async function main() {
         const metadata = await client.decodeSessionMetadata(session);
         const recentEvents = await client.history(session.id, 20);
         const orchestration = deriveOrchestration(session, recentEvents);
+        const latestOutput = await readStoredTurnOutput(session.id).catch(() => undefined);
         ok("session.status", {
             sessionId: session.id,
             machineId: session.machineId,
@@ -1687,6 +2103,11 @@ async function main() {
             sourceSessionId: session.sourceSessionId,
             sourceCheckpointId: session.sourceCheckpointId,
             orchestration,
+            latestOutput,
+            next: {
+                result: `happy-elves result ${session.id}`,
+                run: `happy-elves run ${session.id} --text "..." --wait`,
+            },
             metadata,
             capabilities: session.capabilities,
         }, { machineId: session.machineId, sessionId: session.id });
@@ -1698,7 +2119,25 @@ async function main() {
         if (!Number.isInteger(limit) || limit <= 0) {
             throw new CliError(`Invalid --limit: ${flags.limit}`, "INVALID_ARGUMENT");
         }
-        ok("session.history", { sessionId, events: await client.history(sessionId, limit) }, { sessionId });
+        const events = await client.history(sessionId, limit);
+        if (wantsJson(flags) || wantsVerbose(flags)) {
+            ok("session.history", { sessionId, events }, { sessionId });
+        }
+        else {
+            printConciseEvents(events);
+        }
+        return;
+    }
+    if (domain === "session" && action === "last-output") {
+        const sessionId = requirePositional(positional[0], "sessionId");
+        const events = await client.history(sessionId, 200);
+        const output = lastAssistantOutput(events);
+        if (wantsJson(flags)) {
+            ok("session.last-output", { sessionId, output }, { sessionId });
+        }
+        else {
+            console.log(output || "No assistant output yet.");
+        }
         return;
     }
     if (domain === "session" && action === "resume") {
@@ -1755,8 +2194,52 @@ async function main() {
                 : "";
         if (!text.trim())
             throw new CliError("Missing --text or --text-file", "MISSING_ARGUMENT");
-        const result = await client.run(sessionId, text, { wait: flags["no-wait"] !== true });
-        ok("session.run", { sessionId, turnId: result.turnId, events: await client.decodeEvents(result.events) }, { requestId: result.requestId, sessionId });
+        if (flags.wait === true && (flags.detach === true || flags["no-wait"] === true)) {
+            throw new CliError("--wait cannot be combined with --detach or --no-wait", "INVALID_ARGUMENT");
+        }
+        if (flags["no-wait"] === true && !wantsJson(flags)) {
+            console.error("Warning: --no-wait is deprecated; use --detach.");
+        }
+        const permissionMode = parsePermissionMode(flags["permission-mode"] ?? flags.permission);
+        const wait = flags.wait === true || (wantsJson(flags) && flags.detach !== true && flags["no-wait"] !== true);
+        const watchTimeoutMs = parseDurationMs(flags.timeout, 30 * 60_000);
+        const ackTimeoutMs = 15_000;
+        const runtimeTimeoutMs = typeof flags["runtime-timeout"] === "string" ? parseDurationMs(flags["runtime-timeout"], 30 * 60_000) : undefined;
+        const result = await client.run(sessionId, text, { wait, permissionMode, waitTimeoutMs: watchTimeoutMs, ackTimeoutMs, runtimeTimeoutMs });
+        const events = await client.decodeEvents(result.events);
+        const output = wait && result.turnId ? await writeTurnOutput(sessionId, result.turnId, events) : undefined;
+        if (wantsJson(flags)) {
+            ok("session.run", { sessionId, turnId: result.turnId, events, output }, { requestId: result.requestId, sessionId });
+        }
+        else if (wait) {
+            printConciseEvents(events);
+            if (output) {
+                const label = output.status === "completed" ? "Completed" : output.status[0]?.toUpperCase() + output.status.slice(1);
+                console.log(`${label} ${output.turnId}`);
+                console.log(`Output: ${displayPath(output.outputPath)}`);
+                console.log(`Latest: ${displayPath(output.latestPath)}`);
+                console.log(`View: happy-elves result ${sessionId}`);
+            }
+        }
+        else {
+            console.log(`Turn started: ${result.turnId}`);
+            console.log(`Track: happy-elves run ${sessionId} --text-file <next-prompt> --wait`);
+            console.log(`Wait: happy-elves wait ${sessionId} --until ready`);
+            console.log(`Result: happy-elves result ${sessionId}`);
+        }
+        return;
+    }
+    if (domain === "result") {
+        const sessionId = requirePositional(action, "sessionId");
+        const turnId = typeof flags.turn === "string" ? flags.turn : undefined;
+        const stored = await readStoredTurnOutput(sessionId, turnId).catch(() => undefined);
+        const result = stored ?? await rebuildTurnOutput(client, sessionId, turnId);
+        if (wantsJson(flags)) {
+            ok("session.result", result, { sessionId });
+        }
+        else {
+            console.log(result.output || "No assistant output yet.");
+        }
         return;
     }
     if (domain === "wait") {
@@ -1782,11 +2265,14 @@ async function main() {
         }
         const events = await client.collect(sessionId, { since, limit });
         const lastEventId = events.at(-1)?.id;
-        ok("session.collect", {
-            sessionId,
-            cursor: lastEventId === undefined ? (since ?? null) : `cursor_${lastEventId}`,
-            events,
-        }, { sessionId });
+        const nextSince = lastEventId === undefined ? (since ?? null) : `cursor_${lastEventId}`;
+        if (wantsJson(flags) || wantsVerbose(flags)) {
+            ok("session.collect", { sessionId, cursor: nextSince, nextSince, events }, { sessionId });
+        }
+        else {
+            printConciseEvents(events);
+            console.log(`nextSince: ${nextSince ?? "none"}`);
+        }
         return;
     }
     if (domain === "cancel") {