@enter-pro/enter-cli 0.4.3 → 0.4.4

package/README.md

@@ -31,7 +31,7 @@ unset the variable in your shell.
 enter-cli --output json thread chat PROJECT_ID --file requirement.txt
 enter-cli --output json thread wait PROJECT_ID --task-id TASK_ID --timeout 10
 enter-cli --output json thread status PROJECT_ID --task-id TASK_ID
-enter-cli thread watch PROJECT_ID --task-id TASK_ID --timeout 60
+enter-cli thread wait PROJECT_ID --task-id TASK_ID --stream --timeout 0
 ```
 
 `chat --stdin` also accepts multiline input. Submission returns immediately with
@@ -41,16 +41,16 @@ can be submitted while Enter works; acceptance is not completion.
 | Command | Output and default lifetime |
 | --- | --- |
 | `status` | One JSON/YAML snapshot, 30-second deadline |
-| `wait` | One result on a card, terminal state or timeout; 10 seconds |
-| `watch` | Changed snapshots as NDJSON, then `type: result`; 60 seconds |
+| `wait --stream` | One continuous observer with batched NDJSON; unlimited by default, explicit --timeout bounds lifetime |
+| `wait` | One result on new narrative progress, a card, terminal state or timeout; 10 seconds |
+| `watch` | Changed snapshots as NDJSON, then `type: result`; 60 seconds; unlimited only with explicit `--timeout 0` |
 
-Use one observer per task. In interactive agents, use the returned short wait,
-handle incoming user messages, then continue the same task. Normal observation
-timeout is not a reason to increase the wait or resubmit. Background watch is
-appropriate only with completion notifications and non-blocking output collection;
-do not immediately block on the job for minutes. CLI lifetime and host job-wait
-limits are separate upper bounds, not measured elapsed time. Hosts own message
-scheduling: CLI events cannot make a blocked host process new user input.
+Use one observer per task. Hosts that buffer shell output use bounded `wait`;
+Helix uses `--timeout 10` to return control regularly. On timeout, first handle
+incoming user messages, then report the actual state and continue the returned command for the same task,
+without sleep, resubmission or repeated permission questions. Hosts that consume
+stdout incrementally should use `wait --stream`; unchanged successful observations emit a
+heartbeat every max(30 seconds, progress interval). Hosts own scheduling and interruption.
 
 `--task-id` follows exactly the submitted task, including queue time. `--turn N`
 selects a fixed turn instead; without either, observation pins the first turn.
@@ -70,8 +70,8 @@ messages and the resulting change, and do not substitute the newest turn.
 
 `project create --wait` uses the same observer and requires a matching successful
 build. For existing tasks use `--require-build`; stale builds cannot satisfy it.
-`build_matches_turn` checks commit identity. `status/wait` retain full metadata;
-`--compact` selects monitoring fields. `watch` is compact unless `--full` is set.
+`build_matches_turn` checks commit identity. `status/wait/watch` return monitoring fields by default, excluding usage and unrelated metadata.
+Use `--full` for detailed sanitized metadata; `--compact` remains an explicit alias for the default.
 The additive `workflow` projection supplies `state`, `task`, `next_action`,
 `observation`, build matching and action descriptors; full card details remain in
 `actions`. `use_existing_authorization` does not grant new permission.
@@ -90,14 +90,12 @@ separately; do not replace Enter's validation with source keyword scans.
 
 ## Transport and errors
 
-Observation uses authenticated WebSocket events, reconnects with `last_event_id`,
-deduplicates replay, and re-reads authoritative HTTP state. Healthy streams have a
-30-second safety refresh; unavailable streams fall back to 2-second HTTP checks.
-Text/argument deltas do not trigger full queries; card persistence gets a short
-reconciliation window. `--transport poll` forces HTTP, `--cursor` resumes events,
-and `transport/transport_reason/cursor` identify progress. Stream 401/403 fails explicitly;
-unsupported endpoints fall back without repeated reconnects. WebSockets respect
-proxy variables and `NO_PROXY`; `NODE_USE_ENV_PROXY=0` disables their proxy use.
+Observation defaults to HTTP polling every 2 seconds after each read. Each
+snapshot query is bounded to 30 seconds. No WebSocket is opened by default.
+`--transport auto` opts in to WebSocket events with HTTP fallback; 401/403 on the
+stream stops reconnection but leaves state observation on HTTP. Raw message
+follow still fails with STREAM_AUTH_ERROR. HTTP authentication failures stop
+observation. WebSockets respect proxy variables and NO_PROXY.
 
 `thread messages PROJECT_ID --follow --timeout 60 --cursor EVENT_ID` emits raw
 NDJSON events with diagnostics on stderr. It supports `--max-events`, crosses turn
@@ -142,7 +140,7 @@ npm ci
 npm test
 npm run build
 npm pack
-npm run install:hosts -- --package /absolute/path/enter-pro-enter-cli-0.4.3.tgz
+npm run install:hosts -- --package /absolute/path/enter-pro-enter-cli-0.4.4.tgz
 ```
 
 Tests use loopback HTTP/WebSocket fixtures and dummy credentials, not real cloud
@@ -165,3 +163,87 @@ Scenarios: `plan`, `cloud`, `ai`, `secret`, `questions`, `subscription`, `runnin
 unsupported routes fail, and request bodies/secrets are not retained. Only use
 fake values. `.env.integration.example` lists real-test variables; its ignored
 `.env.integration.local` counterpart is never loaded automatically.
+
+### Agent host integration
+
+All observers return `progress` from the selected task's HTTP message history:
+`source: assistant_messages`, `available`, a scoped `revision`, and the latest
+assistant text in `messages` (up to 1600 characters, marked `truncated` if clipped).
+Reasoning and raw tool arguments are excluded. `observed_at` timestamps the last
+successful state read; `emitted_at` timestamps watch output, including stale results.
+A narrative read failure is separate from authoritative task/action status.
+
+`wait` batches ordinary narrative for 10 seconds by default, keeping the latest text,
+and returns early when that interval has elapsed and progress changed.
+`--progress-interval <seconds>` controls batching; `0` opts into every change.
+Actions, terminal states and errors bypass batching. The overall `--timeout` still
+bounds the call and returns the latest observation even before the interval elapses.
+`status` remains an immediate read; no phase is guessed from narrative keywords. `workflow.next_action=report_progress` means relay the text first, then `after_reporting=observe`. Exit 0 means an observation result, not build completion. Execute the returned `wait_command`, including
+`--after-progress`, to wait for the next revision without replaying the same update.
+`watch` uses the same interval for ordinary narrative/metadata updates; state changes
+and final results are emitted immediately.
+These are latest-progress snapshots, not a lossless replay of every message.
+
+The host agent relays the supplied text, forwards questions, and executes the next
+command; it need not reason over logs or infer development phases. Relay new progress
+proactively, suppress repeated revisions/heartbeats, and answer user questions from
+the last observation before refreshing. Background hosts with only completion notifications fall back to bounded `wait`: batched progress ends the job and triggers that notification. Merely being able to read running stdout is insufficient for automatic `watch` delivery. For background jobs, read output nonblockingly
+or with a short bounded wait; a five-minute blocking job-output call defeats background
+execution. The CLI cannot schedule the host agent or interrupt its tool calls.
+
+Both `wait` and `watch` use HTTP by default. The CLI performs the polling;
+do not generate `sleep && enter-cli` or a loop of `thread status` commands.
+
+For hosts that return shell output only after the command exits, use `wait`.
+For the current Helix integration, use a short 10-second observation window
+to return control for incoming messages:
+
+```bash
+enter-cli --output json thread wait PROJECT_ID --task-id TASK_ID --timeout 10
+```
+
+The CLI and Helix guidance both default to 10 seconds. A shell deadline alone
+does not guarantee responsiveness. On exit 2, handle incoming messages, report
+the returned Enter stage/status and execute the returned `wait_command` to keep observing.
+It preserves the task or pinned turn, chat, build requirement and observation
+timeout. Do not ask the user whether to continue, recreate the project or
+resubmit the build. A timeout ends observation, not the remote task. On
+`blocked`, forward the action and follow the continuation after answering;
+on `completed` or `failed`, consume the result.
+
+For hosts that notify the agent when incremental stdout arrives without blocking user interaction,
+use `watch_command` (60 seconds by default). Only explicitly select `--timeout 0`
+when the host can manage an unlimited background observer.
+`snapshot` contains actual Enter task/turn state, `heartbeat` confirms a
+successful observation without a state change, and `result` ends observation.
+This is stage/status progress, not generated percentages or a raw model-token
+log. Each snapshot query has a 30-second deadline. SIGINT/SIGTERM stop only
+the observer (130/143); the host owns background execution and reconnection.
+
+The current Helix sandbox adapter buffers stdout until command completion;
+therefore an indefinitely running `watch` is not its default integration path.
+Helix colleagues only need to update the actual sandbox CLI and the agent's
+usage instructions for the bounded `wait` path, then verify it in a fresh
+sandbox. Continuous in-flight display requires host-side incremental output
+support; local CLI tests do not prove that integration.
+
+State and pending-action reads run concurrently to avoid spending the observation
+budget on sequential independent requests. Failed turns do not wait for pending
+action reads. `QUERY_TIMEOUT` before the first snapshot means the observation
+deadline expired without a known task state; it does not locate the cause in the
+network or server. The overall deadline remains bounded. Usage changes are not
+progress; continue quietly when there is no new narrative or actionable state.
+
+### One background observer
+
+Use `enter-cli thread wait PROJECT_ID --task-id TASK_ID --stream --timeout 0`
+with a host that supports managed background execution and incremental output delivery.
+The CLI polls HTTP internally and emits batched progress until an action, terminal state,
+interruption or explicit deadline. Ordinary progress does not end this process.
+Consume events without blocking user interaction; do not restart it on report_progress.
+The returned `stream_argv` / `stream_command` starts this observer.
+`watch` remains a compatible streaming entry point.
+
+Without `--stream`, wait retains its bounded single-JSON contract for buffered hosts.
+This fallback can require repeated calls; CLI cannot enable host background scheduling.
+Do not detach with shell `&` or assume buffered Bash output is delivered incrementally.

package/dist/commands/project.js

@@ -91,7 +91,7 @@ projectCmd
     .option("--prompt <text>", "Initial prompt for the project")
     .option("--model <id>", "Pin AI model (see `enter-cli models list`). Invalid IDs silently fall back to 'auto'.")
     .option("--plan-mode", "Start the project in Plan Mode (first turn produces a plan instead of code)")
-    .option("--wait", "Wait until the first build completes")
+    .option("--wait", "Observe the first build; return on progress, input, completion or timeout")
     .option("--timeout <seconds>", "Timeout for --wait in seconds", "300")
     .action(async (id, opts, cmd) => {
     const seconds = Number(opts.timeout);

package/dist/commands/thread.d.ts

@@ -5,8 +5,11 @@ type InteractionOptions = {
     chatId?: string;
     turn?: number;
     requireBuild?: boolean;
+    timeout?: string;
+    afterProgress?: string;
+    progressInterval?: string;
 };
-export declare function threadInteraction(id: string, { taskId, chatId, turn, requireBuild }?: InteractionOptions): {
+export declare function threadInteraction(id: string, { taskId, chatId, turn, requireBuild, timeout, afterProgress, progressInterval }?: InteractionOptions): {
     workflow: {
         actions?: {
             id: unknown;
@@ -26,6 +29,7 @@ export declare function threadInteraction(id: string, { taskId, chatId, turn, re
             interrupted: boolean;
         };
         reason?: string | undefined;
+        after_reporting?: string | undefined;
         state: string;
         task: {
             id: {} | null;
@@ -36,6 +40,9 @@ export declare function threadInteraction(id: string, { taskId, chatId, turn, re
     };
     monitoring_required: boolean;
     wait_command: string;
+    wait_argv: string[];
+    stream_command: string;
+    stream_argv: string[];
     watch_command: string;
     status_command: string;
     follow_up_command: string;
@@ -47,6 +54,8 @@ type MonitorOptions = {
     chatId?: string;
     cursor?: string;
     timeout: string;
+    afterProgress?: string;
+    progressInterval?: string;
     transport?: string;
     full?: boolean;
     compact?: boolean;

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";
@@ -319,13 +320,7 @@ threadCmd
         params.end_turn = endTurn;
     const data = await client.get(`/v1/projects/${id}/thread/messages`, params);
     if (opts.text) {
-        const rows = Array.isArray(data) ? data : data.messages ?? [];
-        const messages = rows.flatMap((row) => {
-            const content = row?.detail?.assistant_content?.content;
-            return row?.message_type === "assistant_content" && typeof content === "string"
-                ? [{ turn: row.turn, text: content }] : [];
-        });
-        print(getFormat(cmd), safeOutput({ messages }));
+        print(getFormat(cmd), safeOutput({ messages: assistantMessages(data) }));
     }
     else
         print(getFormat(cmd), data);
@@ -397,17 +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} --timeout 10`,
-        watch_command: `enter-cli thread watch ${id}${target} --timeout 60`,
+        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. Use short foreground waits and handle new user messages before continuing observation. Use background watch only with non-blocking output collection and completion notifications; do not follow it with a long blocking job wait. Observation timeout is normal: keep the same task and bounded wait, rather than increasing timeouts. CLI observation timeout and host job-wait timeout are separate limits, not elapsed time. Watching never approves or cancels remote work.",
+        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) {
@@ -418,7 +460,10 @@ 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);
@@ -442,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) => {
@@ -476,8 +524,11 @@ async function readThreadSnapshot(id, turnNumber, signal, taskId, chatId) {
 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`;
     }
@@ -490,10 +541,13 @@ function projectSnapshot(snapshot, compact = false) {
         result.integrations = { cloud: supabase?.status ?? "unknown", ai: p.ai_connection_state ?? (p.ai_capability_enabled === true ? "enabled" : "unknown") };
     }
     result.workflow = workflow;
-    return result;
+    // 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");
@@ -501,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;
@@ -534,19 +598,32 @@ async function observeThread(id, opts, wait, onSnapshot) {
                 throw stream.failure;
             const revision = stream?.revision ?? 0;
             querying = true;
+            // 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, controller.signal, opts.taskId, opts.chatId);
+                last = await readThreadSnapshot(id, target, queryController.signal, opts.taskId, opts.chatId);
+                last.observed_at = new Date().toISOString();
+                hasSnapshot = true;
             }
             catch (error) {
-                // A read outage does not end remote work. Keep bounded observation alive;
-                // never retry writes or authentication/permission failures here.
+                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: true });
+                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);
@@ -556,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
@@ -565,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,
@@ -573,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) {
@@ -590,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);
@@ -606,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>")

package/dist/thread-events.js

@@ -110,7 +110,10 @@ export class ThreadEvents {
             if ([401, 403].includes(status)) {
                 retryable = false;
                 reason = status === 401 ? "authentication_required" : "permission_denied";
-                this.failure = new RequestError("STREAM_AUTH_ERROR", "Enter event stream rejected access. Check authentication and project permissions.");
+                // State observers retain authoritative HTTP polling; raw message followers cannot.
+                if (!this.options.stateOnly) {
+                    this.failure = new RequestError("STREAM_AUTH_ERROR", "Enter event stream rejected access. Check authentication and project permissions.");
+                }
             }
             else if ([404, 405, 426, 501].includes(status)) {
                 retryable = false;

package/dist/workflow.d.ts

@@ -10,6 +10,7 @@ export interface WorkflowSnapshot {
     interrupted?: boolean;
     wait_timed_out?: boolean;
     observation_retrying?: boolean;
+    progress_changed?: boolean;
     error?: {
         retryable?: boolean;
     };
@@ -34,6 +35,7 @@ export declare function workflowResult(snapshot: WorkflowSnapshot): {
         interrupted: boolean;
     };
     reason?: string | undefined;
+    after_reporting?: string | undefined;
     state: string;
     task: {
         id: {} | null;

package/dist/workflow.js

@@ -10,12 +10,14 @@ export function workflowResult(snapshot) {
             : state === 'needs_input' ? 'handle_actions'
                 : state === 'completed' ? 'read_delivery'
                     : state === 'failed' ? 'report_failure'
-                        : state === 'idle' ? 'none'
-                            : 'observe';
+                        : snapshot.progress_changed ? 'report_progress'
+                            : state === 'idle' ? 'none'
+                                : 'observe';
     return {
         state,
         task: { id: snapshot.task_id ?? turn?.task_id ?? turn?.id ?? null, turn: turn?.turn ?? null, chat_id: turn?.chat_id ?? null },
         next_action: next,
+        ...(next === "report_progress" ? { after_reporting: "observe" } : {}),
         ...(snapshot.reason ? { reason: snapshot.reason } : {}),
         observation: { timed_out: Boolean(snapshot.wait_timed_out), retrying: Boolean(snapshot.observation_retrying), interrupted: Boolean(snapshot.interrupted) },
         ...(snapshot.project ? { build: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enter-pro/enter-cli",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "Enter CLI - manage Enter platform resources from the command line",
   "type": "module",
   "main": "dist/index.js",

package/skills/enter/SKILL.md

@@ -14,17 +14,21 @@ description: 使用 Enter CLI 创建和修改网站或应用，跟踪任务、
 ## 流程
 
 1. 从用户上下文确定项目；新建时确定 workspace。通过 `project create` 或 `thread chat` 提交一次，保存 task_id。accepted 或观察超时不代表完成，也不是重新提交的理由。
-2. 按下方观察规则执行返回的 wait_command，按同一 task_id 继续；需交付构建时加 `--require-build`。新增需求单独记录返回的 task_id。
+2. 按下方宿主能力规则选择返回的 stream_command 或 wait_command，按同一 task_id 继续；需交付构建时加 `--require-build`。新增需求单独记录返回的 task_id。
 3. 状态的 `workflow` 给出任务关联、next_action 和构建匹配信息。遇到 `handle_actions` 按下方卡片规则处理；`read_delivery` 执行 messages_command，取得 Enter 的总结与验证证据。未知关联不代表提交失败，不猜测它属于其他已完成任务。
 4. 依用户已有授权继续，不因阶段切换反复确认。明确要求用户决策的计划和提问仍需转交。写操作超时或解析失败先查真实状态，再决定是否重试。
 5. 交付说明完成内容、预览/发布地址、Enter 验证结果及待配置项；代码存在、配置保存、构建成功、真实服务可用分开判断。发布按用户授权范围执行。
 
 ## 观察与响应
 
-- 默认执行短时 wait（返回命令为 10 秒），返回后先处理用户新消息，再按同一任务续接。观察超时只结束本次观察；不要为等到完成不断增加超时，也不要重新提交任务。
-- 只有宿主支持完成通知和非阻塞取结果时，才选择后台 watch。启动后让出对话执行权，由通知续接；不要再用数分钟的阻塞工具等待后台任务。若无法可靠接收通知，使用短时 wait。始终只保留一个观察路径，不叠加 sleep 或反复查询。
-- 用户问进度时，先用最新已知状态答复并标明是否为上次观察；需要刷新再执行一次 status，随后继续原任务。不要等到构建完成才回答。收到完成通知先读取该任务结果，再决定是否需要继续观察。
-- CLI 的 `--timeout` 限制观察进程寿命，宿主的取结果等待参数限制一次工具调用；两者都不是实际耗时。耗时看时间戳，任务是否结束看返回状态，不能由等待上限推断卡死。
+- CLI 用 HTTP 获取真实状态与 Enter 最新进度原文。宿主作为传话者：`workflow.next_action=report_progress` 时先转述 `progress.messages`，再按 `after_reporting=observe` 续接；处理其他 `workflow.next_action`，执行返回的命令；不翻原始日志自行分析开发阶段，不把 Enter 的自述当独立验收。`progress.available=false` 表示暂时无法获取进度，不能说没有进展；有数据但 revision 未变才是没有新内容。不编造百分比，不用额度消耗、时间戳变化证明进展。默认只读取监控字段，除非用户查询详情，不使用 --full。
+- 首选单个 `stream_command`（`thread wait --stream --timeout 0`）：仅在宿主支持后台执行、增量输出通知和同时处理用户消息时使用。CLI 内部轮询，宿主非阻塞消费阶段性事件；运行期间不要另起 wait，不因 report_progress 重启观察。收到最终 result 后再按状态处理；不使用 shell & 脱离宿主管理。watch 保留为同一流式观察能力的兼容入口。
+- 同步或仅有完成通知的宿主回退到 `wait_command`：它在普通进度合并窗口到达且有新进展时退出，所以只支持任务完成通知的后台宿主，也能被新进展唤醒。支持后台任务时在后台运行并用完成通知续接，不阻塞等整个网站完成；同步宿主直接执行有界 wait。
+- `wait` 返回 `progress_changed=true` 时直接简短转述，再执行带 `--after-progress` 的续接命令。只有确认宿主能在新 stdout 到达时唤醒 Agent，才选择 `watch_command`；仅能手动读取运行中输出还不够。不得用反复 job_output 空读替代通知，也不得阻塞读取直到后台任务结束。watch 无限观察仅显式 `--timeout 0`。
+- 按 CLI 合并后的进展简短汇报；细碎技术变化无需逐条复述。面向用户不解释 CLI 协议、job 状态或调度过程。相同 revision、heartbeat 和无变化超时无需重复刷屏。超时结束的是本次观察，不是远端工作。保持同一 task_id、turn、chat 和构建要求，不重提、不询问是否继续，不写 sleep 或 status 循环。
+- 用户插话时立即用最近已知的进度与 `observed_at` 回答，标明是上次观察；之后按需刷新一次 status，再继续原任务。不要为了拿最新状态先阻塞回答。新增需求才提交 chat，单纯问进度不触发构建。
+- 普通进度默认每 10 秒合并一次（`--progress-interval`），保留最新原文，不猜测阶段；问题卡、完成和失败立即返回。保留返回的间隔与时限，不自行调长等待。
+- `wait` 默认最多 10 秒，`watch` 默认 60 秒，显式时限会保留在续接命令中。这是观察上限，不是心跳周期或响应保证；不得为等到完成不断延长阻塞调用。宿主如果本身不支持插话或后台唤醒，CLI 不能保证即时响应或主动通知。
 
 ## 卡片
 
@@ -33,4 +37,4 @@ description: 使用 Enter CLI 创建和修改网站或应用，跟踪任务、
 - 普通确认：已有授权就 approve；需要新的决定时询问。用户拒绝才 reject。
 - 配置输入：已有授权和值/文件就提交；缺什么只问什么。普通配置可直接询问，真实密钥使用可用的安全输入或用户指定文件；表单是替代入口，不强制绕路。OAuth/secret/Stripe 的字段、stdin 和更新方法见 [配置输入](references/configuration.md)，仅遇到这些卡片时读取。
 
-CLI 负责事件监听、断线恢复和查询兜底；宿主负责后台调度与用户交互。等待工具不自动批准卡片。宿主没有浏览器不影响 Enter 内部验证，不以关键词扫描替代其验证结果。
+CLI 负责 HTTP 观察和可选的事件监听；宿主负责后台调度与用户交互。等待工具不自动批准卡片。宿主没有浏览器不影响 Enter 内部验证，不以关键词扫描替代其验证结果。