@pellux/goodvibes-tui 1.13.1 → 1.14.0

package/src/runtime/trust/workspace-registration.ts

@@ -0,0 +1,184 @@
+/**
+ * workspace-registration.ts — first-open workspace REGISTRATION half.
+ *
+ * Companion to the per-workspace trust gate (workspace-trust.ts). Trust is
+ * TUI-local (a decision persisted under <cwd>/.goodvibes/tui); REGISTRATION is
+ * the platform-wide "which project roots has the operator opted GoodVibes into"
+ * registry, owned by the SDK.
+ *
+ * SINGLE SOURCE OF TRUTH. Resolution and mutation both go through the SDK's
+ * shared WorkspaceRegistrationStore — the exact class the daemon composes its
+ * `workspaces.*` gateway verbs over (control-plane/routes/register-gateway-verb-
+ * groups.ts constructs `new WorkspaceRegistrationStore({ path: resolveUserPath(
+ * 'control-plane', 'workspace-registrations.json'), homeDir: dirname(daemonState
+ * Dir), daemonStateDir })`). We point an in-process store at that identical path
+ * and roots, so whether the daemon's `workspaces.resolve` verb reads it over the
+ * wire or we read it in-process, both operate on ONE persisted document. This is
+ * not a divergent reimplementation: same SDK store class, same file, same
+ * root-guard. In-process (rather than an RPC to a composed daemon) because the
+ * first-open prompt renders synchronously at startup and must not depend on a
+ * daemon being up — the file is the shared source either way.
+ *
+ * Coverage semantics are the store's (implemented in the SDK, not here): coverage
+ * flows DOWN a registered root's subtree, a linked git worktree inherits its main
+ * repo's registration, and a remembered decline is subtree-scoped at the root it
+ * was asked. So the register half of the first-open prompt only appears when
+ * resolution says UNKNOWN; a covered or declined path never re-asks.
+ */
+import { dirname } from 'node:path';
+import { parse as parsePath } from 'node:path';
+import {
+  WorkspaceRegistrationStore,
+  WorkspaceRegistrationError,
+  normalizeWorkspaceRoot,
+  type WorkspaceCoverageStatus,
+  type RegisterWorkspaceResult,
+} from '@pellux/goodvibes-sdk/platform/workspace';
+
+/** The slice of ShellPathService this manager needs. */
+export interface WorkspaceRegistrationShellPaths {
+  readonly workingDirectory: string;
+  readonly homeDirectory: string;
+  resolveUserPath(...segments: string[]): string;
+}
+
+/** Filename of the shared control-plane registry document (matches the daemon composition). */
+const REGISTRATIONS_FILE = 'workspace-registrations.json';
+
+export interface WorkspaceRegistrationEvaluation {
+  /** Normalized absolute working directory the prompt would ask about. */
+  readonly root: string;
+  /** Coverage verdict from the shared store: covered / declined / unknown. */
+  readonly status: WorkspaceCoverageStatus;
+  /** The nearest registered root covering the path, or null. */
+  readonly coveredBy: string | null;
+  /** True when coverage was inherited through the git worktree→main-repo link. */
+  readonly viaWorktreeLink: boolean;
+  /** True when the root is one the store would refuse ($HOME, filesystem root, ~/.goodvibes). */
+  readonly broad: boolean;
+  /**
+   * Whether to OFFER the register half of the first-open prompt: only when the
+   * store says UNKNOWN and the root is registrable. Broad roots are never
+   * offered — the store refuses them, so we do not prompt for what would be
+   * refused. Covered / declined roots never re-ask.
+   */
+  readonly offerRegister: boolean;
+  /** Human-readable justification from the resolver. */
+  readonly reason: string;
+}
+
+export interface WorkspaceRegistrationManagerOptions {
+  readonly shellPaths: WorkspaceRegistrationShellPaths;
+  /**
+   * Inject a pre-built store (e.g. a `:memory:` store for tests). Defaults to an
+   * in-process store at the shared control-plane path, configured identically to
+   * the daemon's.
+   */
+  readonly store?: WorkspaceRegistrationStore;
+}
+
+export class WorkspaceRegistrationManager {
+  private readonly store: WorkspaceRegistrationStore;
+  private readonly workingDirectory: string;
+  private readonly homeDir: string;
+  private readonly daemonStateDir: string;
+
+  constructor(options: WorkspaceRegistrationManagerOptions) {
+    const { shellPaths } = options;
+    this.workingDirectory = shellPaths.workingDirectory;
+    // Mirror the daemon's composition exactly (register-gateway-verb-groups.ts):
+    // the daemon state dir IS resolveUserPath() (~/.goodvibes); its parent is the
+    // home directory — both refused as broad roots by the same guard.
+    this.daemonStateDir = shellPaths.resolveUserPath();
+    this.homeDir = dirname(this.daemonStateDir);
+    this.store =
+      options.store ??
+      new WorkspaceRegistrationStore({
+        path: shellPaths.resolveUserPath('control-plane', REGISTRATIONS_FILE),
+        homeDir: this.homeDir,
+        daemonStateDir: this.daemonStateDir,
+      });
+  }
+
+  /**
+   * isBroadRoot — mirrors the SDK store's broad-root refusal SET (filesystem
+   * root, home directory, daemon state dir) so the register half is never
+   * offered for a root the store would refuse. This is a UI-suppression predicate
+   * only; the store's `add` remains the enforcement authority (see register()),
+   * which is why register() also catches WorkspaceRegistrationError.
+   */
+  private isBroadRoot(normalizedRoot: string): boolean {
+    if (normalizedRoot === parsePath(normalizedRoot).root) return true;
+    if (normalizedRoot === normalizeWorkspaceRoot(this.homeDir)) return true;
+    if (normalizedRoot === normalizeWorkspaceRoot(this.daemonStateDir)) return true;
+    return false;
+  }
+
+  /**
+   * Resolve the current working directory against the shared registry and decide
+   * whether the register half of the first-open prompt should appear. Read-only —
+   * never writes, so it is safe to call from `status`/`doctor`.
+   */
+  async evaluate(): Promise<WorkspaceRegistrationEvaluation> {
+    const resolution = await this.store.resolve(this.workingDirectory);
+    const broad = this.isBroadRoot(resolution.path);
+    return {
+      root: resolution.path,
+      status: resolution.status,
+      coveredBy: resolution.coveredBy,
+      viaWorktreeLink: resolution.viaWorktreeLink,
+      broad,
+      offerRegister: resolution.status === 'unknown' && !broad,
+      reason: resolution.reason,
+    };
+  }
+
+  /**
+   * Register the current working directory at its resolved project root. The
+   * store refuses broad roots (WorkspaceRegistrationError) — we surface that
+   * honestly rather than record a phantom registration.
+   */
+  async register(label?: string): Promise<
+    | { readonly registered: true; readonly result: RegisterWorkspaceResult }
+    | { readonly registered: false; readonly refusedReason: string }
+  > {
+    try {
+      const result = await this.store.add(this.workingDirectory, label ? { label } : undefined);
+      return { registered: true, result };
+    } catch (error) {
+      if (error instanceof WorkspaceRegistrationError) {
+        return { registered: false, refusedReason: error.message };
+      }
+      throw error;
+    }
+  }
+
+  /** Remember a subtree-scoped decline at the current working directory. Idempotent. */
+  async decline(): Promise<{ readonly root: string; readonly alreadyDeclined: boolean }> {
+    return this.store.decline(this.workingDirectory);
+  }
+
+  /** The normalized working directory this manager asks about. */
+  getWorkingRoot(): string {
+    return normalizeWorkspaceRoot(this.workingDirectory);
+  }
+
+  /**
+   * A one-liner registration posture for `status`/`doctor`. Read-only.
+   */
+  async describe(): Promise<string> {
+    const evaluation = await this.evaluate();
+    switch (evaluation.status) {
+      case 'covered':
+        return evaluation.viaWorktreeLink
+          ? `registered (via worktree link to ${evaluation.coveredBy})`
+          : `registered (covered by ${evaluation.coveredBy})`;
+      case 'declined':
+        return 'not registered (registration declined for this directory)';
+      case 'unknown':
+        return evaluation.broad
+          ? 'not registered (this root is too broad to register)'
+          : 'not registered (never asked)';
+    }
+  }
+}

package/src/runtime/trust/workspace-trust.ts

@@ -0,0 +1,202 @@
+/**
+ * workspace-trust.ts — per-workspace trust gate.
+ *
+ * The first time GoodVibes opens a workspace (a cwd / project root it has no
+ * prior state for), that workspace is "restricted": only read-category tools
+ * run; write, execute, and delegate tools are denied until the user marks the
+ * workspace trusted. This is NOT a parallel permission checker — the decision
+ * is consulted by the real permission machinery at its final ask layer (the
+ * requestPermission callback wired in bootstrap-core.ts), so it composes with,
+ * and cannot drift from, the existing PermissionManager layer chain.
+ *
+ * Trust is persisted per-workspace in <cwd>/.goodvibes/tui/trust.json. A
+ * workspace that already carries GoodVibes runtime state (prior sessions,
+ * checkpoints, state, memory, or a project onboarding marker) is grandfathered
+ * as trusted on first load, so the gate only ever prompts for genuinely new
+ * places.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { JsonFileStore } from '@pellux/goodvibes-sdk/platform/state';
+import type { PermissionCategory } from '@pellux/goodvibes-sdk/platform/permissions';
+import type { PermissionPromptRequest, PermissionPromptDecision } from '@pellux/goodvibes-sdk/platform/permissions';
+
+type AskCallback = (request: PermissionPromptRequest) => Promise<PermissionPromptDecision>;
+
+/**
+ * Wrap the permission machinery's final ask callback with the workspace trust
+ * gate: in an untrusted workspace, deny any non-read tool outright instead of
+ * asking. This runs inside PermissionManager's own layer chain (it IS the ask
+ * layer), so it composes with — and cannot drift from — the real machinery.
+ */
+export function trustGatedAsk(manager: Pick<WorkspaceTrustManager, 'isCategoryAllowed'>, ask: AskCallback): AskCallback {
+  return (request) =>
+    manager.isCategoryAllowed(request.category) ? ask(request) : Promise.resolve({ approved: false });
+}
+
+export type WorkspaceTrustLevel = 'trusted' | 'restricted';
+
+interface PersistedWorkspaceTrust {
+  level: WorkspaceTrustLevel;
+  decidedAt: string;
+  grandfathered?: boolean;
+}
+
+const TRUST_FILE = 'trust.json';
+
+/**
+ * detectPriorWorkspaceState — true if <workingDirectory>/.goodvibes already
+ * holds GoodVibes RUNTIME state from a prior session. Deliberately keyed on
+ * generated state (sessions/checkpoints/state/memory/onboarding marker), not on
+ * committed scaffolding like .goodvibes/agents or GOODVIBES.md, so a checked-out
+ * template does not read as "previously used". MUST be sampled before any
+ * service initializes the workspace this session (bootstrap-core samples it
+ * before createRuntimeServices), or this-run scaffolding would look like prior
+ * use.
+ */
+export function detectPriorWorkspaceState(workingDirectory: string): boolean {
+  const root = join(workingDirectory, '.goodvibes');
+  if (!existsSync(root)) return false;
+
+  const fileSignals = [
+    join(root, 'checkpoints', 'index.json'),
+    join(root, 'tui', 'onboarding-checked.json'),
+    join(root, 'goodvibes.json'),
+  ];
+  for (const file of fileSignals) {
+    if (existsSync(file)) return true;
+  }
+
+  const dirSignals = ['sessions', 'checkpoints', 'state', 'memory'];
+  for (const dir of dirSignals) {
+    const path = join(root, dir);
+    try {
+      if (existsSync(path) && statSync(path).isDirectory() && readdirSync(path).length > 0) {
+        return true;
+      }
+    } catch {
+      // Unreadable — treat as absent rather than crash the gate.
+    }
+  }
+  return false;
+}
+
+export interface WorkspaceTrustPaths {
+  readonly projectGoodVibesRoot: string;
+  resolveProjectPath(...segments: string[]): string;
+}
+
+/** Read-only view of the persisted trust decision, for status/doctor reporting. */
+export interface PersistedWorkspaceTrustView {
+  /** 'trusted' | 'restricted' when a decision exists; 'undecided' when none is persisted yet. */
+  readonly level: WorkspaceTrustLevel | 'undecided';
+  readonly grandfathered: boolean;
+}
+
+/**
+ * readPersistedWorkspaceTrust — read <cwd>/.goodvibes/tui/trust.json WITHOUT the
+ * side effects of WorkspaceTrustManager.load() (which grandfathers and persists).
+ * Reporting surfaces (`status`/`doctor`) must never mutate trust state, so they
+ * use this pure reader instead of constructing a manager.
+ */
+export function readPersistedWorkspaceTrust(paths: WorkspaceTrustPaths): PersistedWorkspaceTrustView {
+  const file = paths.resolveProjectPath('tui', TRUST_FILE);
+  try {
+    if (!existsSync(file)) return { level: 'undecided', grandfathered: false };
+    const parsed = JSON.parse(readFileSync(file, 'utf-8')) as Partial<PersistedWorkspaceTrust>;
+    if (parsed.level === 'trusted' || parsed.level === 'restricted') {
+      return { level: parsed.level, grandfathered: parsed.grandfathered ?? false };
+    }
+  } catch {
+    // Unreadable/corrupt — report undecided rather than crash the report.
+  }
+  return { level: 'undecided', grandfathered: false };
+}
+
+export interface WorkspaceTrustManagerOptions {
+  readonly shellPaths: WorkspaceTrustPaths;
+  /** Whether the workspace already had prior GoodVibes runtime state at startup. */
+  readonly hadPriorState: boolean;
+}
+
+export class WorkspaceTrustManager {
+  private level: WorkspaceTrustLevel | null = null; // null = undecided (new place)
+  private grandfathered = false;
+  private loaded = false;
+  private readonly store: JsonFileStore<PersistedWorkspaceTrust>;
+  private readonly hadPriorState: boolean;
+
+  constructor(options: WorkspaceTrustManagerOptions) {
+    this.store = new JsonFileStore<PersistedWorkspaceTrust>(
+      options.shellPaths.resolveProjectPath('tui', TRUST_FILE),
+    );
+    this.hadPriorState = options.hadPriorState;
+  }
+
+  /**
+   * Load the persisted decision. If none exists, grandfather a workspace that
+   * already had prior GoodVibes state (persisting the decision so it is never
+   * re-evaluated); otherwise the workspace stays undecided and the gate treats
+   * it as restricted until the user chooses.
+   */
+  async load(): Promise<void> {
+    if (this.loaded) return;
+    const persisted = await this.store.load().catch(() => null);
+    if (persisted && (persisted.level === 'trusted' || persisted.level === 'restricted')) {
+      this.level = persisted.level;
+      this.grandfathered = persisted.grandfathered ?? false;
+      this.loaded = true;
+      return;
+    }
+    if (this.hadPriorState) {
+      this.level = 'trusted';
+      this.grandfathered = true;
+      await this.persist();
+    }
+    this.loaded = true;
+  }
+
+  isDecided(): boolean {
+    return this.level !== null;
+  }
+
+  /** Undecided workspaces read as 'restricted' — the safe default before a choice. */
+  getLevel(): WorkspaceTrustLevel {
+    return this.level ?? 'restricted';
+  }
+
+  isTrusted(): boolean {
+    return this.level === 'trusted';
+  }
+
+  wasGrandfathered(): boolean {
+    return this.grandfathered;
+  }
+
+  async setLevel(level: WorkspaceTrustLevel): Promise<void> {
+    this.level = level;
+    this.grandfathered = false;
+    this.loaded = true;
+    await this.persist();
+  }
+
+  /**
+   * The restriction rule the permission machinery consults. Read tools always
+   * run (read-only exploration is the whole point of "restricted"); every other
+   * category (write / execute / delegate) is denied until the workspace is
+   * trusted.
+   */
+  isCategoryAllowed(category: PermissionCategory): boolean {
+    if (this.isTrusted()) return true;
+    return category === 'read';
+  }
+
+  private async persist(): Promise<void> {
+    if (this.level === null) return;
+    await this.store.save({
+      level: this.level,
+      decidedAt: new Date().toISOString(),
+      grandfathered: this.grandfathered,
+    });
+  }
+}

package/src/runtime/ui-services.ts

@@ -10,6 +10,7 @@ import { SessionUnionCache, type SessionReadFacade } from '@pellux/goodvibes-sdk
 import type { ShellPathService } from '@/runtime/index.ts';
 import type { HostServiceStatus } from '@/runtime/index.ts';
 import type { SecretsManager } from '../config/secrets.ts';
+import type { buildRelayExternalServiceMethods } from './relay-reachability-bridge.ts';
 
 export interface UiEnvironmentServices {
   readonly workingDirectory: string;
@@ -63,7 +64,7 @@ export interface UiPlatformServices {
   readonly webhookNotifier: RuntimeServices['webhookNotifier'];
   readonly focusTracker: RuntimeServices['focusTracker'];
   readonly policyRuntimeState: RuntimeServices['policyRuntimeState'];
-  readonly externalServices?: {
+  readonly externalServices?: ReturnType<typeof buildRelayExternalServiceMethods> & {
     inspect(): {
       readonly daemonRunning: boolean;
       readonly daemonPortInUse?: boolean;

package/src/runtime/update-check.ts

@@ -0,0 +1,113 @@
+/**
+ * Pure logic for `/update`: version comparison, the latest-release-tag
+ * redirect lookup, and honest install-kind detection. No filesystem or
+ * process side effects here — everything takes its inputs as arguments so
+ * tests exercise it without touching the network or the host, matching the
+ * repo rule that tests never compare against the live build VERSION and
+ * never make live network calls.
+ *
+ * The self-update download/verify/swap orchestration that USES these lives
+ * in src/input/commands/update-runtime.ts; this module only decides "is
+ * there a newer version" and "can this install be swapped in place".
+ */
+
+export function normalizeVersion(version: string): string {
+  return version.replace(/^v/i, '').trim();
+}
+
+/**
+ * Compares two version strings component-wise as dotted non-negative
+ * integers (a leading "v" is ignored, matching the "vX.Y.Z" release tag
+ * format). Returns -1/0/1 for a<b / a==b / a>b. Non-numeric or missing
+ * components are treated as 0, so "1.2" and "1.2.0" compare equal.
+ */
+export function compareVersions(a: string, b: string): -1 | 0 | 1 {
+  const partsA = normalizeVersion(a).split('.');
+  const partsB = normalizeVersion(b).split('.');
+  const length = Math.max(partsA.length, partsB.length);
+  for (let i = 0; i < length; i++) {
+    const x = Number.parseInt(partsA[i] ?? '0', 10) || 0;
+    const y = Number.parseInt(partsB[i] ?? '0', 10) || 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Extracts the release tag from a GitHub "/releases/latest" redirect
+ * Location header, e.g. "https://github.com/mgd34msu/goodvibes-tui/releases/tag/v1.13.2"
+ * -> "v1.13.2". Mirrors scripts/install.sh's own redirect-URL tag parsing
+ * (it takes everything after the final slash of the redirect target).
+ */
+export function parseReleaseTagFromLocation(location: string | null | undefined): string | null {
+  if (!location) return null;
+  const segments = location.split('/').filter((segment) => segment.length > 0);
+  const tag = segments[segments.length - 1];
+  return tag && tag.length > 0 ? tag : null;
+}
+
+/** Minimal shape of the subset of the fetch API this module needs, so tests inject a stub instead of the real network. */
+export interface UpdateFetchLike {
+  (url: string, init?: { method?: string; redirect?: 'manual' | 'follow' | 'error' }): Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    readonly url: string;
+    readonly headers: { get(name: string): string | null };
+    text(): Promise<string>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+  }>;
+}
+
+/**
+ * Resolves the latest release tag the same way scripts/install.sh does:
+ * a HEAD request with redirects NOT followed, reading the tag out of the
+ * response's redirect Location header. Throws if no tag can be resolved —
+ * callers must not silently fall back to "already current".
+ */
+export async function resolveLatestReleaseTag(fetchImpl: UpdateFetchLike, releasesLatestUrl: string): Promise<string> {
+  const response = await fetchImpl(releasesLatestUrl, { method: 'HEAD', redirect: 'manual' });
+  const location = response.headers.get('location');
+  const tag = parseReleaseTagFromLocation(location) ?? (response.url !== releasesLatestUrl ? parseReleaseTagFromLocation(response.url) : null);
+  if (!tag) {
+    throw new Error(`could not resolve the latest release tag from ${releasesLatestUrl} (no redirect Location header)`);
+  }
+  return tag;
+}
+
+/**
+ * How this running process was installed, detected honestly from
+ * process.execPath rather than assumed:
+ *   - "binary": a standalone `bun build --compile` executable with no
+ *     package-manager ancestry — the scripts/install.sh install path.
+ *     Swappable in place.
+ *   - "bun-global-package": running the vendored binary shipped inside an
+ *     npm/bun-managed package install (execPath contains a "node_modules"
+ *     path segment — true for both `bun add -g` and a local project
+ *     dependency). Managed by the package manager; swapping the vendored
+ *     file in place would fight the next `bun add -g` upgrade, so this is
+ *     never swapped — the user re-runs their package manager instead.
+ *   - "source": running directly via the `bun` interpreter (`bun run
+ *     src/main.ts`), not a compiled binary at all.
+ */
+export type InstallKind = 'binary' | 'bun-global-package' | 'source';
+
+export function detectInstallKind(execPath: string): InstallKind {
+  const segments = execPath.split(/[\\/]/);
+  const execName = (segments[segments.length - 1] ?? '').toLowerCase();
+  if (execName === 'bun' || execName === 'bun.exe') {
+    return 'source';
+  }
+  if (segments.includes('node_modules')) {
+    return 'bun-global-package';
+  }
+  return 'binary';
+}
+
+/** The exact command to tell the user to run instead of a swap, for each non-binary install kind. */
+export function fallbackUpdateCommand(kind: Exclude<InstallKind, 'binary'>): string {
+  if (kind === 'bun-global-package') {
+    return 'bun add -g @pellux/goodvibes-tui';
+  }
+  return 'curl -fsSL https://goodvibes.sh/install.sh | sh';
+}

package/src/runtime/workspace-checkpointing.ts

@@ -0,0 +1,32 @@
+import { WorkspaceCheckpointManager } from '@pellux/goodvibes-sdk/platform/workspace';
+import { withCheckpointGuardSettings } from '../config/tui-extension-settings.ts';
+import type { ConfigManager } from '../config/index.ts';
+import type { RuntimeEventBus } from '@/runtime/index.ts';
+
+/**
+ * createWorkspaceCheckpointing — build the per-workspace checkpoint manager and
+ * kick off its initialization. Extracted from services.ts so the (load-bearing)
+ * failure-mode notes below live with the code they describe.
+ */
+export function createWorkspaceCheckpointing(opts: {
+  workspaceRoot: string;
+  runtimeBus: RuntimeEventBus;
+  configManager: ConfigManager;
+}): WorkspaceCheckpointManager {
+  // Checkpoint root-guard from the user's `checkpoints.*` config (docs/configuration.md;
+  // inert until the platform SDK's checkpoint manager exposes the keys — see the reader's note).
+  const manager = new WorkspaceCheckpointManager(
+    withCheckpointGuardSettings({ workspaceRoot: opts.workspaceRoot, runtimeBus: opts.runtimeBus }, opts.configManager),
+  );
+  // Fire-and-forget: subscriptions go live immediately if init() succeeds.
+  // If it rejects, WorkspaceCheckpointManager caches that rejection on
+  // `initPromise` and never clears it, so every later call (create/list/
+  // diff/restore — each awaits init() first) re-throws the same error
+  // forever: checkpointing becomes entirely unavailable for the rest of the
+  // session, not "degraded to manual-only". The `.catch(() => {})` here only
+  // exists to prevent an unhandled rejection at startup; the checkpoint
+  // commands (checkpoint-runtime.ts) are what actually catch and report the
+  // failure to the user, on first use.
+  void manager.init().catch(() => {});
+  return manager;
+}

package/src/runtime/workstream-attempts-validation.ts

@@ -0,0 +1,77 @@
+// ---------------------------------------------------------------------------
+// workstream-attempts-validation.ts — plan-format validation for best-of-N.
+//
+// The plan format re-enables the per-item `attempts` field (SDK WorkItem/
+// WorkItemSpec.attempts — best-of-N). A best-of-N item MAY be non-leaf: it may
+// declare its own `dependsOn` (each sibling inherits it) and other items may
+// depend on it — a dependent is held by the dependency gate until the group's
+// winner is picked and merged, then resolves to that winner (SDK
+// WorkItemSpec.attempts doc). The TUI enforces the engine's genuine constraints
+// at plan validation rather than letting a launch silently drop the field:
+//   • WORKTREE isolation. Best-of-N needs isolated worktrees to run and compare
+//     the N sibling attempts; under `shared` isolation the value is ignored.
+//   • STABLE id when depended upon. A dependency edge references an id, so a
+//     best-of-N item that others depend on must carry a stable `id`; an
+//     anonymous best-of-N item stays a leaf by construction (nothing can name it).
+// Values above the engine's MAX_ATTEMPTS (5) are clamped by the engine; the TUI
+// surfaces that as a note so the preview never overstates the fan-out.
+// ---------------------------------------------------------------------------
+
+import type { CreateWorkstreamInput } from '@pellux/goodvibes-sdk/platform/orchestration';
+
+/** The engine's hard cap on sibling attempts per work item (SDK MAX_ATTEMPTS). */
+export const MAX_ATTEMPTS = 5;
+
+export interface AttemptsValidation {
+  /** True when any item requests best-of-N (attempts >= 2). */
+  readonly hasAttempts: boolean;
+  /** Hard rule breaks that must block a launch (worktree isolation + stable id when depended upon). */
+  readonly violations: readonly string[];
+  /** Non-blocking notes (e.g. an over-cap value the engine will clamp). */
+  readonly notes: readonly string[];
+}
+
+function itemKey(item: CreateWorkstreamInput['items'][number]): string {
+  return item.id ?? item.title;
+}
+
+/**
+ * Validate a draft spec's best-of-N usage against the worktree-isolation and
+ * stable-id (when depended upon) constraints. Non-leaf best-of-N is allowed.
+ * Pure — no I/O. `violations` are hard (block launch); `notes` are advisory.
+ */
+export function validateAttempts(spec: CreateWorkstreamInput): AttemptsValidation {
+  const violations: string[] = [];
+  const notes: string[] = [];
+  const worktree = spec.isolation === 'worktree';
+
+  // Which items are depended upon (so a best-of-N item that is a dependency
+  // target can be checked for the stable-id requirement).
+  const dependedUpon = new Set<string>();
+  for (const item of spec.items) {
+    for (const dep of item.dependsOn ?? []) dependedUpon.add(dep);
+  }
+
+  let hasAttempts = false;
+  for (const item of spec.items) {
+    const attempts = item.attempts ?? 1;
+    if (attempts < 2) continue;
+    hasAttempts = true;
+    const label = item.title;
+
+    if (!worktree) {
+      violations.push(`"${label}" requests ${attempts} attempts, but the workstream is not worktree-isolated — best-of-N needs isolated trees. Set --isolation worktree.`);
+    }
+    // Non-leaf best-of-N is allowed. The only structural requirement: if other
+    // items depend on this one, it must carry a stable id for the dependency
+    // edge to name — an anonymous best-of-N item cannot be a dependency target.
+    if (dependedUpon.has(itemKey(item)) && !item.id) {
+      violations.push(`another item depends on best-of-N item "${label}", but it has no stable id — give the item an id so the dependency can resolve to the winner (an anonymous best-of-N item cannot be a dependency target).`);
+    }
+    if (attempts > MAX_ATTEMPTS) {
+      notes.push(`"${label}" requests ${attempts} attempts — the engine caps best-of-N at ${MAX_ATTEMPTS}, so ${MAX_ATTEMPTS} siblings will run.`);
+    }
+  }
+
+  return { hasAttempts, violations, notes };
+}