@united-workforce/cli 0.6.1 → 0.8.1

package/dist/commands/step.js

@@ -1,7 +1,6 @@
-import { execFileSync } from "node:child_process";
 import { createLogger, generateUlid } from "@united-workforce/util";
-import { getAskSessionId, loadWorkflowConfig, setAskSessionId } from "@united-workforce/util-agent";
-import { createUwfStore, setThread } from "../store.js";
+import { isThreadRunning } from "../background/index.js";
+import { createUwfStore, getActiveStep, getActiveTurnHead, getThread, readActiveTurnRoles, readActiveTurns, setThread, turnsOfStep, } from "../store.js";
 import { collectOrderedSteps, expandDeep, expandOutput, fail, resolveHeadHash, walkChain, } from "./shared.js";
 const log = createLogger({ sink: { kind: "stderr" } });
 /**
@@ -128,7 +127,14 @@ export async function cmdStepList(storageRoot, threadId) {
     };
 }
 /**
- * Show details of a specific step (previously: thread step-details)
+ * Show details of a specific step (previously: thread step-details).
+ *
+ * Returns a merged object that combines StepNode metadata (role / agent /
+ * timing / usage) with the expanded broker-detail payload so callers can
+ * read both layers in one envelope. The detail node by itself only carries
+ * `{ sessionId, duration, turnCount, turns }` — without merging in the
+ * StepNode metadata, `step show` would render empty `Role` / `Agent` /
+ * `Status` / `-` `Duration` (issue #392).
  */
 export async function cmdStepShow(storageRoot, stepHash) {
     const uwf = await createUwfStore(storageRoot);
@@ -143,7 +149,34 @@ export async function cmdStepShow(storageRoot, stepHash) {
     if (!payload.detail) {
         fail(`step ${stepHash} has no detail`);
     }
-    return expandDeep(uwf.store, payload.detail);
+    const detail = expandDeep(uwf.store, payload.detail);
+    const output = expandOutput(uwf, payload.output);
+    const status = output !== null &&
+        typeof output === "object" &&
+        !Array.isArray(output) &&
+        typeof output.$status === "string"
+        ? output.$status
+        : "";
+    const startedAtMs = typeof payload.startedAtMs === "number" && Number.isFinite(payload.startedAtMs)
+        ? payload.startedAtMs
+        : null;
+    const completedAtMs = typeof payload.completedAtMs === "number" && Number.isFinite(payload.completedAtMs)
+        ? payload.completedAtMs
+        : null;
+    const durationMs = startedAtMs !== null && completedAtMs !== null && completedAtMs >= startedAtMs
+        ? completedAtMs - startedAtMs
+        : null;
+    return {
+        hash: stepHash,
+        role: payload.role,
+        agent: payload.agent,
+        status,
+        startedAtMs,
+        completedAtMs,
+        durationMs,
+        usage: payload.usage ?? null,
+        detail,
+    };
 }
 /**
  * Fork a thread from a specific step (previously: thread fork)
@@ -343,159 +376,476 @@ export async function cmdStepRead(storageRoot, stepHash, quota, showPrompt) {
     const selectedTurns = selectTurnsForQuota(turnData, availableQuota);
     return formatStepMarkdown(stepHash, payload.role, payload.agent, turnData, selectedTurns);
 }
-// ── step ask ────────────────────────────────────────────────────────────────
-function parseAgentOverride(override) {
-    const parts = override
-        .trim()
-        .split(/\s+/)
-        .filter((p) => p.length > 0);
-    const command = parts[0];
-    if (command === undefined) {
-        fail("agent override must not be empty");
-    }
-    return { command, args: parts.slice(1) };
-}
-function resolveAskAgentConfig(config, workflow, role, agentOverride, recordedAgent) {
-    if (agentOverride !== null) {
-        const fromAlias = config.agents[agentOverride];
-        if (fromAlias !== undefined) {
-            return fromAlias;
+// ── step turns ────────────────────────────────────────────────────────────────
+//
+// Phase 4 (#400) / #409 — the consumer side of the realtime-turns RFC. `step
+// turns <thread-id>` renders the **whole-thread turn panorama**: it walks the
+// entire thread chain (reusing the SAME `walkChain` + `collectOrderedSteps`
+// infrastructure as `cmdStepList`) and shows every step's turns in chronological
+// order, each turn attributed to its owning role/step.
+//
+// Per-step turn sourcing (active-var precedence, scoped to each step's role):
+//   - the in-flight step (its `@uwf/active-turns/<tid>/<role>` var still present)
+//     → read the live active var and mark the step `🔄 进行中`;
+//   - every completed step → read its own immutable `detail.turns` and mark `✓`.
+// Both sources are a `CasRef[]` of pure `{role, content}` turn nodes, so per-turn
+// rendering reuses the SAME `loadTurnData` → `formatTurnBody` pipeline as
+// `step read` — a turn block here is byte-identical to `step read` for that step.
+//
+// `--role X` filters the panorama to that role's steps (across the whole chain);
+// `--limit`/`--offset` paginate the flattened cross-step turn sequence (filter
+// first, then paginate). Default is full, untruncated output. Because turns are
+// always sourced per-step, role isolation (#408) falls out structurally — the
+// head-only `readHeadDetailTurns` role-guard hack is obsolete.
+/** Default poll interval for `--live` (ms). Small + fixed; injectable for tests. */
+export const STEP_TURNS_POLL_INTERVAL_MS = 400;
+/** Fill optional CmdStepTurnsOptions fields with their runtime defaults. */
+function resolveStepTurnsOptions(storageRoot, threadId, options) {
+    return {
+        role: options.role ?? null,
+        live: options.live,
+        limit: options.limit ?? null,
+        offset: options.offset ?? 0,
+        pollIntervalMs: options.pollIntervalMs ?? null,
+        onChunk: options.onChunk ?? null,
+        sleep: options.sleep ?? null,
+        isRunning: options.isRunning ?? (async () => (await isThreadRunning(storageRoot, threadId)) !== null),
+    };
+}
+/**
+ * Walk the thread chain from `headHash` and return the **newest** step whose
+ * `role === role`'s immutable `detail.turns`, or `[]` when no step on the chain
+ * has that role. Used by the `--live` exit reconcile to flush the followed role's
+ * own solidified turns without ever surfacing a *different* role's turns: in a
+ * multi-step run the head may have advanced past the followed step to another
+ * role, so reconciling against `head` blindly (the pre-#409 `readHeadDetailTurns`)
+ * could leak the next role's turns. Scoping to the followed role's own step on
+ * the chain is the live counterpart of the non-live per-step sourcing.
+ */
+function readRoleDetailTurnsFromChain(uwf, headHash, role) {
+    let hash = headHash;
+    while (hash !== null) {
+        const node = uwf.store.cas.get(hash);
+        if (node === null || node.type !== uwf.schemas.stepNode) {
+            break;
         }
-        return parseAgentOverride(agentOverride);
-    }
-    // Try to resolve via the recorded agent name as a config alias.
-    const fromRecorded = config.agents[recordedAgent];
-    if (fromRecorded !== undefined) {
-        return fromRecorded;
-    }
-    // Fall back to default agent for the workflow / role.
-    if (workflow !== null && config.agentOverrides !== null) {
-        const roleOverrides = config.agentOverrides[workflow.name];
-        if (roleOverrides !== undefined && roleOverrides[role] !== undefined) {
-            const alias = roleOverrides[role];
-            const agentConfig = config.agents[alias];
-            if (agentConfig !== undefined) {
-                return agentConfig;
-            }
+        const payload = node.payload;
+        if (payload.role === role) {
+            return readStepDetailTurns(uwf, hash);
         }
+        hash = payload.prev;
     }
-    // Treat the recorded value as a raw command path.
-    return parseAgentOverride(recordedAgent);
+    return [];
 }
 /**
- * Derive the agent name used for cache file partitioning from an executable
- * path or alias.  Examples:
- *   uwf-hermes        → hermes
- *   uwf-claude-code   → claude-code
- *   /tmp/mock-agent.sh → mock
- *   /usr/bin/agent    → agent
+ * Read a specific step's immutable `detail.turns` (the ordered `CasRef[]` of its
+ * turn nodes). Returns `[]` for a non-StepNode, a step with no detail, or a
+ * detail whose `turns` is absent/malformed. Unlike `readHeadDetailTurns` this is
+ * role-agnostic — the caller already knows which step it is reading (the chain
+ * walk attributes each step to its own role), so no head-role guard is needed.
  */
-function deriveAgentName(commandPath) {
-    const basename = commandPath.split(/[/\\]/).pop() ?? commandPath;
-    // Strip a trailing extension (.sh, .js, .mjs, .cjs)
-    const noExt = basename.replace(/\.(sh|js|mjs|cjs|ts)$/i, "");
-    // Strip the `uwf-` prefix introduced by agentLabel().
-    const noPrefix = noExt.startsWith("uwf-") ? noExt.slice(4) : noExt;
-    // Strip the trailing `-agent` suffix used by tests / generic agent shells.
-    const noSuffix = noPrefix.endsWith("-agent") ? noPrefix.slice(0, -"-agent".length) : noPrefix;
-    return noSuffix === "" ? noExt : noSuffix;
-}
-function loadDetailNode(store, detailRef) {
-    const detailNode = store.get(detailRef);
+function readStepDetailTurns(uwf, stepHash) {
+    const node = uwf.store.cas.get(stepHash);
+    if (node === null || node.type !== uwf.schemas.stepNode) {
+        return [];
+    }
+    const payload = node.payload;
+    if (payload.detail === null) {
+        return [];
+    }
+    const detailNode = uwf.store.cas.get(payload.detail);
     if (detailNode === null) {
-        fail(`detail node not found: ${detailRef}`);
+        return [];
+    }
+    const detail = detailNode.payload;
+    return Array.isArray(detail.turns) ? detail.turns : [];
+}
+/**
+ * Walk the step-start chain from a turn's owner backward via `prev` pointers.
+ * Returns step-starts in chronological order (oldest first).
+ */
+function walkStepStartChain(uwf, turnHead) {
+    // First, find a step-start hash from any turn's owner
+    const turnChain = [];
+    let currentTurn = turnHead;
+    // Walk the turn chain to find all unique owners
+    const seenOwners = new Set();
+    const owners = [];
+    while (currentTurn !== null) {
+        turnChain.push(currentTurn);
+        const node = uwf.store.cas.get(currentTurn);
+        if (node === null)
+            break;
+        const payload = node.payload;
+        const owner = payload.owner ?? null;
+        if (owner !== null && !seenOwners.has(owner)) {
+            seenOwners.add(owner);
+            owners.push(owner);
+        }
+        currentTurn = payload.prev ?? null;
     }
-    const payload = detailNode.payload;
-    const sessionId = typeof payload.sessionId === "string" ? payload.sessionId : null;
-    return { sessionId, payload };
-}
-function spawnAskAgent(agent, argv, cwd) {
-    try {
-        const stdout = execFileSync(agent.command, [...agent.args, ...argv], {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "pipe"],
-            maxBuffer: 50 * 1024 * 1024,
-            cwd,
+    // Now walk the step-start chain to get them in order
+    // Find the newest step-start and walk backward via prev
+    if (owners.length === 0) {
+        return [];
+    }
+    // Use the owners we found and order by stepIndex
+    const stepStartsWithIndex = [];
+    for (const owner of owners) {
+        const node = uwf.store.cas.get(owner);
+        if (node === null || node.type !== uwf.schemas.stepStart)
+            continue;
+        const payload = node.payload;
+        stepStartsWithIndex.push({ hash: owner, index: payload.stepIndex });
+    }
+    // Sort by stepIndex to get chronological order
+    stepStartsWithIndex.sort((a, b) => a.index - b.index);
+    return stepStartsWithIndex.map((s) => s.hash);
+}
+/**
+ * Build the whole-thread turn panorama (#421 Phase 3): walk the step-start chain
+ * (via turn owner → step-start → prev) and produce one group per step in
+ * chronological order. Each turn is attributed to its owning step-start via the
+ * `owner` field.
+ *
+ * Phase 3 changes (root-causing #412):
+ *   - Walks step-start chain instead of role-keyed active vars
+ *   - Each segment's turns sourced via `turnsOfStep(turnHead, stepStartHash)`
+ *   - In-flight detection: active-step matches step-start AND no step-complete
+ *   - edgePrompt readable directly from step-start
+ *
+ * In-flight step detection:
+ *   1. Check if `@uwf/active-step/<threadId>` points to this step-start hash
+ *   2. If match, this step is in-flight (no step-complete written yet)
+ *
+ * Fails with the standard `thread not found` message for an unknown thread.
+ */
+function buildTurnsPanorama(uwf, threadId) {
+    const entry = getThread(uwf.varStore, threadId);
+    if (entry === null) {
+        fail(`thread not found: ${threadId}`);
+    }
+    // Get the turn chain head and active-step (if any)
+    const turnHead = getActiveTurnHead(uwf.store, threadId);
+    const activeStepHash = getActiveStep(uwf.store, threadId);
+    // If no turns yet, try the legacy path via StepNode chain
+    if (turnHead === null) {
+        return buildTurnsPanoramaLegacy(uwf, threadId, entry.head);
+    }
+    // Walk the step-start chain from turn owners
+    const stepStarts = walkStepStartChain(uwf, turnHead);
+    const groups = [];
+    for (const stepStartHash of stepStarts) {
+        const node = uwf.store.cas.get(stepStartHash);
+        if (node === null || node.type !== uwf.schemas.stepStart)
+            continue;
+        const payload = node.payload;
+        const role = payload.role;
+        // Detect in-flight: active-step points to this step-start
+        const isInFlight = activeStepHash === stepStartHash;
+        // Get turns for this step using owner-based filtering
+        const turnHashes = turnsOfStep(uwf, turnHead, stepStartHash);
+        const turns = loadTurnData(uwf.store.cas, turnHashes);
+        groups.push({
+            role,
+            running: isInFlight,
+            turns,
+            stepStartHash,
         });
-        return { stdout };
     }
-    catch (e) {
-        const err = e;
-        if (err.code === "ENOENT") {
-            fail(`"${agent.command}" not found in PATH. Install it or check your PATH config. Run: which ${agent.command}`);
+    return groups;
+}
+/**
+ * Legacy fallback for threads without new turn chain structure.
+ * Uses the old role-keyed active vars and StepNode detail.turns.
+ */
+function buildTurnsPanoramaLegacy(uwf, threadId, headHash) {
+    const chain = walkChain(uwf, headHash);
+    const ordered = collectOrderedSteps(uwf, headHash, chain);
+    const activeRoles = readActiveTurnRoles(uwf.store, threadId);
+    const activeByRole = new Map(activeRoles.map((a) => [a.role, a.turns]));
+    const consumed = new Set();
+    const groups = [];
+    for (const item of ordered) {
+        const role = item.payload.role;
+        const active = activeByRole.get(role);
+        if (active !== undefined && active.length > 0 && !consumed.has(role)) {
+            groups.push({
+                role,
+                running: true,
+                turns: loadTurnData(uwf.store.cas, active),
+                stepStartHash: null,
+            });
+            consumed.add(role);
+        }
+        else {
+            groups.push({
+                role,
+                running: false,
+                turns: loadTurnData(uwf.store.cas, readStepDetailTurns(uwf, item.hash)),
+                stepStartHash: null,
+            });
+        }
+    }
+    for (const { role, turns } of activeRoles) {
+        if (consumed.has(role)) {
+            continue;
         }
-        const stderr = err.stderr == null
-            ? ""
-            : typeof err.stderr === "string"
-                ? err.stderr
-                : err.stderr.toString("utf8");
-        const detail = stderr.trim() !== "" ? `: ${stderr.trim()}` : "";
-        fail(`agent command failed (${agent.command})${detail}`);
+        groups.push({
+            role,
+            running: true,
+            turns: loadTurnData(uwf.store.cas, turns),
+            stepStartHash: null,
+        });
+        consumed.add(role);
     }
+    return groups;
 }
-function resolveAskWorkflow(uwf, payload) {
-    const startNode = uwf.store.cas.get(payload.start);
-    if (startNode === null) {
-        return null;
+/**
+ * Filter the panorama to a single role (exact-match), or pass it through
+ * unchanged when `role === null` (show every role's steps). `--role` is a filter
+ * over the whole-chain panorama, so it keeps **all** steps of that role across
+ * the thread (e.g. a role that ran in two rounds), not just the latest.
+ */
+function filterPanoramaByRole(groups, role) {
+    if (role === null) {
+        return groups;
     }
-    const start = startNode.payload;
-    const workflowNode = uwf.store.cas.get(start.workflow);
-    if (workflowNode === null) {
-        return null;
+    return groups.filter((g) => g.role === role);
+}
+/** Render a single turn's `## Turn N` block (1-based) via the reused pipeline. */
+function formatTurnBlock(turn, displayIndex) {
+    return `## Turn ${displayIndex}\n\n${formatTurnBody(turn)}`;
+}
+/**
+ * Slice the panorama's flattened cross-step turn sequence to `[offset, offset+limit)`
+ * (`limit === null` → no upper bound, the OCAS `ListOptions` "no limit" convention),
+ * keeping each surviving turn's **global** index so numbering is consistent across
+ * the whole panorama. Returns per-group survivors paired with their group, so
+ * grouping/markers are preserved while pagination removes turns (not steps).
+ */
+function paginatePanorama(groups, offset, limit) {
+    const start = offset > 0 ? offset : 0;
+    const end = limit === null ? Number.POSITIVE_INFINITY : start + Math.max(0, limit);
+    let globalIndex = 0;
+    const result = [];
+    for (const group of groups) {
+        const survivors = [];
+        for (const turn of group.turns) {
+            const idx = globalIndex;
+            globalIndex += 1;
+            if (idx >= start && idx < end) {
+                survivors.push({ turn, globalIndex: idx });
+            }
+        }
+        result.push({ group, turns: survivors });
+    }
+    return result;
+}
+/** Step group header, e.g. `## developer ✓ (47 turns)` / `## reviewer 🔄 进行中 (12 turns so far)`. */
+function formatGroupHeader(group) {
+    const count = group.turns.length;
+    if (group.running) {
+        return `## ${group.role} 🔄 进行中 (${count} turns so far)`;
     }
-    return workflowNode.payload;
+    return `## ${group.role} ✓ (${count} turns)`;
 }
-async function performFork(agent, agentName, stepHash, sourceSessionId, storageRoot, cwd) {
-    const cached = await getAskSessionId(agentName, stepHash, storageRoot);
-    if (cached !== null) {
-        return cached;
+/**
+ * Assemble the whole-thread turn panorama markdown (#409): a thread header, then
+ * one group per step (role + `✓`/`🔄 进行中` marker + turn count), and under each
+ * the surviving turns rendered via the reused `formatTurnBlock` pipeline with
+ * their global (cross-step) turn numbers. A group whose turns are entirely sliced
+ * out by pagination still shows its header (zero turns beneath).
+ */
+function formatPanoramaMarkdown(threadId, groups, offset, limit) {
+    const parts = [`# Thread ${threadId}`];
+    const paged = paginatePanorama(groups, offset, limit);
+    for (const { group, turns } of paged) {
+        parts.push("");
+        parts.push(formatGroupHeader(group));
+        for (const { turn, globalIndex } of turns) {
+            parts.push("");
+            parts.push(formatTurnBlock(turn, globalIndex + 1));
+        }
     }
-    const { stdout } = spawnAskAgent(agent, ["--mode", "fork", "--session", sourceSessionId], cwd);
-    const newSessionId = stdout.trim().split("\n").pop()?.trim() ?? "";
-    if (newSessionId === "") {
-        fail(`agent fork did not return a session id (${agent.command})`);
+    return parts.join("\n");
+}
+/**
+ * Resolve the turn hashes to flush when the followed step finishes (active var
+ * gone AND thread no longer running). Phase 3: uses active-turn-head and owner
+ * filtering via turnsOfStep. Falls back to legacy role-keyed vars if no turn
+ * chain exists.
+ */
+function resolveFinalTurnHashesPhase3(uwf, threadId, activeStepStart) {
+    const turnHead = getActiveTurnHead(uwf.store, threadId);
+    if (turnHead !== null && activeStepStart !== null) {
+        return turnsOfStep(uwf, turnHead, activeStepStart);
     }
-    await setAskSessionId(agentName, stepHash, newSessionId, storageRoot);
-    return newSessionId;
+    // Fallback: no new turn chain, return empty
+    return [];
 }
 /**
- * Ask a follow-up question to a historical step's agent (read-only).
+ * Legacy fallback for resolveFinalTurnHashes when thread uses role-keyed vars.
+ */
+function resolveFinalTurnHashesLegacy(uwf, threadId, followRole) {
+    const remaining = readActiveTurns(uwf.store, threadId, followRole);
+    if (remaining.length > 0) {
+        return remaining;
+    }
+    const entry = getThread(uwf.varStore, threadId);
+    if (entry === null) {
+        return [];
+    }
+    return readRoleDetailTurnsFromChain(uwf, entry.head, followRole);
+}
+/**
+ * Get turns for the in-flight step using Phase 3 owner-based filtering.
+ * Returns turn hashes owned by the active step-start.
+ */
+function getInFlightTurns(uwf, threadId) {
+    const turnHead = getActiveTurnHead(uwf.store, threadId);
+    const activeStepStart = getActiveStep(uwf.store, threadId);
+    if (turnHead === null || activeStepStart === null) {
+        return [];
+    }
+    return turnsOfStep(uwf, turnHead, activeStepStart);
+}
+/**
+ * Check if thread uses Phase 3 turn chain (has active-turn-head var).
+ */
+function hasPhase3TurnChain(uwf, threadId) {
+    return (getActiveTurnHead(uwf.store, threadId) !== null || getActiveStep(uwf.store, threadId) !== null);
+}
+/** Get active turns based on Phase 3 vs legacy mode. */
+function getActiveTurnsForLive(uwf, threadId, state, followRole) {
+    if (state.usePhase3) {
+        const activeStepStart = getActiveStep(uwf.store, threadId);
+        if (activeStepStart !== null) {
+            state.lastActiveStepStart = activeStepStart;
+        }
+        return getInFlightTurns(uwf, threadId);
+    }
+    return readActiveTurns(uwf.store, threadId, followRole);
+}
+/** Get final turns for reconciliation based on Phase 3 vs legacy mode. */
+function getFinalTurnsForLive(uwf, threadId, state, followRole) {
+    if (state.usePhase3) {
+        return resolveFinalTurnHashesPhase3(uwf, threadId, state.lastActiveStepStart);
+    }
+    return resolveFinalTurnHashesLegacy(uwf, threadId, followRole);
+}
+/**
+ * `--live` follower: poll the in-flight step's turns via the Phase 3 turn chain,
+ * printing each new turn block exactly once (tracking how many blocks were emitted
+ * and rendering only the new tail).
  *
- * Does NOT write a new StepNode and does NOT mutate thread state.  The agent's
- * raw stdout is returned so the CLI entry point can stream it directly.
+ * Phase 3 changes (#421):
+ *   - Uses `getActiveTurnHead` and `getActiveStep` instead of role-keyed vars
+ *   - Filters turns via `turnsOfStep(turnHead, activeStepStart)`
+ *   - Exits when the thread is no longer running
+ *
+ * Backward compatible: Falls back to legacy role-keyed vars for threads without
+ * Phase 3 turn chain.
  */
-export async function cmdStepAsk(storageRoot, stepHash, options) {
+async function followStepTurnsLive(storageRoot, threadId, opts) {
+    const emit = opts.onChunk ?? ((chunk) => process.stdout.write(chunk));
+    const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const isRunning = opts.isRunning ?? (async () => (await isThreadRunning(storageRoot, threadId)) !== null);
+    const intervalMs = opts.pollIntervalMs ?? STEP_TURNS_POLL_INTERVAL_MS;
+    const followRole = opts.role ?? (await resolveLiveFollowRole(storageRoot, threadId));
+    const state = {
+        printedCount: 0,
+        lastActiveStepStart: null,
+        usePhase3: null,
+    };
+    const flush = (uwf, hashes) => {
+        if (hashes.length <= state.printedCount) {
+            return;
+        }
+        const tail = loadTurnData(uwf.store.cas, hashes.slice(state.printedCount));
+        for (let i = 0; i < tail.length; i++) {
+            const turn = tail[i];
+            if (turn === undefined)
+                continue;
+            emit(`${formatTurnBlock(turn, state.printedCount + i + 1)}\n`);
+        }
+        state.printedCount = hashes.length;
+    };
+    while (true) {
+        const uwf = await createUwfStore(storageRoot);
+        if (state.usePhase3 === null) {
+            state.usePhase3 = hasPhase3TurnChain(uwf, threadId);
+        }
+        const active = getActiveTurnsForLive(uwf, threadId, state, followRole);
+        flush(uwf, active);
+        const running = await isRunning();
+        if (!running) {
+            flush(uwf, getFinalTurnsForLive(uwf, threadId, state, followRole));
+            return;
+        }
+        await sleep(intervalMs);
+    }
+}
+/**
+ * Resolve the role for `--live` to follow when `--role` is omitted: the thread's
+ * current in-flight role. Prefers a role with a live `@uwf/active-turns` var
+ * (the genuinely in-flight step); falls back to the head StepNode's role, then to
+ * `"agent"` for a StartNode head. Fails with the standard `thread not found`
+ * message for an unknown thread.
+ */
+async function resolveLiveFollowRole(storageRoot, threadId) {
     const uwf = await createUwfStore(storageRoot);
-    const node = uwf.store.cas.get(stepHash);
-    if (node === null) {
-        fail(`CAS node not found: ${stepHash}`);
+    const entry = getThread(uwf.varStore, threadId);
+    if (entry === null) {
+        fail(`thread not found: ${threadId}`);
     }
-    if (node.type !== uwf.schemas.stepNode) {
-        fail(`node ${stepHash} is not a StepNode`);
+    const activeRoles = readActiveTurnRoles(uwf.store, threadId);
+    const lastActive = activeRoles[activeRoles.length - 1];
+    if (lastActive !== undefined) {
+        return lastActive.role;
     }
-    const payload = node.payload;
-    if (payload.detail === null) {
-        fail(`step ${stepHash} has no detail; cannot ask`);
-    }
-    const detailRef = payload.detail;
-    const { sessionId: sourceSessionId } = loadDetailNode(uwf.store.cas, detailRef);
-    const workflow = resolveAskWorkflow(uwf, payload);
-    const config = await loadWorkflowConfig(storageRoot);
-    const agent = resolveAskAgentConfig(config, workflow, payload.role, options.agentOverride, payload.agent);
-    const agentName = deriveAgentName(agent.command);
-    const cwd = payload.cwd !== "" ? payload.cwd : process.cwd();
-    // Fork path: fork (or reuse cached fork) → ask with that session.
-    if (options.fork && sourceSessionId !== null) {
-        const askSessionId = await performFork(agent, agentName, stepHash, sourceSessionId, storageRoot, cwd);
-        const argv = ["--mode", "ask", "--session", askSessionId, "--prompt", options.prompt];
-        argv.push("--detail", detailRef);
-        const { stdout } = spawnAskAgent(agent, argv, cwd);
-        return stdout;
-    }
-    // Fallback path: ask without forking; inject detail ref for context.
-    const argv = ["--mode", "ask", "--prompt", options.prompt];
-    argv.push("--detail", detailRef);
-    const { stdout } = spawnAskAgent(agent, argv, cwd);
-    return stdout;
+    const node = uwf.store.cas.get(entry.head);
+    if (node !== null && node.type === uwf.schemas.stepNode) {
+        return node.payload.role;
+    }
+    return "agent";
+}
+/**
+ * `uwf step turns <thread-id> [--role <r>] [--live] [--limit <n>] [--offset <m>]`
+ * — render the whole-thread turn panorama (#409): walk the entire chain and show
+ * every step's turns (each completed step from its immutable `detail.turns`, the
+ * in-flight step from its active var, marked `🔄 进行中`), through the same
+ * per-turn pipeline as `step read`. `--role` filters the panorama to one role;
+ * `--limit`/`--offset` paginate the flattened cross-step turn sequence (after the
+ * role filter). With `--live`, follow the in-flight step's active var, printing
+ * new turns incrementally.
+ *
+ * Returns the assembled markdown (non-live); for `--live` the output is streamed
+ * to `onChunk`/stdout and the resolved string is returned empty.
+ */
+export async function cmdStepTurns(storageRoot, threadId, options) {
+    const opts = resolveStepTurnsOptions(storageRoot, threadId, options);
+    if (opts.live) {
+        await followStepTurnsLive(storageRoot, threadId, opts);
+        return "";
+    }
+    const uwf = await createUwfStore(storageRoot);
+    const panorama = buildTurnsPanorama(uwf, threadId);
+    const filtered = filterPanoramaByRole(panorama, opts.role);
+    return formatPanoramaMarkdown(threadId, filtered, opts.offset, opts.limit);
+}
+/**
+ * `uwf step ask` is unavailable in 0.x while broker integration (#381) is in
+ * progress. The legacy spawn-agent code path was removed alongside the
+ * `agents.<alias>: {command, args}` config shape. Use `uwf thread exec` /
+ * `uwf thread resume` instead — those routes go through `broker.send()` and
+ * preserve the Sumeru session.
+ */
+export async function cmdStepAsk(_storageRoot, _stepHash, _options) {
+    fail("step ask is unavailable in 0.x while broker integration (#381) is in progress. " +
+        "The pre-broker spawn-agent path was removed in #380; equivalent ask/fork primitives " +
+        "will return in Phase 4 once the Sumeru broker exposes session-fork APIs. " +
+        "Use `uwf thread resume <id> -p '...'` to continue a suspended thread, or " +
+        "`uwf thread exec <id>` to advance an idle thread.");
 }
 //# sourceMappingURL=step.js.map