@pellux/goodvibes-tui 1.13.1 → 1.15.0

package/src/input/commands/workstream-attempts.ts

@@ -0,0 +1,244 @@
+// ---------------------------------------------------------------------------
+// workstream-attempts.ts — the /workstream attempts surface for best-of-N.
+//
+// The engine runs a best-of-N work item as N sibling attempts in isolated
+// worktrees and HOLDS the merge, exposing the candidates for a winner pick
+// (orchestration engine.listHeldMergeGroups / proposeAttemptWinner /
+// pickAttemptWinner — the same seam the fleet.attempts.* gateway verbs use).
+// This module drives that seam from the /workstream command:
+//   • list             — the held-merge groups awaiting a pick, with candidates.
+//   • diff <c>         — one candidate's worktree diff in the existing DiffPanel.
+//   • judge            — the OPTIONAL model proposal, clearly labelled a model
+//                        judgment (scoredBy 'model'), with its reasons; never a pick.
+//   • pick <c>         — behind a DiffPanel confirm; merges the winner and lets
+//                        the engine clean the losers, then renders the receipt.
+// ---------------------------------------------------------------------------
+
+import type {
+  AttemptCandidate,
+  AttemptJudgment,
+  AttemptPickResult,
+  HeldMergeGroup,
+} from '@pellux/goodvibes-sdk/platform/orchestration';
+import { AttemptError } from '@pellux/goodvibes-sdk/platform/orchestration';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import type { CommandContext } from '../command-registry.ts';
+import type { WorkstreamCommandService } from '../../runtime/workstream-services.ts';
+import { requirePanelManager } from './runtime-services.ts';
+import { type AttemptGraphItem, renderDependentHoldLines } from './workstream-attempt-dependents.ts';
+
+/** Resolve a workstream's items for dependent-hold display; null-safe against a stubbed engine. */
+type ResolveWorkstreamItems = (workstreamId: string) => readonly AttemptGraphItem[] | null;
+
+function shortId(id: string): string {
+  return id.length > 10 ? `${id.slice(0, 10)}…` : id;
+}
+
+/** Resolve a group by exact id or unambiguous id prefix. */
+function resolveGroup(groups: readonly HeldMergeGroup[], ref: string): HeldMergeGroup | { error: string } {
+  const exact = groups.find((g) => g.groupId === ref);
+  if (exact) return exact;
+  const prefix = groups.filter((g) => g.groupId.startsWith(ref));
+  if (prefix.length === 1) return prefix[0]!;
+  if (prefix.length > 1) return { error: `Group ref "${ref}" is ambiguous (${prefix.length} matches). Use the full id.` };
+  return { error: `No held-merge group found: ${ref}. Run /workstream attempts list.` };
+}
+
+/** Resolve a candidate within a group by 1-based attempt number or itemId (prefix). */
+function resolveCandidate(group: HeldMergeGroup, ref: string): AttemptCandidate | { error: string } {
+  if (/^\d+$/.test(ref)) {
+    const cand = group.candidates.find((c) => c.attemptIndex + 1 === Number(ref));
+    return cand ?? { error: `No attempt #${ref} in group ${shortId(group.groupId)} (1–${group.candidates.length}).` };
+  }
+  const byId = group.candidates.filter((c) => c.itemId === ref || c.itemId.startsWith(ref));
+  if (byId.length === 1) return byId[0]!;
+  if (byId.length > 1) return { error: `Candidate ref "${ref}" is ambiguous. Use the attempt number instead.` };
+  return { error: `No candidate "${ref}" in group ${shortId(group.groupId)}.` };
+}
+
+function candidateLine(c: AttemptCandidate): string {
+  const files = c.diff ? `${c.diff.files.length} file(s)` : 'no diff';
+  const state = c.state === 'held-merge' ? 'held (pick-ready)' : `failed${c.failureReason ? `: ${c.failureReason}` : ''}`;
+  return `    ${c.attemptIndex + 1}. [${state}] ${c.title} — ${files}, item ${shortId(c.itemId)}`;
+}
+
+function renderGroupList(groups: readonly HeldMergeGroup[], resolveItems?: ResolveWorkstreamItems): string {
+  if (groups.length === 0) {
+    return 'No best-of-N groups awaiting a pick. A worktree-isolated item with attempts>1 appears here once its siblings finish.';
+  }
+  const lines: string[] = ['Best-of-N groups (held for a winner pick):'];
+  for (const g of groups) {
+    lines.push(`  ${shortId(g.groupId)} — "${g.sourceTitle}" (workstream ${shortId(g.workstreamId)})  ${g.ready ? 'READY' : 'still running'}${g.autoAccept ? ', auto-accept' : ''}`);
+    for (const c of g.candidates) lines.push(candidateLine(c));
+    if (g.judgment?.proposedWinnerItemId) {
+      lines.push(`    judge proposal: item ${shortId(g.judgment.proposedWinnerItemId)} (model, advisory)`);
+    }
+    // Non-leaf best-of-N: name the dependents this group holds, so a group that
+    // gates downstream work reads as such (leaf groups add nothing here).
+    const items = resolveItems?.(g.workstreamId);
+    if (items) {
+      lines.push(...renderDependentHoldLines(items, g.candidates.map((c) => c.itemId)));
+    }
+  }
+  lines.push('Compare: /workstream attempts diff <group> <#>   Judge: /workstream attempts judge <group>   Pick: /workstream attempts pick <group> <#>');
+  return lines.join('\n');
+}
+
+/** The model proposal, CLEARLY labelled a model judgment (never ground truth), with reasons. */
+function renderJudgment(group: HeldMergeGroup, judgment: AttemptJudgment): string {
+  const lines: string[] = [`Judge proposal for group ${shortId(group.groupId)} — "${group.sourceTitle}"`];
+  lines.push('  MODEL PROPOSAL (scoredBy: model) — advisory only; a human still confirms the pick.');
+  if (judgment.proposedWinnerItemId) {
+    const cand = group.candidates.find((c) => c.itemId === judgment.proposedWinnerItemId);
+    lines.push(`  Proposed winner: ${cand ? `attempt ${cand.attemptIndex + 1} — ${cand.title}` : `item ${shortId(judgment.proposedWinnerItemId)}`}`);
+  } else {
+    lines.push('  Proposed winner: none — the judge declined to choose.');
+  }
+  if (judgment.model) lines.push(`  Model: ${judgment.model}`);
+  if (judgment.reasons.length > 0) {
+    lines.push('  Reasons:');
+    for (const r of judgment.reasons) lines.push(`    - ${r}`);
+  }
+  if (judgment.proposedWinnerItemId) {
+    const cand = group.candidates.find((c) => c.itemId === judgment.proposedWinnerItemId);
+    lines.push(`  Accept it with: /workstream attempts pick ${shortId(group.groupId)} ${cand ? cand.attemptIndex + 1 : judgment.proposedWinnerItemId}`);
+  }
+  return lines.join('\n');
+}
+
+function renderPickReceipt(result: AttemptPickResult): string {
+  const losers = result.loserItemIds.length;
+  return [
+    `[Workstream] Winner picked for group ${shortId(result.groupId)}${result.auto ? ' (auto-accepted by judge)' : ''}.`,
+    `  Winner item ${shortId(result.winnerItemId)} merged through the integration lane.`,
+    `  ${losers} loser worktree(s) cleaned by the engine.`,
+  ].join('\n');
+}
+
+/**
+ * Handle `/workstream attempts …`. Returns true when it consumed the subcommand
+ * (so the main handler can stop), false when `attempts` was not the subcommand.
+ */
+export async function handleAttemptsSubcommand(ctx: CommandContext, service: WorkstreamCommandService, args: readonly string[]): Promise<boolean> {
+  if (args[0] !== 'attempts') return false;
+  const action = args[1] ?? 'list';
+
+  let groups: HeldMergeGroup[];
+  try {
+    groups = await service.engine.listHeldMergeGroups();
+  } catch (err) {
+    ctx.print(`Could not read best-of-N groups: ${summarizeError(err)}`);
+    return true;
+  }
+
+  if (action === 'list') {
+    const resolveItems: ResolveWorkstreamItems = (workstreamId) => {
+      try {
+        return (service.engine.getWorkstream(workstreamId)?.items as readonly AttemptGraphItem[] | undefined) ?? null;
+      } catch {
+        return null;
+      }
+    };
+    ctx.print(renderGroupList(groups, resolveItems));
+    return true;
+  }
+
+  const groupRef = args[2];
+  if (!groupRef) {
+    ctx.print(`Usage: /workstream attempts ${action} <group> ${action === 'list' ? '' : '<#>'}`.trim());
+    return true;
+  }
+  const group = resolveGroup(groups, groupRef);
+  if ('error' in group) {
+    ctx.print(group.error);
+    return true;
+  }
+
+  if (action === 'judge') {
+    try {
+      const judgment = await service.engine.proposeAttemptWinner(group.groupId);
+      ctx.print(renderJudgment(group, judgment));
+    } catch (err) {
+      ctx.print(err instanceof AttemptError
+        ? `No judge available: ${err.message}. Configure a judge model to get a proposal; you can still pick manually.`
+        : `Judge failed: ${summarizeError(err)}`);
+    }
+    return true;
+  }
+
+  if (action === 'diff') {
+    const candRef = args[3];
+    if (!candRef) {
+      ctx.print(`Candidates in group ${shortId(group.groupId)}:\n${group.candidates.map(candidateLine).join('\n')}\nView one: /workstream attempts diff ${shortId(group.groupId)} <#>`);
+      return true;
+    }
+    const cand = resolveCandidate(group, candRef);
+    if ('error' in cand) { ctx.print(cand.error); return true; }
+    if (!cand.diff || !cand.diff.unifiedDiff.trim()) {
+      ctx.print(`Attempt ${cand.attemptIndex + 1} has no viewable diff (${cand.state === 'failed' ? 'it failed' : 'its worktree was already cleaned'}).`);
+      return true;
+    }
+    const { DiffPanel } = await import('../../panels/diff-panel.ts');
+    const pm = requirePanelManager(ctx);
+    let panel = pm.getAllOpen().find((p) => p.id === 'diff');
+    if (!panel) { try { panel = pm.open('diff'); } catch { ctx.print('Could not open the diff panel.'); return true; } }
+    pm.activateById('diff');
+    if (!pm.isVisible()) pm.show();
+    ctx.focusPanels?.();
+    (panel as InstanceType<typeof DiffPanel>).loadRawDiff(cand.diff.unifiedDiff);
+    ctx.print(`Showing attempt ${cand.attemptIndex + 1} ("${cand.title}") diff in the diff panel.`);
+    ctx.renderRequest();
+    return true;
+  }
+
+  if (action === 'pick') {
+    const candRef = args[3];
+    if (!candRef) { ctx.print(`Usage: /workstream attempts pick ${shortId(group.groupId)} <#>`); return true; }
+    if (!group.ready) { ctx.print(`Group ${shortId(group.groupId)} is not ready — its siblings are still running. Wait until every attempt is terminal.`); return true; }
+    const cand = resolveCandidate(group, candRef);
+    if ('error' in cand) { ctx.print(cand.error); return true; }
+    if (cand.state !== 'held-merge') { ctx.print(`Attempt ${cand.attemptIndex + 1} failed — only a held (pick-ready) candidate can win.`); return true; }
+
+    const { DiffPanel } = await import('../../panels/diff-panel.ts');
+    const pm = requirePanelManager(ctx);
+    let panel = pm.getAllOpen().find((p) => p.id === 'diff');
+    if (!panel) { try { panel = pm.open('diff'); } catch { ctx.print('Could not open the diff panel to confirm.'); return true; } }
+    pm.activateById('diff');
+    if (!pm.isVisible()) pm.show();
+    ctx.focusPanels?.();
+    const diffPanel = panel as InstanceType<typeof DiffPanel>;
+    if (cand.diff?.unifiedDiff.trim()) diffPanel.loadRawDiff(cand.diff.unifiedDiff);
+    else diffPanel.showDiff(cand.title, '@@ pick @@\n (no diff to preview for this candidate)');
+
+    diffPanel.confirmOverlay.arm({
+      id: `${group.groupId}:${cand.itemId}`,
+      label: `Pick attempt ${cand.attemptIndex + 1} ("${cand.title}") — merge it, clean the ${group.candidates.length - 1} other worktree(s)`,
+      verb: 'Pick',
+      onConfirm: async () => {
+        try {
+          const result = await service.engine.pickAttemptWinner(group.groupId, cand.itemId);
+          pm.close('diff');
+          ctx.focusPrompt?.();
+          ctx.print(renderPickReceipt(result));
+        } catch (err) {
+          pm.close('diff');
+          ctx.focusPrompt?.();
+          ctx.print(err instanceof AttemptError ? `Pick refused: ${err.message}` : `Pick failed: ${summarizeError(err)}`);
+        }
+        ctx.renderRequest();
+      },
+      onCancel: () => {
+        pm.close('diff');
+        ctx.focusPrompt?.();
+        ctx.print('Pick cancelled — nothing merged, no worktree cleaned.');
+        ctx.renderRequest();
+      },
+    });
+    ctx.print(`Confirm the pick in the diff panel: Enter/y to merge attempt ${cand.attemptIndex + 1} and clean the losers, n/Esc to cancel.`);
+    ctx.renderRequest();
+    return true;
+  }
+
+  ctx.print(`Unknown attempts action "${action}". Use: list | diff <group> <#> | judge <group> | pick <group> <#>.`);
+  return true;
+}

package/src/input/commands/workstream-runtime.ts

@@ -11,7 +11,12 @@
 // planning-runtime.ts), NOT a panel — a multi-phase proposal is too rich for
 // a one-line confirm overlay, and Pillar-3 doctrine keeps work visible in the
 // transcript. create -> approve -> launch is a real three-step flow (edit and
-// cancel apply to the pending proposal too): the engine's own createWorkstream
+// cancel apply to the pending proposal too). The transcript IS the plan-review
+// gate: between create and approve the proposal is reshapable in place —
+// edit-item rewrites one item's brief, remove-item drops an item (and unlinks
+// it from siblings' dependencies), move-item reorders authoring order, and
+// each re-renders the whole proposal and clears any prior approval, so nothing
+// launches until the reshaped plan is explicitly re-approved. The engine's own createWorkstream
 // immediately materializes a real, ticking-eligible Workstream with no
 // pre-creation "draft" concept, so approval happens on a TUI-held draft
 // (workstream-services.ts's WorkstreamDraft) before anything is created in
@@ -22,7 +27,10 @@
 import { AdaptivePlanner } from '@pellux/goodvibes-sdk/platform/core';
 import type { CreateWorkstreamInput, PhaseKind, PhaseRole, WorkItem, WorkItemState, Workstream, WorkstreamIsolation } from '@pellux/goodvibes-sdk/platform/orchestration';
 import type { WorkstreamCommandService, WorkstreamDraft, WorkstreamDraftProvenance } from '../../runtime/workstream-services.ts';
+import { validateAttempts } from '../../runtime/workstream-attempts-validation.ts';
+import { handleAttemptsSubcommand } from './workstream-attempts.ts';
 import type { CommandContext, CommandRegistry } from '../command-registry.ts';
+import { describeOperatorRpcError, getOperatorRpc } from './operator-rpc.ts';
 
 // ---------------------------------------------------------------------------
 // Formatting helpers
@@ -53,6 +61,47 @@ function templateForPhaseKind(kind: PhaseKind): string {
   return kind === 'review' || kind === 'gate' ? 'general' : 'engineer';
 }
 
+/**
+ * Pre-fan-out quota consultation for /workstream launch. Assesses whether the
+ * draft's work-item count (the fan-out this launch is about to create, worst
+ * case — items can run concurrently within a phase) is likely to exhaust the
+ * active provider's quota window, grounded in observed rate-limit signals
+ * (quota.fanout.get). Returns a printable warning + evidence when the daemon
+ * reports 'likely-exhausts'; returns null for 'unlikely'/'unknown' (no
+ * evidence of risk is not itself evidence of safety, so those verdicts never
+ * block) and whenever the check itself can't run (daemon unavailable/
+ * unreachable, or no active provider) — an infra gap in the quota check is
+ * not grounds to block launching work the operator already approved.
+ */
+async function checkFanoutQuotaWarning(ctx: CommandContext, draft: WorkstreamDraft): Promise<string | null> {
+  const provider = ctx.session.runtime.provider;
+  if (!provider) return null;
+  const rpc = getOperatorRpc(ctx);
+  if (!rpc.available) return null;
+  const agentCount = Math.max(1, draft.proposal.workItems.length);
+  const assessment = await rpc.sdk.operator.invoke('quota.fanout.get', { provider, agentCount }).catch((error: unknown) => {
+    ctx.print(`[workstream launch] quota check could not run: ${describeOperatorRpcError(error)}`);
+    return null;
+  });
+  if (!assessment || assessment.verdict !== 'likely-exhausts') return null;
+  const ev = assessment.evidence;
+  const evidenceParts = [
+    `requested=${ev.requestedAgents}`,
+    `recentRateLimitCount=${ev.recentRateLimitCount}`,
+    ev.activeCooldownMs !== undefined ? `activeCooldownMs=${ev.activeCooldownMs}` : null,
+    ev.observedRemaining !== undefined ? `observedRemaining=${ev.observedRemaining}` : null,
+    ev.observedLimit !== undefined ? `observedLimit=${ev.observedLimit}` : null,
+  ].filter((part): part is string => part !== null);
+  return [
+    `[workstream launch] WARNING — ${provider} likely exhausts its quota window for ${agentCount} agent(s) fanning out.`,
+    `  reason: ${assessment.reason}`,
+    `  evidence: ${evidenceParts.join(' ')}`,
+    '',
+    `Launch anyway: /workstream launch ${draft.id} --force`,
+    'Cancel: do nothing — the approved proposal stays ready to launch later.',
+  ].join('\n');
+}
+
 /**
  * phase.role for a 'custom' phase is the free-text description passed to
  * `/workstream insert-phase` — it is purely COSMETIC. Neither
@@ -142,11 +191,21 @@ function formatItemDependencyNote(item: WorkItem, ws: Workstream): string {
  */
 function formatDraftItems(spec: CreateWorkstreamInput): string[] {
   const titleById = new Map(spec.items.map((it) => [it.id ?? it.title, it.title] as const));
-  return spec.items.map((it, i) => {
+  const lines: string[] = [];
+  spec.items.forEach((it, i) => {
     const deps = it.dependsOn ?? [];
     const after = deps.length > 0 ? ` (after: ${deps.map((d) => titleById.get(d) ?? d).join(', ')})` : '';
-    return `  ${i + 1}. ${it.title}${after}`;
+    const attempts = (it.attempts ?? 1) > 1 ? `  [best-of-${it.attempts}${it.autoAcceptWinner ? ', auto-accept winner' : ''}]` : '';
+    lines.push(`  ${i + 1}. ${it.title}${after}${attempts}`);
+    // Show the brief (the instructions the item's agent runs) only when it says
+    // something the title doesn't — an edited brief (via /workstream edit-item)
+    // must be visible on the review surface, but a decomposition whose title and
+    // brief coincide would just repeat itself.
+    if (it.task.trim() && it.task.trim() !== it.title.trim()) {
+      lines.push(`       brief: ${it.task.trim()}`);
+    }
   });
+  return lines;
 }
 
 function summarizeItemStates(ws: Workstream): string {
@@ -204,18 +263,31 @@ function renderDraftProposal(draft: WorkstreamDraft): string {
   });
   lines.push('Work items (ordinal order):');
   lines.push(...formatDraftItems(draft.spec));
+  // Best-of-N plan validation (workstream-attempts-validation.ts): surface the
+  // worktree/stable-id constraint breaks here so a violating plan is visible
+  // before approve, and blocked at launch. Non-leaf best-of-N (items with
+  // dependents) is allowed. Notes (e.g. the engine's attempts cap) are advisory.
+  const attemptsCheck = validateAttempts(draft.spec);
+  if (attemptsCheck.violations.length > 0) {
+    lines.push('Best-of-N: plan is INVALID and cannot launch until fixed:');
+    for (const v of attemptsCheck.violations) lines.push(`  ✗ ${v}`);
+  } else if (attemptsCheck.hasAttempts) {
+    lines.push('Best-of-N: worktree + stable-id constraints satisfied — winners are chosen via /workstream attempts pick, and any dependents wait for the winner to be picked and merged.');
+  }
+  for (const n of attemptsCheck.notes) lines.push(`  note: ${n}`);
   lines.push(
     draft.approved
       ? `Approved. Launch with: /workstream launch ${draft.id}`
       : `Approve with: /workstream approve ${draft.id}`,
   );
-  lines.push(`Edit the task: /workstream edit ${draft.id} <new task...>   Discard: /workstream cancel ${draft.id}`);
-  // Honest limitation (see workstream-services.ts's REALITY-WINS doc): the
-  // engine has no pre-creation draft concept, so this proposal is
-  // process-lifetime, in-memory state only — never journaled like a launched
-  // Workstream is. State that plainly, the same way an unsent chat draft
-  // would be, rather than letting a restart silently make it vanish.
-  lines.push('Note: not saved — lost if the TUI restarts before launch.');
+  lines.push(`Reshape: /workstream edit-item ${draft.id} <#> <brief...> | remove-item ${draft.id} <#> | move-item ${draft.id} <#> <pos>`);
+  lines.push(`Re-decompose from a new goal: /workstream edit ${draft.id} <new task...>   Discard: /workstream cancel ${draft.id}`);
+  // Honest durability note (see workstream-services.ts's REALITY-WINS doc):
+  // the engine has no pre-launch draft concept, but the TUI journals this
+  // proposal to disk (.goodvibes/orchestration/drafts/) and reloads it at
+  // startup, so it survives a restart and is here to launch afterward — its
+  // approval state included.
+  lines.push('Note: saved to .goodvibes/orchestration/drafts/ — survives a restart until you launch or cancel it.');
   return lines.join('\n');
 }
 
@@ -285,18 +357,16 @@ function resolveWorkstream(service: WorkstreamCommandService, ref: string): Work
 }
 
 /**
- * approve/edit/launch all fail this way when `id` doesn't resolve to a held
- * draft. A bare "No pending proposal found" reads like a typo'd id even when
- * the real cause is that drafts are process-lifetime, in-memory-only state
- * (see renderDraftProposal's note and workstream-services.ts's REALITY-WINS
- * doc) and a TUI restart wiped every one of them. Only hint at that when the
- * service is holding zero drafts at all — with other drafts present, a typo
- * or stale id is the more honest guess and the plain message stays.
+ * approve/edit/launch/*-item all fail this way when `id` doesn't resolve to a
+ * held draft. Drafts are now journaled to disk and reloaded at startup (see
+ * renderDraftProposal's note and workstream-services.ts's REALITY-WINS doc), so
+ * a restart no longer silently wipes them — a missing id is a typo or a
+ * stale/already-launched proposal, and the plain message is the honest guess.
+ * `service` is kept in the signature so callers stay uniform and a future
+ * "did you mean <closest id>?" hint has somewhere to live.
  */
-function draftNotFoundMessage(service: WorkstreamCommandService, id: string): string {
-  const base = `No pending proposal found: ${id}`;
-  if (service.listDrafts().length > 0) return base;
-  return `${base} (proposals aren't saved — a TUI restart since you created it would explain this; recreate it with /workstream create)`;
+function draftNotFoundMessage(_service: WorkstreamCommandService, id: string): string {
+  return `No pending proposal found: ${id}`;
 }
 
 // ---------------------------------------------------------------------------
@@ -307,8 +377,8 @@ export function registerWorkstreamRuntimeCommands(registry: CommandRegistry): vo
   registry.register({
     name: 'workstream',
     description: 'Author and oversee multi-phase agent workstreams (orchestration engine)',
-    usage: 'create [--isolation shared|worktree] <task...> | list | status [id] | insert-phase <id> <description...> | approve <id> | edit <id> [--isolation shared|worktree] <task...> | launch <id> | cancel <id>',
-    argsHint: 'create [--isolation worktree] <task> | list | status [id] | approve | edit | launch | cancel',
+    usage: 'create [--isolation shared|worktree] <task...> | list | status [id] | insert-phase <id> <description...> | edit-item <id> <item#> <brief...> | remove-item <id> <item#> | move-item <id> <item#> <pos> | approve <id> | edit <id> [--isolation shared|worktree] <task...> | launch <id> [--force] | cancel <id> | attempts list|diff|judge|pick',
+    argsHint: 'create [--isolation worktree] <task> | list | status [id] | edit-item | remove-item | move-item | approve | edit | launch | cancel | attempts',
     handler: async (args, ctx: CommandContext) => {
       const service = ctx.session.workstreamEngine;
       if (!service) {
@@ -318,6 +388,22 @@ export function registerWorkstreamRuntimeCommands(registry: CommandRegistry): vo
 
       const sub = args[0];
 
+      // Best-of-N surface: /workstream attempts list|diff|judge|pick (workstream-attempts.ts).
+      if (await handleAttemptsSubcommand(ctx, service, args)) return;
+
+      /** Thread editItem/removeItem/moveItem's tri-state result to the transcript: a missing draft gets the restart-aware not-found message, a bad reference/argument gets its honest reason, and a success re-renders the whole reshaped proposal so the review surface always shows the current plan. */
+      const printItemEdit = (id: string, res: WorkstreamDraft | { error: string } | undefined): void => {
+        if (res === undefined) {
+          ctx.print(draftNotFoundMessage(service, id));
+          return;
+        }
+        if ('error' in res) {
+          ctx.print(res.error);
+          return;
+        }
+        ctx.print(renderDraftProposal(res));
+      };
+
       if (!sub || sub === 'list') {
         ctx.print(renderWorkstreamList(service));
         return;
@@ -419,10 +505,47 @@ export function registerWorkstreamRuntimeCommands(registry: CommandRegistry): vo
         return;
       }
 
-      if (sub === 'launch') {
+      if (sub === 'edit-item') {
         const id = args[1];
+        const itemRef = args[2];
+        const brief = args.slice(3).join(' ').trim();
+        if (!id || !itemRef || !brief) {
+          ctx.print('Usage: /workstream edit-item <id> <item#> <new brief...>');
+          return;
+        }
+        printItemEdit(id, service.editItem(id, itemRef, brief));
+        return;
+      }
+
+      if (sub === 'remove-item') {
+        const id = args[1];
+        const itemRef = args[2];
+        if (!id || !itemRef) {
+          ctx.print('Usage: /workstream remove-item <id> <item#>');
+          return;
+        }
+        printItemEdit(id, service.removeItem(id, itemRef));
+        return;
+      }
+
+      if (sub === 'move-item') {
+        const id = args[1];
+        const itemRef = args[2];
+        const posRaw = args[3];
+        const position = Number(posRaw);
+        if (!id || !itemRef || posRaw === undefined || !Number.isInteger(position)) {
+          ctx.print('Usage: /workstream move-item <id> <item#> <new-position#>');
+          return;
+        }
+        printItemEdit(id, service.moveItem(id, itemRef, position));
+        return;
+      }
+
+      if (sub === 'launch') {
+        const force = args.includes('--force');
+        const id = args.find((arg, index) => index > 0 && arg !== '--force');
         if (!id) {
-          ctx.print('Usage: /workstream launch <id>');
+          ctx.print('Usage: /workstream launch <id> [--force]');
           return;
         }
         const draft = service.getDraft(id);
@@ -434,6 +557,18 @@ export function registerWorkstreamRuntimeCommands(registry: CommandRegistry): vo
           ctx.print(`Proposal ${id} is not approved yet. Run /workstream approve ${id} first.`);
           return;
         }
+        const attemptsCheck = validateAttempts(draft.spec);
+        if (attemptsCheck.violations.length > 0) {
+          ctx.print(`Cannot launch ${id} — best-of-N plan constraints are violated:\n${attemptsCheck.violations.map((v) => `  - ${v}`).join('\n')}\nFix the plan (or drop the attempts) and re-approve.`);
+          return;
+        }
+        if (!force) {
+          const quotaWarning = await checkFanoutQuotaWarning(ctx, draft);
+          if (quotaWarning) {
+            ctx.print(quotaWarning);
+            return;
+          }
+        }
         const result = service.launchDraft(id);
         if (!result) {
           ctx.print(`Could not launch ${id}.`);
@@ -478,9 +613,12 @@ export function registerWorkstreamRuntimeCommands(registry: CommandRegistry): vo
         + '  /workstream list\n'
         + '  /workstream status [id]\n'
         + '  /workstream insert-phase <id> <description...>\n'
+        + '  /workstream edit-item <id> <item#> <new brief...>\n'
+        + '  /workstream remove-item <id> <item#>\n'
+        + '  /workstream move-item <id> <item#> <new-position#>\n'
         + '  /workstream approve <id>\n'
         + '  /workstream edit <id> [--isolation shared|worktree] <new task...>\n'
-        + '  /workstream launch <id>\n'
+        + '  /workstream launch <id> [--force]\n'
         + '  /workstream cancel <id>',
       );
     },

package/src/input/commands/worktree-runtime.ts

@@ -1,13 +1,39 @@
 import { getPersistedWorktreeMeta, reviewWorktreeAttachments, summarizeWorktreeOwnership } from '@/runtime/index.ts';
+import type { ManagedWorktreeMeta } from '@/runtime/index.ts';
 import type { CommandRegistry } from '../command-registry.ts';
 import { openCommandPanel, requireShellPaths } from './runtime-services.ts';
+import { describeOperatorRpcError, getOperatorRpc } from './operator-rpc.ts';
+
+/** Compact per-row setup-state tag for /worktree review — absent when setup has never run; failure stands out. */
+export function formatSetupTag(setup: ManagedWorktreeMeta['setup']): string {
+  if (!setup) return '';
+  if (setup.state === 'failed') return ' setup:FAILED';
+  if (setup.state === 'succeeded') return ' setup:ok';
+  return ' setup:skipped';
+}
+
+/** Full setup-state block for /worktree inspect — the failing step + captured output when failed. */
+export function formatSetupDetail(setup: ManagedWorktreeMeta['setup']): string[] {
+  if (!setup) return ['  setup: never run'];
+  if (setup.state !== 'failed') return [`  setup: ${setup.state}`];
+  const failingStep = setup.steps.find((step) => !step.ok);
+  return [
+    `  setup: FAILED — ${setup.error ?? 'unknown error'}`,
+    ...(failingStep
+      ? [
+          `    failing step (${failingStep.kind}): ${failingStep.label}${failingStep.exitCode !== undefined ? ` (exit ${failingStep.exitCode})` : ''}`,
+          ...(failingStep.output ? [`    output: ${failingStep.output.slice(0, 2000)}`] : []),
+        ]
+      : []),
+  ];
+}
 
 export function registerWorktreeRuntimeCommands(registry: CommandRegistry): void {
   registry.register({
     name: 'worktree',
     aliases: ['worktrees'],
     description: 'Review and manage orchestrator-owned git worktrees',
-    usage: '[review|panel|inspect <path>|attach <path> <session|task> <id>|session <id>|task <id>|recover <session|task> <id>|pause <path>|resume <path>|keep <path>|discard <path>|cleanup <path>]',
+    usage: '[review|panel|inspect <path>|setup <path>|attach <path> <session|task> <id>|session <id>|task <id>|recover <session|task> <id>|pause <path>|resume <path>|keep <path>|discard <path>|cleanup <path>]',
     async handler(args, ctx) {
       const sub = (args[0] ?? 'review').toLowerCase();
       const runtime = ctx.workspace.worktreeRegistry;
@@ -32,6 +58,7 @@ export function registerWorktreeRuntimeCommands(registry: CommandRegistry): void
           return;
         }
         const nextSteps = [
+          record.setup?.state === 'failed' ? `/worktree setup ${record.path}` : null,
           record.state === 'paused' ? `/worktree resume ${record.path}` : null,
           record.state === 'discard' || record.state === 'pending-cleanup' ? `/worktree cleanup ${record.path}` : null,
           record.state === 'kept' ? `/worktree keep ${record.path}` : null,
@@ -47,10 +74,37 @@ export function registerWorktreeRuntimeCommands(registry: CommandRegistry): void
           `  session: ${record.sessionId ?? 'n/a'}`,
           `  task: ${record.taskId ?? 'n/a'}`,
           `  updated: ${new Date(record.updatedAt).toLocaleString()}`,
+          ...formatSetupDetail(record.setup),
           ...(nextSteps.length > 0 ? ['  next:', ...nextSteps.map((step) => `    ${step}`)] : ['  next: /worktree review']),
         ].join('\n'));
         return;
       }
+      if (sub === 'setup') {
+        const path = args[1];
+        if (!path) {
+          ctx.print('Usage: /worktree setup <path>');
+          return;
+        }
+        const rpc = getOperatorRpc(ctx);
+        if (!rpc.available) {
+          ctx.print(`[worktree setup] ${rpc.reason}`);
+          return;
+        }
+        ctx.print(`[worktree setup] Re-running cold-start setup for ${path}...`);
+        try {
+          const { setup } = await rpc.sdk.operator.invoke('worktrees.setup.run', { path });
+          if (setup.state === 'skipped') {
+            ctx.print('[worktree setup] skipped — no setup commands or carry-over globs are configured.');
+          } else if (setup.state === 'succeeded') {
+            ctx.print(`[worktree setup] succeeded (${setup.steps.length} step(s)).`);
+          } else {
+            ctx.print(formatSetupDetail(setup).join('\n'));
+          }
+        } catch (error) {
+          ctx.print(`[worktree setup] round-trip request failed: ${describeOperatorRpcError(error)}`);
+        }
+        return;
+      }
       if (sub === 'attach') {
         const path = args[1];
         const targetKind = args[2];
@@ -128,7 +182,7 @@ export function registerWorktreeRuntimeCommands(registry: CommandRegistry): void
             `  session attached: ${summary.sessionAttached}  task attached: ${summary.taskAttached}`,
             `  agent owned: ${summary.agentOwned}  orchestrator owned: ${summary.orchestratorOwned}  manual: ${summary.manualOwned}`,
             ...rows.map((row) => (
-              `  ${row.kind.padEnd(12)} ${row.state.padEnd(15)} ${row.branch.padEnd(22)} session=${(row.sessionId ?? '-').padEnd(12)} task=${(row.taskId ?? '-').padEnd(12)} ${row.path}`
+              `  ${row.kind.padEnd(12)} ${row.state.padEnd(15)} ${row.branch.padEnd(22)} session=${(row.sessionId ?? '-').padEnd(12)} task=${(row.taskId ?? '-').padEnd(12)} ${row.path}${formatSetupTag(row.setup)}`
             )),
           ].join('\n')
         : 'Worktree Review\n  No worktrees discovered.');