@enter-pro/enter-cli 0.4.2 → 0.4.4

package/dist/commands/thread.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { Command } from "commander";
 import { setTimeout as delay } from "node:timers/promises";
 import { writeFileSync, readFileSync } from "fs";
@@ -7,7 +8,8 @@ import { pollUntil, TimeoutError } from "../poll.js";
 import { resolveLifecycleStatus } from "../lifecycle.js";
 import { ThreadEvents, isStateEvent } from "../thread-events.js";
 import { safeOutput } from "../safe-output.js";
-import { errorEnvelope } from "../errors.js";
+import { RequestError, errorEnvelope } from "../errors.js";
+import { workflowResult } from "../workflow.js";
 import { registerThreadTasks } from "./thread-tasks.js";
 export const threadCmd = new Command("thread").description("Manage project threads and chat");
 registerThreadTasks(threadCmd);
@@ -27,6 +29,8 @@ function normalizeAction(raw) {
         updated_at: String(raw.updated_at ?? raw.UpdatedAt ?? ""),
     };
 }
+// Single registry: adding a new tool only requires editing one row.
+const STRIPE_INPUT_INSTRUCTIONS = "Submit the Stripe key through --secret-value-stdin from an authorized input source. Reuse input already supplied for this task; otherwise offer an available secure input or local-file path. Do not echo the key or embed it in shell text or build prompts. Report connection errors without assuming their cause.";
 async function loadToolCallArgs(projectId, action, toolName, context = {}) {
     const turn = String(action.turn);
     const data = await (context.messages ??= client.get(`/v1/projects/${projectId}/thread/messages`, { start_turn: turn, end_turn: turn }, context.signal));
@@ -73,18 +77,22 @@ async function loadToolCallArgs(projectId, action, toolName, context = {}) {
     }
     return { kind: "not_found" };
 }
+const ANSWERS_FORMAT = 'Use the exact original question text as each key, not a host question ID. Each value must be {"selected_options":["exact option label"],"other_text":"optional free text"}. Use an empty selected_options array for free-text-only answers. See thread approve --help.';
 const TOOL_HANDLERS = {
     // ask_user_question: surface the questions array directly so callers don't
     // have to fetch + parse thread messages to know what to ask the user.
     ask_user_question: {
         kind: "questions",
-        approveSuffix: (pid, a) => `--answers '<json>' OR enter-cli thread approve ${pid} ${a.action_id} --skip-answers`,
-        instructions: "Questions are included in this action's `questions` field. Forward each question (with its options and multiSelect) to the user, collect answers, then run approve_command --answers '<json>' (or --skip-answers).",
+        approveSuffix: "--answers '<json>'",
+        instructions: `Forward questions, options and multiSelect to the user unchanged. Map their response back to the original question text. ${ANSWERS_FORMAT} After receiving the user response, run approve_command with that JSON. Use skip_command only if the user asks to skip.`,
         enrich: async (projectId, action, context) => {
             const args = await loadToolCallArgs(projectId, action, "ask_user_question", context);
             switch (args.kind) {
                 case "ok":
-                    return { questions: args.value.questions ?? [] };
+                    return {
+                        questions: args.value.questions ?? [],
+                        skip_command: `enter-cli thread approve ${projectId} ${action.action_id} --skip-answers`,
+                    };
                 case "parse_error":
                     return { questions: { raw_arguments: args.raw_arguments, parse_error: true } };
                 case "not_found":
@@ -94,31 +102,31 @@ const TOOL_HANDLERS = {
     },
     supabase_add_secret: {
         kind: "secret",
-        approveSuffix: () => `--secret-name <NAME> --secret-value-stdin`,
-        instructions: "Use a secure input surface for the secret name and value; direct CLI callers can use stdin. Never request or echo credentials in ordinary chat.",
+        approveSuffix: `--secret-name <NAME> --secret-value-stdin`,
+        instructions: "Submit the secret name and value through --secret-value-stdin from an authorized input source. Reuse input already supplied for this task; otherwise ask for the missing value through an available secure input or local-file path. Do not echo the value or embed it in shell text or build prompts.",
     },
     supabase_configure_auth_provider: {
         kind: "auth_provider",
-        approveSuffix: () => "",
-        instructions: "Configure the requested provider through Enter's secure form, then approve. For direct CLI use, --auth-config-stdin accepts provider configuration JSON through stdin. Never collect credentials in ordinary chat. Approval verifies saved configuration with the backend.",
-        enrich: async (projectId, action, context) => ({ provider: await authProviderFor(projectId, action, context) }),
+        approveSuffix: "",
+        instructions: "Configure this provider with --auth-config-stdin using an authorized input source, or use Enter's provider form. Reuse configuration already supplied for this task; ask only for missing fields. After form submission query status before approving again. Missing input is not build failure.",
+        enrich: async (projectId, action, context) => authProviderInput(await authProviderFor(projectId, action, context)),
     },
     stripe_enable: {
         kind: "secret",
-        approveSuffix: () => `--secret-value-stdin`,
-        instructions: "Use a secure input surface or direct CLI stdin for the Stripe key. Never request credentials in ordinary chat.",
+        approveSuffix: `--secret-value-stdin`,
+        instructions: STRIPE_INPUT_INSTRUCTIONS,
     },
     stripe_update_key_and_migrate: {
         kind: "secret",
-        approveSuffix: () => `--secret-value-stdin`,
-        instructions: "Product IDs come from the pending tool call. Supply the new Stripe key through a secure input surface or direct CLI stdin, never ordinary chat.",
+        approveSuffix: `--secret-value-stdin`,
+        instructions: `${STRIPE_INPUT_INSTRUCTIONS} Product IDs come from the pending tool call.`,
     },
     // confirm_plan_mode: surface the plan text directly on the action so callers
     // don't have to fetch + parse thread messages themselves.
     confirm_plan_mode: {
         kind: "none",
-        approveSuffix: () => "",
-        instructions: "Plan is included in this action's `plan` field. Show it to the user, then run approve_command.",
+        approveSuffix: "",
+        instructions: "Plan is included in this action's `plan` field. Present it for the user's approval and wait for their decision before running approve_command. Displaying the plan is not approval.",
         enrich: async (projectId, action, context) => {
             const args = await loadToolCallArgs(projectId, action, "confirm_plan_mode", context);
             switch (args.kind) {
@@ -141,7 +149,7 @@ const TOOL_HANDLERS = {
 };
 const DEFAULT_HANDLER = {
     kind: "none",
-    approveSuffix: () => "",
+    approveSuffix: "",
     instructions: "No additional input required. Approve only within the user-authorized scope; input_kind none does not itself grant authorization.",
 };
 const FEATURE_ENABLE_ROUTES = new Map([
@@ -156,6 +164,25 @@ const AUTH_PROVIDER_FIELDS = {
     alipay: ["enabled", "app_id", "private_key"],
     feishu: ["enabled", "app_id", "app_secret"],
 };
+// Input requirements are separate from optional provider settings. Never put
+// stored configuration values (including masked secrets) in action metadata.
+const AUTH_PROVIDER_INPUTS = {
+    google: ["client_ids", "client_secret"],
+    wechat: ["client_id", "client_secret"],
+    alipay: ["app_id", "private_key"],
+    feishu: ["app_id", "app_secret"],
+};
+function authProviderInput(provider) {
+    return {
+        provider,
+        configuration: {
+            input_surface: "enter_project_auth_form",
+            input_methods: ["auth_config_stdin", "enter_project_auth_form"],
+            fields: AUTH_PROVIDER_INPUTS[provider],
+            instructions: "Supply the listed fields as JSON through --auth-config-stdin from an authorized input source; Enter's provider form is an alternative, not a required detour. If input is missing, offer an available secure input or local-file path. Do not echo credentials or embed them in shell text or build prompts. Use the actual OAuth callback URL when configuring the provider. After saving through the form query status, since it may already have approved the action.",
+        },
+    };
+}
 async function authProviderFor(projectId, action, context = {}) {
     if (!action.tool_call_id)
         throw new Error("Auth provider action is missing its tool_call_id");
@@ -183,7 +210,7 @@ function handlerFor(toolName) {
 }
 function buildApproveCommand(projectId, action) {
     const base = `enter-cli thread approve ${projectId} ${action.action_id}`;
-    const suffix = handlerFor(action.tool_name).approveSuffix(projectId, action);
+    const suffix = handlerFor(action.tool_name).approveSuffix;
     return suffix ? `${base} ${suffix}` : base;
 }
 async function fetchPendingActions(projectId, actionIds = [], signal) {
@@ -217,8 +244,7 @@ threadCmd
         content = opts.message;
     }
     else {
-        console.error("Error: either -m <text> or --file <path> is required");
-        process.exit(1);
+        throw new Error("Provide non-empty input using --message, --file or --stdin");
     }
     if (!content.trim())
         throw new Error("Message must not be empty");
@@ -241,6 +267,7 @@ threadCmd
     .option("--end-turn <n>", "End turn number")
     .option("--turn <n>", "Get messages for a specific turn (shorthand for --start-turn N --end-turn N)")
     .option("--latest", "Get messages from the most recent turn (most common usage)")
+    .option("--text", "Return assistant text with turn numbers, without raw event envelopes")
     .option("--tail <n>", "Get messages from the last N turns")
     .option("--follow", "Stream NDJSON events over WebSocket; no automatic approval")
     .option("--cursor <id>", "Resume after a previously returned event ID")
@@ -249,6 +276,8 @@ threadCmd
     .option("--max-events <n>", "Stop --follow after N events")
     .action(async (id, opts, cmd) => {
     if (opts.follow) {
+        if (opts.text)
+            throw new Error("--text is not supported with --follow");
         await followThreadStream(id, opts);
         return;
     }
@@ -264,7 +293,7 @@ threadCmd
         const resp = turnsData;
         const turns = resp.turns || [];
         if (turns.length === 0) {
-            printMessage("No turns found.");
+            print(getFormat(cmd), { messages: [] });
             return;
         }
         if (opts.latest) {
@@ -283,15 +312,18 @@ threadCmd
         }
     }
     if (!startTurn) {
-        console.error("Error: specify --start-turn, --turn, --latest, --tail, or --follow");
-        process.exit(1);
+        throw new Error("Specify --start-turn, --turn, --latest, --tail, or --follow");
     }
     const params = {};
     params.start_turn = startTurn;
     if (endTurn)
         params.end_turn = endTurn;
     const data = await client.get(`/v1/projects/${id}/thread/messages`, params);
-    print(getFormat(cmd), data);
+    if (opts.text) {
+        print(getFormat(cmd), safeOutput({ messages: assistantMessages(data) }));
+    }
+    else
+        print(getFormat(cmd), data);
 });
 async function followThreadStream(projectId, opts) {
     const timeout = positiveNumber(opts.timeout ?? "60", "--timeout") * 1000;
@@ -360,16 +392,64 @@ threadCmd
     ]);
     printTable(["Turn", "Name", "Status", "Model", "Credits", "Created"], rows);
 });
-export function threadInteraction(id, { taskId, chatId, turn, requireBuild } = {}) {
-    const target = (taskId ? ` --task-id ${taskId}` : turn === undefined ? "" : ` --turn ${turn}`)
-        + (chatId ? ` --chat-id ${chatId}` : "") + (requireBuild ? " --require-build" : "");
+function assistantMessages(data) {
+    const rows = Array.isArray(data) ? data : data?.messages ?? [];
+    return rows.flatMap((row) => {
+        const content = row?.detail?.assistant_content?.content;
+        return row?.message_type === "assistant_content" && typeof content === "string" && content.trim()
+            ? [{ turn: row.turn, text: content }] : [];
+    });
+}
+async function readProgress(id, turn, signal, timeoutMs = 30000) {
+    const controller = new AbortController();
+    const abort = () => controller.abort(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+    if (signal.aborted)
+        abort();
+    // Optional narrative must not hold up action handling or status indefinitely.
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const data = await client.get(`/v1/projects/${id}/thread/messages`, {
+            start_turn: String(turn.turn), end_turn: String(turn.turn),
+            ...(typeof turn.chat_id === "string" ? { chat_id: turn.chat_id } : {}),
+        }, controller.signal);
+        const messages = assistantMessages(data).filter(m => m.turn === undefined || String(m.turn) === String(turn.turn)).slice(-1);
+        const revision = createHash("sha256").update(JSON.stringify([id, turn.id, turn.chat_id, turn.turn, messages])).digest("hex");
+        return { source: "assistant_messages", available: true, revision,
+            messages: messages.map(m => ({ ...m, text: m.text.slice(0, 1600), ...(m.text.length > 1600 ? { truncated: true } : {}) })) };
+    }
+    catch (error) {
+        return { source: "assistant_messages", available: false, messages: [],
+            error: controller.signal.aborted ? { code: "PROGRESS_QUERY_TIMEOUT", retryable: true } : errorEnvelope(error).error };
+    }
+    finally {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", abort);
+    }
+}
+export function threadInteraction(id, { taskId, chatId, turn, requireBuild, timeout, afterProgress, progressInterval } = {}) {
+    const targetArgs = [
+        ...(taskId ? ["--task-id", taskId] : turn === undefined ? [] : ["--turn", String(turn)]),
+        ...(chatId ? ["--chat-id", chatId] : []), ...(requireBuild ? ["--require-build"] : []),
+    ];
+    const target = targetArgs.length ? ` ${targetArgs.join(" ")}` : "";
+    const waitArgv = ["enter-cli", "--output", "json", "thread", "wait", id, ...targetArgs,
+        ...(afterProgress ? ["--after-progress", afterProgress] : []),
+        ...(progressInterval !== undefined ? ["--progress-interval", progressInterval] : []),
+        "--timeout", timeout === "0" ? "10" : timeout ?? "10"];
+    const streamArgv = [...waitArgv.slice(0, -2), "--stream", "--timeout", "0"];
+    const shellCommand = (argv) => argv.map(arg => /^[a-zA-Z0-9_./:-]+$/.test(arg) ? arg : "'" + arg.replace(/'/g, "'\"'\"'") + "'").join(" ");
     return {
+        workflow: workflowResult({ status: "running", task_id: taskId, turn: { turn, chat_id: chatId } }),
         monitoring_required: true,
-        wait_command: `enter-cli --output json thread wait ${id}${target}`,
-        watch_command: `enter-cli thread watch ${id}${target}`,
-        status_command: `enter-cli --output json thread status ${id}${target}`,
+        wait_command: shellCommand(waitArgv),
+        wait_argv: waitArgv,
+        stream_command: shellCommand(streamArgv),
+        stream_argv: streamArgv,
+        watch_command: `enter-cli thread watch ${id}${target}${afterProgress ? ` --after-progress ${afterProgress}` : ""}${progressInterval !== undefined ? ` --progress-interval ${progressInterval}` : ""} --timeout ${timeout ?? "60"}`,
+        status_command: `enter-cli --output json thread status ${id}${target} --timeout 10`,
         follow_up_command: `enter-cli --output json thread chat ${id}${chatId ? ` --chat-id ${chatId}` : ""} --file <message-file>`,
-        instructions: "Accepted or timeout is not completion. Follow this task until blocked, failed or completed. Forward questions unchanged; approve only within existing authorization. Watching never approves or cancels remote work. Hosts own background scheduling.",
+        instructions: "Follow workflow.next_action; tool completion or CLI exit 0 is not Enter task completion. First handle incoming user messages: reply from the last observation before refreshing status. Briefly relay batched progress.messages as Enter-reported progress; do not infer progress from credits, timestamps, or tool activity. With no new narrative, observe quietly; on user inquiry report the last known state and any unavailable progress. Suppress repeated revisions and heartbeats. After a bounded observer exits while observation is still required, continue with wait_argv or validated wait_command, including after observation timeout. Do not end the task or ask whether to continue merely because wait returned. Shell-quote each wait_argv argument and invoke bare enter-cli without sleep, cd, or other prefixes. Stop observing on completed, failed, blocked, resolve_error, or resume_when_requested and handle that state. Forward questions unchanged; approve only within existing authorization. Prefer one background stream_argv invocation when the host delivers incremental output and can handle user messages concurrently. While that process is active, consume its events without starting another observer; report_progress means relay text, not restart the process. Use bounded wait only as a fallback for buffered output or completion-only notifications; batched progress ends that observation. Keep the returned timeout and progress interval; do not lengthen waits. Streaming wait and watch require incremental output delivery; consume output nonblockingly. Do not resubmit work. Hosts own scheduling; observation never cancels or approves remote work.",
     };
 }
 function positiveNumber(value, option, integer = false) {
@@ -380,15 +460,19 @@ function positiveNumber(value, option, integer = false) {
     return number;
 }
 async function readThreadSnapshot(id, turnNumber, signal, taskId, chatId) {
-    const data = await client.get(`/v1/projects/${id}/thread/turns`, chatId ? { chat_id: chatId } : undefined, signal);
+    // Both are read-only; serial reads unnecessarily consume the observation budget.
+    const turnsPromise = client.get(`/v1/projects/${id}/thread/turns`, chatId ? { chat_id: chatId } : undefined, signal);
+    const actionsPromise = fetchPendingActions(id, [], signal).then(actions => ({ actions }), error => ({ error }));
+    const data = await turnsPromise;
     const turns = data.turns ?? [];
     const selected = taskId ? turns.find(t => t.id === taskId || t.task_id === taskId)
         : turnNumber === undefined ? turns[0] : turns.find(t => Number(t.turn) === turnNumber);
     if (!selected && taskId) {
         const queue = await client.get(`/v1/projects/${id}/thread/tasks`, { simple: "true", ...(chatId ? { chat_id: chatId } : {}) }, signal);
-        return { status: queue.task_ids?.includes(taskId) ? "queued" : "unknown", project_id: id, turn: null,
-            reason: queue.task_ids?.includes(taskId) ? "task_queued" : "task_not_observed",
-            ...(!queue.task_ids?.includes(taskId) ? {
+        const queued = queue.task_ids?.includes(taskId);
+        return { status: queued ? "queued" : "unknown", project_id: id, turn: null,
+            reason: queued ? "task_queued" : "task_not_observed",
+            ...(!queued ? {
                 correlation: "unavailable",
                 project_activity: turns[0] ? pick(turns[0], ["id", "turn", "status", "chat_id", "commit_id"]) : null,
                 project_status_command: `enter-cli --output json thread status ${id}${chatId ? ` --chat-id ${chatId}` : ""}`,
@@ -403,7 +487,10 @@ async function readThreadSnapshot(id, turnNumber, signal, taskId, chatId) {
     if (["cancelled", "error", "failed"].includes(status)) {
         return { ...base, status: "failed", reason: `turn_${status}` };
     }
-    const pending = (await fetchPendingActions(id, [], signal)).filter(a => String(a.turn) === String(selected.turn));
+    const actionResult = await actionsPromise;
+    if ("error" in actionResult)
+        throw actionResult.error;
+    const pending = actionResult.actions.filter(a => String(a.turn) === String(selected.turn));
     if (pending.length) {
         const context = { signal };
         const actions = await Promise.all(pending.map(async (a) => {
@@ -435,22 +522,32 @@ async function readThreadSnapshot(id, turnNumber, signal, taskId, chatId) {
     return { ...base, status: "completed", project: { ...project, lifecycle_status: resolveLifecycleStatus(project) } };
 }
 function projectSnapshot(snapshot, compact = false) {
+    const workflow = workflowResult(snapshot);
     const result = { ...snapshot };
-    if (compact && snapshot.turn)
+    if (compact && snapshot.turn) {
         result.turn = pick(snapshot.turn, ["id", "turn", "status", "turn_name", "created_at", "updated_at", "commit_id", "chat_id"]);
+        if (typeof snapshot.turn.turn_name === "string")
+            result.turn.turn_name = snapshot.turn.turn_name.slice(0, 1000);
+    }
+    if (snapshot.status === "completed" && snapshot.turn) {
+        result.messages_command = `enter-cli --output json thread messages ${snapshot.project_id} --turn ${snapshot.turn.turn} --text`;
+    }
     if (snapshot.project) {
         const p = snapshot.project;
         if (compact)
             result.project = pick(p, ["project_id", "name", "status", "lifecycle_status", "commit", "commit_turn", "preview_url", "publish_url", "build_status"]);
-        const build = p.build_status;
-        result.build_matches_turn = Boolean(snapshot.turn?.commit_id && build?.commit_id === snapshot.turn.commit_id);
+        result.build_matches_turn = workflow.build?.matches_task ?? false;
         const supabase = p.supabase;
         result.integrations = { cloud: supabase?.status ?? "unknown", ai: p.ai_connection_state ?? (p.ai_capability_enabled === true ? "enabled" : "unknown") };
     }
-    return result;
+    result.workflow = workflow;
+    // Buffered hosts may truncate verbose metadata: keep the decision and continuation first.
+    return { status: snapshot.status, workflow,
+        ...(result.wait_command ? { wait_command: result.wait_command, wait_argv: result.wait_argv, instructions: result.instructions } : {}),
+        ...result };
 }
 // Owns observation and lifetime only; callers choose JSON or NDJSON rendering.
-async function observeThread(id, opts, wait, onSnapshot) {
+async function observeThread(id, opts, wait, onSnapshot, continuous = false) {
     let target = opts.turn === undefined ? undefined : positiveNumber(opts.turn, "--turn", true);
     if (opts.taskId && target !== undefined)
         throw new Error("Use only one of --task-id and --turn");
@@ -458,25 +555,35 @@ async function observeThread(id, opts, wait, onSnapshot) {
         throw new Error("--transport must be auto or poll");
     if (opts.cursor && !/^\d+-\d+$/.test(opts.cursor))
         throw new Error("--cursor must be an event ID such as 123-0");
-    const timeoutMs = positiveNumber(opts.timeout, "--timeout") * 1000;
+    if (opts.afterProgress && !/^[a-f0-9]{64}$/.test(opts.afterProgress))
+        throw new Error("--after-progress must be a returned progress revision");
+    const progressIntervalMs = Number(opts.progressInterval ?? "10") * 1000;
+    if (!Number.isFinite(progressIntervalMs) || progressIntervalMs < 0 || progressIntervalMs > 2147483647)
+        throw new Error("--progress-interval must be between 0 and 2147483 seconds");
+    const progressStartedAt = Date.now();
+    const timeoutMs = continuous && opts.timeout === "0" ? 0 : positiveNumber(opts.timeout, "--timeout") * 1000;
     if (timeoutMs > 2147483647)
         throw new Error("--timeout is too large");
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const timer = timeoutMs === 0 ? undefined : setTimeout(() => controller.abort(), timeoutMs);
     const interrupt = () => controller.abort("SIGINT");
     const terminate = () => controller.abort("SIGTERM");
     process.once("SIGINT", interrupt);
     process.once("SIGTERM", terminate);
     let last = { status: "unknown", project_id: id, turn: null };
     let querying = false;
+    let hasSnapshot = false;
+    let progressPromise;
+    let progressRead;
     let stream;
     let reconcileUntil = 0;
     const emit = (extra = {}, final = false) => onSnapshot({
         ...last,
         ...(["idle", "running", "queued", "pending", "unknown"].includes(last.status)
-            ? threadInteraction(id, { taskId: opts.taskId, chatId: opts.chatId, turn: target, requireBuild: opts.requireBuild }) : {}),
+            ? threadInteraction(id, { taskId: opts.taskId, chatId: opts.chatId, turn: target, requireBuild: opts.requireBuild,
+                timeout: wait ? opts.timeout : undefined, progressInterval: opts.progressInterval === "10" ? undefined : opts.progressInterval, afterProgress: last.progress?.messages.length ? last.progress.revision : opts.afterProgress }) : {}),
         ...(opts.taskId ? { task_id: opts.taskId } : {}),
-        ...(stream ? { transport: stream.mode, transport_reason: stream.reason, cursor: stream.cursor } : {}), ...extra,
+        ...(stream ? { transport: stream.mode, transport_reason: stream.reason, cursor: stream.cursor } : wait ? { transport: "polling" } : {}), ...extra,
     }, final);
     const interruption = () => {
         const reason = controller.signal.reason;
@@ -491,7 +598,32 @@ async function observeThread(id, opts, wait, onSnapshot) {
                 throw stream.failure;
             const revision = stream?.revision ?? 0;
             querying = true;
-            last = await readThreadSnapshot(id, target, controller.signal, opts.taskId, opts.chatId);
+            // A persistent observer still bounds each read so a stalled endpoint cannot hang forever.
+            const queryController = new AbortController();
+            const abortQuery = () => queryController.abort(controller.signal.reason);
+            controller.signal.addEventListener("abort", abortQuery, { once: true });
+            const queryTimer = setTimeout(() => queryController.abort(), 30000);
+            try {
+                last = await readThreadSnapshot(id, target, queryController.signal, opts.taskId, opts.chatId);
+                last.observed_at = new Date().toISOString();
+                hasSnapshot = true;
+            }
+            catch (error) {
+                if (queryController.signal.aborted && !controller.signal.aborted) {
+                    error = new RequestError("QUERY_TIMEOUT", "Enter status query exceeded its deadline.", true);
+                }
+                if (!wait || controller.signal.aborted || !(error instanceof RequestError) || !error.retryable)
+                    throw error;
+                querying = false;
+                emit({ ...errorEnvelope(error), observation_retrying: true, last_observed: hasSnapshot });
+                await delay(1000, undefined, { signal: controller.signal });
+                continue;
+            }
+            finally {
+                queryController.abort();
+                clearTimeout(queryTimer);
+                controller.signal.removeEventListener("abort", abortQuery);
+            }
             if (opts.requireBuild && last.status === "completed") {
                 const build = last.project?.build_status;
                 const matches = Boolean(last.turn?.commit_id && build?.commit_id === last.turn.commit_id);
@@ -501,6 +633,30 @@ async function observeThread(id, opts, wait, onSnapshot) {
                     last = { ...last, status: "failed", reason: "build_failed" };
             }
             querying = false;
+            if (last.turn && ["running", "completed"].includes(last.status)) {
+                if (!wait || last.status === "completed") {
+                    last.progress = await readProgress(id, last.turn, controller.signal, 3000);
+                }
+                else {
+                    const key = JSON.stringify([last.turn.id, last.turn.chat_id, last.turn.turn]);
+                    if (progressRead?.key !== key)
+                        progressRead = { key, pending: false, nextReadAt: 0 };
+                    const read = progressRead;
+                    if (!read.pending && Date.now() >= read.nextReadAt) {
+                        read.pending = true;
+                        read.nextReadAt = Date.now() + 2000;
+                        // Narrative latency must not delay authoritative state/card checks.
+                        progressPromise = readProgress(id, last.turn, controller.signal).then(value => {
+                            read.value = value;
+                            read.pending = false;
+                        });
+                    }
+                    last.progress = read.value ?? { source: "assistant_messages", available: false, messages: [] };
+                }
+            }
+            const stopped = interruption();
+            if (stopped !== undefined)
+                return stopped;
             if (target === undefined && last.turn && !opts.taskId)
                 target = positiveNumber(String(last.turn.turn), "server turn", true);
             // A newly accepted task can be temporarily absent from both reads. Keep
@@ -510,7 +666,9 @@ async function observeThread(id, opts, wait, onSnapshot) {
                 emit({}, true);
                 return last.status === "failed" || last.status === "unknown" ? 1 : 0;
             }
-            if (!stream && opts.transport !== "poll") {
+            if (controller.signal.aborted)
+                break;
+            if (!stream && opts.transport === "auto") {
                 stream = new ThreadEvents(id, {
                     signal: controller.signal, turn: target ?? (last.turn ? Number(last.turn.turn) : undefined),
                     chatId: opts.chatId ?? last.turn?.chat_id, cursor: opts.cursor, stateOnly: true,
@@ -518,16 +676,24 @@ async function observeThread(id, opts, wait, onSnapshot) {
                         reconcileUntil = Date.now() + 1500; },
                 });
             }
+            const progressChanged = last.progress?.available && last.progress.messages.length
+                && last.progress.revision !== opts.afterProgress;
+            if (!continuous && progressChanged && Date.now() - progressStartedAt >= progressIntervalMs) {
+                emit({ progress_changed: true }, true);
+                return 0;
+            }
             emit();
             if (stream)
                 await stream.wait(revision, Date.now() < reconcileUntil ? 250 : stream.mode === "websocket" ? 30000 : 2000);
-            else
-                await delay(2000, undefined, { signal: controller.signal });
+            else {
+                const pause = delay(2000, undefined, { signal: controller.signal });
+                await (progressRead?.pending && progressPromise ? Promise.race([pause, progressPromise]) : pause);
+            }
         }
         const interrupted = interruption();
         if (interrupted !== undefined)
             return interrupted;
-        emit({ wait_timed_out: true, query_timed_out: false }, true);
+        emit({ wait_timed_out: true, query_timed_out: false, last_observed: hasSnapshot }, true);
         return 2;
     }
     catch (error) {
@@ -535,13 +701,20 @@ async function observeThread(id, opts, wait, onSnapshot) {
         if (interrupted !== undefined)
             return interrupted;
         if (!controller.signal.aborted) {
-            emit({ ...errorEnvelope(error), last_observed: true }, true);
+            emit({ ...errorEnvelope(error), last_observed: true,
+                ...(error instanceof RequestError && error.code === "QUERY_TIMEOUT" ? { query_timed_out: true } : {}),
+            }, true);
             return 1;
         }
-        emit({ wait_timed_out: wait, query_timed_out: querying, ...(querying ? { error: { code: "QUERY_TIMEOUT", retryable: true, outcome_unknown: false } } : {}) }, true);
+        if (wait && hasSnapshot) {
+            emit({ wait_timed_out: true, query_timed_out: false, last_observed: true }, true);
+            return 2;
+        }
+        emit({ wait_timed_out: wait, query_timed_out: querying, ...(querying ? { error: { code: "QUERY_TIMEOUT", message: "The observation deadline expired before a status snapshot was available. Task state is unknown; this does not identify a network or server failure.", retryable: true, outcome_unknown: false } } : {}) }, true);
         return wait && !querying ? 2 : 1;
     }
     finally {
+        controller.abort();
         stream?.close();
         clearTimeout(timer);
         process.removeListener("SIGINT", interrupt);
@@ -551,38 +724,68 @@ async function observeThread(id, opts, wait, onSnapshot) {
 export async function reportThread(id, opts, cmd, wait, watch = false) {
     if (opts.full && opts.compact)
         throw new Error("Use only one of --full and --compact");
+    const progressIntervalMs = Number(opts.progressInterval ?? "10") * 1000;
+    const heartbeatIntervalMs = Math.max(30000, progressIntervalMs);
     let signature = "";
+    let lastOutputAt = 0;
+    let lastState = "";
+    let reportedProgress = opts.afterProgress;
     process.exitCode = await observeThread(id, opts, wait, (snapshot, final) => {
-        const data = projectSnapshot(snapshot, !opts.full && (opts.compact || watch));
+        if (!watch && !final)
+            return;
+        const now = Date.now();
+        const state = JSON.stringify([snapshot.status, snapshot.reason, snapshot.turn?.id, snapshot.error]);
+        const stateChanged = state !== lastState;
+        const intervalElapsed = now - lastOutputAt >= progressIntervalMs;
+        const heartbeatDue = now - lastOutputAt >= heartbeatIntervalMs;
+        // Skip output preparation inside the batch window without delaying state transitions.
+        if (watch && !final && !stateChanged && !intervalElapsed && !heartbeatDue)
+            return;
+        const progressChanged = Boolean(snapshot.progress?.available && snapshot.progress.messages.length
+            && snapshot.progress.revision !== reportedProgress);
+        const data = projectSnapshot({ ...snapshot, progress_changed: progressChanged }, !opts.full);
         if (!watch) {
-            if (final)
-                print(getFormat(cmd), safeOutput(data));
+            print(getFormat(cmd), safeOutput(data));
             return;
         }
         // Cursor-only changes should not flood agents with identical snapshots.
-        const next = JSON.stringify({ ...data, cursor: undefined });
-        if (next !== signature || final) {
-            process.stdout.write(JSON.stringify(safeOutput({ type: final ? "result" : "snapshot", ...data })) + "\n");
+        const next = JSON.stringify({ ...data, cursor: undefined, observed_at: undefined, progress_changed: undefined,
+            workflow: workflowResult({ ...snapshot, progress_changed: false }) });
+        const changed = next !== signature;
+        if (final || stateChanged || (changed && intervalElapsed) || heartbeatDue) {
+            lastState = state;
+            process.stdout.write(JSON.stringify(safeOutput({ type: final ? "result" : changed || snapshot.error ? "snapshot" : "heartbeat", ...data, progress_changed: progressChanged, emitted_at: new Date(now).toISOString() })) + "\n");
             signature = next;
+            lastOutputAt = now;
+            if (snapshot.progress?.available && snapshot.progress.messages.length)
+                reportedProgress = snapshot.progress.revision;
         }
-    });
+    }, watch);
 }
 for (const [name, timeout, description] of [
     ["status", "30", "Read one task snapshot; never wait for completion"],
-    ["wait", "10", "Wait for an action or terminal state using events with polling fallback"],
+    ["wait", "10", "Wait for batched progress, an action or terminal state using HTTP polling"],
     ["watch", "60", "Stream meaningful state changes as NDJSON; exit on pending actions or terminal state"],
 ]) {
-    threadCmd.command(`${name} <project_id>`).description(description)
+    const command = threadCmd.command(`${name} <project_id>`).description(description)
         .option("--turn <n>", "Select a fixed turn number")
         .option("--task-id <id>", "Follow exactly the task returned by chat/approve, including queue time")
         .option("--chat-id <id>", "Scope turn lookup and events to a chat")
         .option("--cursor <id>", "Resume stream after an event ID")
-        .option("--transport <mode>", "auto: WebSocket with fallback; poll: HTTP only", "auto")
+        .option("--after-progress <revision>", "Wait for narrative progress after a returned revision; preserves task identity")
+        .option("--progress-interval <seconds>", "Batch ordinary progress; 0 reports every change; actions/terminal states bypass this interval", "10")
+        .option("--transport <mode>", "poll: HTTP only (default); auto: opt in to WebSocket with fallback", "poll")
         .option("--require-build", "Require a matching successful build before reporting completion")
-        .option("--compact", "Return only monitoring fields (default for watch)")
-        .option("--full", "Include full sanitized metadata (default for status/wait)")
-        .option("--timeout <seconds>", "Bound the entire call without cancelling Enter", timeout)
-        .action(async (id, opts, cmd) => reportThread(id, opts, cmd, name !== "status", name === "watch"));
+        .option("--compact", "Return only monitoring fields (default)")
+        .option("--full", "Include full sanitized metadata, including usage")
+        .option("--timeout <seconds>", name === "watch" ? "Observation lifetime; 0 waits until action/terminal state or interruption" : "Bound the entire call without cancelling Enter", timeout)
+        .action(async (id, opts, cmd) => {
+        if (opts.stream && cmd.getOptionValueSource("timeout") === "default")
+            opts.timeout = "0";
+        await reportThread(id, opts, cmd, name !== "status", name === "watch" || Boolean(opts.stream));
+    });
+    if (name === "wait")
+        command.option("--stream", "Keep one observer running and emit batched NDJSON; default timeout 0, host owns background execution");
 }
 threadCmd
     .command("diff <project_id> <turn_number>")
@@ -600,7 +803,7 @@ threadCmd
         else {
             writeFileSync(path, JSON.stringify(data, null, 2));
         }
-        printMessage(`Diff written to ${path}`);
+        printResult(getFormat(cmd), { path }, `Diff written to ${path}`);
         return;
     }
     print(getFormat(cmd), data);
@@ -608,10 +811,11 @@ threadCmd
 threadCmd
     .command("cancel <project_id>")
     .description("Cancel the currently running turn. No-op if nothing is running.")
-    .action(async (id, _opts, cmd) => {
+    .option("--chat-id <id>", "Scope cancellation to this chat")
+    .action(async (id, opts, cmd) => {
     // Pre-check the latest turn — the server returns code 1000 even when
     // nothing is running, which is misleading. We want a clean idempotent no-op.
-    const turnsResp = await client.get(`/v1/projects/${id}/thread/turns`);
+    const turnsResp = await client.get(`/v1/projects/${id}/thread/turns`, opts.chatId ? { chat_id: opts.chatId } : undefined);
     const turns = turnsResp.turns ?? [];
     const latest = turns[0];
     const isRunning = latest && !TERMINAL_TURN_STATUSES.has(String(latest.status ?? ""));
@@ -622,11 +826,13 @@ threadCmd
             reason: "no_running_turn",
             latest_turn: latest?.turn ?? null,
             latest_status: latest?.status ?? null,
+            tasks_command: `enter-cli --output json thread tasks ${id}${opts.chatId ? ` --chat-id ${opts.chatId}` : ""}`,
         }, `Nothing to cancel (latest turn ${latest?.turn ?? "?"} status: ${latest?.status ?? "unknown"}).`);
         return;
     }
-    await client.post(`/v1/projects/${id}/thread/cancel`);
-    printResult(format, { cancelled: true, turn: latest.turn }, `Cancelled turn ${latest.turn}.`);
+    const chatId = opts.chatId ?? latest.chat_id;
+    await client.post(`/v1/projects/${id}/thread/cancel`, chatId ? { chat_id: chatId } : undefined);
+    printResult(format, { cancelled: true, turn: latest.turn, ...(chatId ? { chat_id: chatId } : {}) }, `Cancelled turn ${latest.turn}.`);
 });
 threadCmd
     .command("restore <project_id>")
@@ -756,7 +962,7 @@ threadCmd
     .option("--secret-value-stdin", "Read the secret value from stdin instead of process arguments")
     .option("--auth-config-stdin", "Read configuration JSON for the action's auth provider from stdin; credentials never go into the approval response")
     .option("--tool-result <result>", "Custom tool result string")
-    .option("--answers <json>", 'Answers for ask_user_question, JSON: \'{"Q text": {"selected_options": ["A"], "other_text": ""}}\'')
+    .option("--answers <json>", `Answers for ask_user_question. ${ANSWERS_FORMAT}`)
     .option("--skip-answers", "Skip all questions for ask_user_question (sets skipped: true)")
     .action(async (projectId, actionIdArg, opts, cmd) => {
     const format = getFormat(cmd);
@@ -792,7 +998,17 @@ threadCmd
         }
         const data = await client.get(configPath);
         if (data.config?.providers?.[provider]?.enabled !== true) {
-            throw new Error(`Auth provider ${provider} is not enabled. Configure it through Enter's secure form or --auth-config-stdin before approval.`);
+            print(format, {
+                status: "blocked", reason: "auth_provider_configuration_required",
+                project_id: projectId, approved: false,
+                actions: [{
+                        action_id: action.action_id, tool_name: action.tool_name, turn: action.turn,
+                        input_kind: "auth_provider", ...authProviderInput(provider),
+                        approve_command: buildApproveCommand(projectId, action),
+                    }],
+                next_step: "Provide the missing fields via --auth-config-stdin, or save them in Enter's provider form and query thread status. Continue with existing authorized input without asking the user to enter it again.",
+            });
+            return;
         }
         // The backend additionally verifies stored credentials and the card's
         // ExpectedProvider before claiming the action. Never send credentials here.
@@ -819,10 +1035,10 @@ threadCmd
     if (answers) {
         for (const answer of Object.values(answers)) {
             if (!answer || typeof answer !== "object" || Array.isArray(answer))
-                throw new Error("Each answer must be an object");
+                throw new Error(`Invalid --answers: each answer must be an object. ${ANSWERS_FORMAT}`);
             const value = answer;
             if (!Array.isArray(value.selected_options) || !value.selected_options.every(item => typeof item === "string") || (value.other_text !== undefined && typeof value.other_text !== "string")) {
-                throw new Error("Each answer requires selected_options as a string array and optional other_text as a string");
+                throw new Error(`Invalid --answers: selected_options must be a string array and other_text an optional string. ${ANSWERS_FORMAT}`);
             }
         }
     }