@cueloop/client 0.1.0-alpha.10 → 0.1.0-alpha.101

package/src/keymap.ts

@@ -1,173 +0,0 @@
-/**
- * The keyboard grammar as a pure reducer (#70): view state in, intents out.
- * App builds a KeyState per key event, calls reduceKey, and dispatches the
- * intents to controller verbs and view-state setters - no branch bodies live
- * in the key handler. Diff and plan reviews share one path for annotation
- * navigation, deletion, and submit; the read-only rule is one gate here.
- */
-
-import { actionFor } from "./config";
-
-export type Intent =
-  | { t: "exit" }
-  | { t: "status"; msg: string }
-  | { t: "move"; to: "down" | "up" | "top" | "bottom" }
-  | { t: "inboxMove"; to: "down" | "up" }
-  | { t: "openSession" }
-  | { t: "startSpan" }
-  | { t: "spanKey"; name: string }
-  | { t: "openCompose"; kind: "comment" | "suggestion"; from: "cursor" | "span" }
-  | { t: "openSubmit" }
-  | { t: "cut" }
-  | { t: "edit" }
-  | { t: "editCard" }
-  | { t: "nextAnn" }
-  | { t: "prevAnn" }
-  | { t: "removeAnnotation" }
-  | { t: "deselect" }
-  | { t: "closeOverlay" }
-  | { t: "saveCompose" }
-  | { t: "submitVerdict" }
-  | { t: "cycleVerdict"; dir: -1 | 1 }
-  | { t: "finishReview" }
-  | { t: "optInAutoClose" }
-  | { t: "dismissCompletion" };
-
-export interface KeyInput {
-  name: string;
-  shift: boolean;
-}
-
-export interface KeyState {
-  /** Loaded keymap (config.ts): action -> key combos. */
-  keys: Record<string, string[]>;
-  readOnly: boolean;
-  /** Layer that owns keys before the grammar runs. */
-  overlay: "none" | "compose" | "submit" | "completion-prompt" | "completion-counting";
-  view: "inbox" | "plan" | "diff";
-  /** Plan-only span selection sub-mode. */
-  spanMode: boolean;
-  resolved: boolean;
-  hasInboxItems: boolean;
-  annotationCount: number;
-  hasFocusedAnnotation: boolean;
-  /** Cursor sits on annotatable text: a work block (plan) or a code row (diff). */
-  cursorAnnotatable: boolean;
-}
-
-/** Verbs that write session state; an observer never reaches their handlers. */
-const MUTATING_ACTIONS = new Set(["comment", "suggest", "cut", "edit", "delete_annotation", "submit"]);
-
-const SPAN_KEYS = ["l", "h", "w", "b", "$", "0"];
-
-function status(msg: string): Intent[] {
-  return [{ t: "status", msg }];
-}
-
-export function reduceKey(state: KeyState, key: KeyInput): Intent[] {
-  const name = key.name;
-  // compose/submit overlays own the keys via focused inputs; only escape,
-  // return, and verdict arrows route through the grammar
-  if (state.overlay === "compose" || state.overlay === "submit") {
-    if (name === "escape") return [{ t: "closeOverlay" }];
-    if (name === "return" || name === "enter") {
-      return [state.overlay === "compose" ? { t: "saveCompose" } : { t: "submitVerdict" }];
-    }
-    if (state.overlay === "submit" && (name === "left" || name === "right")) {
-      return [{ t: "cycleVerdict", dir: name === "left" ? -1 : 1 }];
-    }
-    return [];
-  }
-  if (state.overlay === "completion-prompt" || state.overlay === "completion-counting") {
-    if (name === "return" || name === "enter" || name === "q") return [{ t: "finishReview" }];
-    if (name === "a" && state.overlay === "completion-prompt") return [{ t: "optInAutoClose" }];
-    if (name === "escape") return [{ t: "dismissCompletion" }];
-    return [];
-  }
-  const action = actionFor(state.keys, name, key.shift);
-  if (action === "quit") return [{ t: "exit" }];
-  // the ONE read-only rule: any mutating attempt answers instead of acting
-  // (span-mode c/s are hardwired keys, so they gate by name as well)
-  const mutating = MUTATING_ACTIONS.has(action ?? "") || (state.spanMode && (name === "c" || name === "s"));
-  if (state.readOnly && mutating) return status("observer - read-only");
-
-  if (state.view === "inbox") return inboxGrammar(state, name);
-  if (state.view === "diff") return diffGrammar(state, action);
-  if (state.spanMode) return spanGrammar(name);
-  return planGrammar(state, action, name);
-}
-
-function inboxGrammar(state: KeyState, name: string): Intent[] {
-  if (!state.hasInboxItems) return [];
-  if (name === "j" || name === "down") return [{ t: "inboxMove", to: "down" }];
-  if (name === "k" || name === "up") return [{ t: "inboxMove", to: "up" }];
-  if (name === "return" || name === "enter") return [{ t: "openSession" }];
-  return [];
-}
-
-function diffGrammar(state: KeyState, action: string | undefined): Intent[] {
-  const nav = navIntent(action);
-  if (nav) return nav;
-  if (action === "comment") {
-    if (state.resolved) return status("review submitted - read-only");
-    if (!state.cursorAnnotatable) return status("move to a code line to comment");
-    return [{ t: "openCompose", kind: "comment", from: "cursor" }];
-  }
-  const shared = annotationCluster(state, action);
-  if (shared) return shared;
-  if (action === "span" || action === "cut" || action === "edit" || action === "suggest") {
-    return status("plan-only verb - diff review uses c on a line");
-  }
-  return [];
-}
-
-function spanGrammar(name: string): Intent[] {
-  if (name === "escape") return [{ t: "closeOverlay" }];
-  if (SPAN_KEYS.includes(name)) return [{ t: "spanKey", name }];
-  if (name === "c" || name === "s") {
-    return [{ t: "openCompose", kind: name === "s" ? "suggestion" : "comment", from: "span" }];
-  }
-  return [];
-}
-
-function planGrammar(state: KeyState, action: string | undefined, name: string): Intent[] {
-  const nav = navIntent(action);
-  if (nav) return nav;
-  if (name === "escape") return [{ t: "deselect" }];
-  if (action === "span") return state.cursorAnnotatable ? [{ t: "startSpan" }] : [];
-  if (action === "comment" || action === "suggest") {
-    if (state.resolved) return status("review submitted - read-only");
-    if (!state.cursorAnnotatable) return status("text is cut - restore it first");
-    return [{ t: "openCompose", kind: action === "suggest" ? "suggestion" : "comment", from: "cursor" }];
-  }
-  if (action === "cut" || action === "edit") {
-    if (state.resolved) return status("review submitted - read-only");
-    // the document selects, the rail edits: with a card selected, Cut deletes
-    // the annotation and edit rewrites the card body in place
-    if (state.hasFocusedAnnotation) return [action === "cut" ? { t: "removeAnnotation" } : { t: "editCard" }];
-    return [{ t: action }];
-  }
-  return annotationCluster(state, action) ?? [];
-}
-
-/** Cursor movement is the same intent everywhere; views clamp their own bounds. */
-function navIntent(action: string | undefined): Intent[] | null {
-  if (action === "down" || action === "up" || action === "top" || action === "bottom") {
-    return [{ t: "move", to: action }];
-  }
-  return null;
-}
-
-/** Annotation navigation, deletion, and submit: one path for plan and diff. */
-function annotationCluster(state: KeyState, action: string | undefined): Intent[] | null {
-  if (action === "next_annotation" || action === "prev_annotation") {
-    if (!state.annotationCount) return status("no annotations");
-    return [{ t: action === "next_annotation" ? "nextAnn" : "prevAnn" }];
-  }
-  if (action === "delete_annotation") {
-    if (state.resolved || !state.hasFocusedAnnotation) return [];
-    return [{ t: "removeAnnotation" }];
-  }
-  if (action === "submit") return state.resolved ? [] : [{ t: "openSubmit" }];
-  return null;
-}

package/src/run.ts

@@ -1,30 +0,0 @@
-/** Real-terminal entry: render the App and resolve when the user quits. */
-
-import React from "react";
-import { createCliRenderer } from "@opentui/core";
-import { createRoot } from "@opentui/react";
-import { App } from "./App";
-
-export interface RunClientOptions {
-  sessionId?: string;
-  home?: string;
-}
-
-export async function runClient(opts: RunClientOptions): Promise<number> {
-  // mouse movement reporting makes multiplexers forward drags to the app,
-  // so the renderer's native selection is the drag driver
-  const renderer = await createCliRenderer({ enableMouseMovement: true });
-  return new Promise<number>((resolve) => {
-    createRoot(renderer).render(
-      React.createElement(App, {
-        home: opts.home,
-        sessionId: opts.sessionId,
-        onExit: (code: number) => {
-          renderer.destroy();
-          resolve(code);
-          process.exit(code);
-        },
-      }),
-    );
-  });
-}

package/src/serve.ts

@@ -1,75 +0,0 @@
-/**
- * SSH-served TUI (#22 share path): `cueloop serve` lets teammates join a
- * review session over plain ssh. Every SSH connection renders <App> in
- * observer mode (readOnly) against the same local daemon; the one writable
- * controller stays the local owner's own `cueloop` TUI.
- *
- * Trust model - tunnel of trust, no passwords, no keys:
- * the server authenticates nobody ("open" auth). Access control is the act of
- * sharing the address deliberately: it binds to 127.0.0.1 by default, so a
- * remote teammate reaches it only through a channel the owner opened on
- * purpose (an SSH tunnel, a tailnet address via --host). Anyone who can reach
- * the port can watch - and only watch: observers cannot mutate the session.
- * The host key is generated once under CUELOOP_HOME/ssh/host_key (0600) so
- * fingerprints stay stable across restarts.
- */
-
-import { mkdirSync } from "node:fs";
-import { join } from "node:path";
-import React from "react";
-import { createRoot } from "@opentui/react";
-import { createServer } from "@opentui/ssh";
-import { cueloopHome } from "@cueloop/daemon";
-import { App } from "./App";
-
-export interface ServeOptions {
-  /** TCP port for the SSH listener; 0 picks an ephemeral port. Default 2222. */
-  port?: number;
-  /** Bind address. Default 127.0.0.1 - widen deliberately (e.g. a tailnet IP). */
-  host?: string;
-  /** Open every connection on this session; omit for the inbox. */
-  sessionId?: string;
-  /** CUELOOP_HOME override (daemon socket + ssh host key live under it). */
-  home?: string;
-  /** Silence the @opentui/ssh startup banner (tests). Default true. */
-  banner?: boolean;
-  onError?: (err: unknown) => void;
-}
-
-export interface ServeHandle {
-  host: string;
-  port: number;
-  /** SHA256 host-key fingerprints, for out-of-band verification. */
-  fingerprints: string[];
-  close(): Promise<void>;
-}
-
-export async function serveClient(opts: ServeOptions = {}): Promise<ServeHandle> {
-  const home = opts.home ?? cueloopHome();
-  const sshDir = join(home, "ssh");
-  mkdirSync(sshDir, { recursive: true, mode: 0o700 });
-
-  const server = createServer({
-    // password-less by design; see the trust model in the module comment
-    auth: "open",
-    hostKey: { path: join(sshDir, "host_key") },
-    startupBanner: opts.banner ?? true,
-    idleTimeout: "2h",
-    onError: opts.onError,
-  }).serve((session) => {
-    const root = createRoot(session.renderer);
-    root.render(
-      React.createElement(App, {
-        home,
-        sessionId: opts.sessionId,
-        readOnly: true,
-        // q disconnects only this observer, never the server
-        onExit: () => session.end(),
-      }),
-    );
-    session.onClose(() => root.unmount());
-  });
-
-  const info = await server.listen(opts.port ?? 2222, opts.host ?? "127.0.0.1");
-  return { ...info, close: () => server.close() };
-}

package/src/session-controller.ts

@@ -1,398 +0,0 @@
-/**
- * The review-session controller (#70): every daemon round-trip and mutation
- * verb behind one React-free object. It owns connect/autostart/subscribe,
- * the session/inbox/status/error snapshot, optimistic apply, the mutation
- * verbs (cut/edit/annotate/submit/...), and the post-submit completion
- * lifecycle including the notes-vault export and the herdr return-focus.
- * App subscribes to snapshots and keeps only view state.
- */
-
-import { DaemonClient } from "@cueloop/daemon/client";
-import {
-  cutBlock,
-  makeAnchor,
-  newAnnotationId,
-  parseBlocks,
-  resolveAnchor,
-  restoreBlock,
-  restoreLine,
-  type ReviewSession,
-  type VerdictKind,
-} from "@cueloop/schema";
-import { Registry, type Exporter } from "@cueloop/extension-api";
-import { createObsidianExtension, shouldExport, type ObsidianConfig } from "@cueloop/integration-obsidian";
-import { buildDisplay, nextWorkBlock, type DisplayBlock } from "./view";
-import { diffRowAnchor, diffRows, type DiffRow } from "./view-diff";
-import { editInEditor } from "./editor";
-import { focusHerdrPane, returnPaneFor } from "./herdr";
-import { persistAutoClose, type AutoClose, type CueloopConfig } from "./config";
-
-/**
- * Post-submit lifecycle (a review pane should hand you back to the agent,
- * not linger): idle → prompt (auto-close off: offer the choice) or
- * counting (configured delay) → exit. esc dismisses to the resolved view.
- */
-export type Completion =
-  | { phase: "idle" }
-  | { phase: "prompt" }
-  | { phase: "counting"; remaining: number }
-  | { phase: "dismissed" };
-
-export interface ControllerSnapshot {
-  session: ReviewSession | null;
-  inbox: ReviewSession[] | null;
-  status: string;
-  error: string | null;
-  completion: Completion;
-  /**
-   * Annotations whose anchor stopped resolving after the last editor
-   * hand-off - the reconciliation banner count. 0 = no banner.
-   */
-  editOrphanCount: number;
-}
-
-export interface ReviewControllerOptions {
-  home?: string;
-  sessionId?: string;
-  /** Observer mode: stored for the key reducer's read-only gate. */
-  readOnly?: boolean;
-  onExit?: (code: number) => void;
-}
-
-export interface ReviewController {
-  readonly readOnly: boolean;
-  /** Snapshot listeners (stable identity - safe for useSyncExternalStore). */
-  subscribe(listener: () => void): () => void;
-  getSnapshot(): ControllerSnapshot;
-  /** Dial the daemon (autostart), subscribe to events, fetch session or inbox. */
-  connect(): void;
-  close(): void;
-  /** Loaded config parts the controller acts on: auto-close and exporters. */
-  applyConfig(cfg: CueloopConfig): void;
-  setStatus(msg: string): void;
-  /** Derived projections, cached per session identity. */
-  display(): DisplayBlock[];
-  rows(): DiffRow[];
-  working(): string;
-  /** Open a session from the inbox. */
-  open(id: string): void;
-  /** Cut the block under the cursor, or restore a cut one. */
-  cut(dispIdx: number): void;
-  /** The $EDITOR hand-off on the working copy. */
-  edit(): void;
-  /**
-   * Anchor and store an annotation; both plan and diff anchor constructions.
-   * Returns the minted annotation id so the view can select the new card.
-   */
-  annotate(kind: "comment" | "suggestion", dispIdx: number, start: number, end: number, body: string): string | undefined;
-  /** Rewrite a stored annotation's body in place (the rail-card edit). */
-  updateAnnotation(id: string, body: string): void;
-  removeAnnotation(id: string): void;
-  setWorkingCopy(content: string | undefined): void;
-  /** Resolve the review, run the export, start the completion hand-back. */
-  submit(verdict: VerdictKind, summary: string): void;
-  /** Close the review and, inside herdr, bounce focus back to the agent. */
-  finishReview(): void;
-  dismissCompletion(): void;
-  /** From the completion prompt: persist auto-close and start the countdown. */
-  optInAutoClose(): void;
-}
-
-export function createReviewController(opts: ReviewControllerOptions): ReviewController {
-  return new Controller(opts);
-}
-
-class Controller implements ReviewController {
-  readonly readOnly: boolean;
-  private client: DaemonClient | null = null;
-  private closed = false;
-  private snap: ControllerSnapshot = {
-    session: null,
-    inbox: null,
-    status: "",
-    error: null,
-    completion: { phase: "idle" },
-    editOrphanCount: 0,
-  };
-  private listeners = new Set<() => void>();
-  private autoClose: AutoClose = "off";
-  private obsidian: ObsidianConfig | null = null;
-  private exporters = new Map<string, Exporter>();
-  private countdown: ReturnType<typeof setTimeout> | undefined;
-  /** Projections keyed by session identity so renders reuse one computation. */
-  private derivedFor: ReviewSession | null = null;
-  private derived: { display: DisplayBlock[]; rows: DiffRow[] } = { display: [], rows: [] };
-
-  constructor(private readonly opts: ReviewControllerOptions) {
-    this.readOnly = opts.readOnly ?? false;
-  }
-
-  subscribe = (listener: () => void): (() => void) => {
-    this.listeners.add(listener);
-    return () => this.listeners.delete(listener);
-  };
-
-  getSnapshot = (): ControllerSnapshot => this.snap;
-
-  private update(patch: Partial<ControllerSnapshot>): void {
-    this.snap = { ...this.snap, ...patch };
-    for (const l of this.listeners) l();
-  }
-
-  connect(): void {
-    void (async () => {
-      try {
-        const client = await DaemonClient.connect({ home: this.opts.home, autostart: true });
-        if (this.closed) return void client.close();
-        this.client = client;
-        client.onEvent((e) => {
-          // another controller/observer changed state: re-fetch
-          const s = this.snap.session;
-          if (s && e.sessionId === s.id) void this.refreshSession(s.id);
-          if (!this.opts.sessionId) void this.refreshInbox();
-        });
-        await client.subscribe();
-        if (this.opts.sessionId) {
-          this.update({ session: await client.sessionGet(this.opts.sessionId) });
-        } else {
-          this.update({ inbox: await client.sessionList({ status: "pending" }) });
-        }
-      } catch (err) {
-        this.update({ error: err instanceof Error ? err.message : String(err) });
-      }
-    })();
-  }
-
-  close(): void {
-    this.closed = true;
-    clearTimeout(this.countdown);
-    this.client?.close();
-  }
-
-  applyConfig(cfg: CueloopConfig): void {
-    this.autoClose = cfg.ui.autoClose;
-    this.obsidian = cfg.integrations.obsidian;
-    // bundled integrations register through the public extension API
-    const registry = new Registry();
-    void registry.load("obsidian", createObsidianExtension(cfg.integrations.obsidian)).then((rec) => {
-      this.exporters = rec.exporters;
-    });
-  }
-
-  setStatus(msg: string): void {
-    this.update({ status: msg });
-  }
-
-  // ── derived projections ─────────────────────
-  private ensureDerived(): void {
-    const s = this.snap.session;
-    if (this.derivedFor === s) return;
-    this.derivedFor = s;
-    this.derived = {
-      display: s ? buildDisplay(s.artifact.content, s.workingCopy) : [],
-      rows: s && s.artifact.type === "diff" ? diffRows(s.artifact.content) : [],
-    };
-  }
-
-  display(): DisplayBlock[] {
-    this.ensureDerived();
-    return this.derived.display;
-  }
-
-  rows(): DiffRow[] {
-    this.ensureDerived();
-    return this.derived.rows;
-  }
-
-  working(): string {
-    const s = this.snap.session;
-    return s ? (s.workingCopy ?? s.artifact.content) : "";
-  }
-
-  private async refreshSession(id: string): Promise<void> {
-    if (this.client) this.update({ session: await this.client.sessionGet(id) });
-  }
-
-  private async refreshInbox(): Promise<void> {
-    if (this.client) this.update({ inbox: await this.client.sessionList({ status: "pending" }) });
-  }
-
-  /** Optimistic apply: the daemon response is the next session snapshot. */
-  private apply(p: Promise<ReviewSession>): void {
-    p.then((session) => this.update({ session })).catch((e: unknown) =>
-      this.setStatus(String(e instanceof Error ? e.message : e)),
-    );
-  }
-
-  // ── verbs ───────────────────────────────────
-  open(id: string): void {
-    const cached = this.snap.inbox?.find((s) => s.id === id);
-    if (cached) this.update({ session: cached });
-    else void this.refreshSession(id);
-  }
-
-  cut(dispIdx: number): void {
-    const session = this.snap.session;
-    if (!session || session.status === "resolved") return;
-    const d = this.display()[dispIdx];
-    if (!d) return;
-    const working = this.working();
-    if (d.type === "del") {
-      const line = restoreLine(nextWorkBlock(this.display(), dispIdx), working.split("\n").length);
-      // restoreBlock returns undefined when the block structure round-trips
-      // to the submitted revision - the working copy is gone
-      const restored = restoreBlock(session.artifact.content, working, d.base!, line);
-      this.setWorkingCopy(restored);
-      this.setStatus("cut restored");
-    } else if (d.work) {
-      this.setWorkingCopy(cutBlock(working, d.work));
-      this.setStatus("block cut - it serializes into the diff");
-    }
-  }
-
-  edit(): void {
-    const session = this.snap.session;
-    if (!session || session.status === "resolved") return;
-    try {
-      const result = editInEditor(this.working(), "plan.md");
-      if (result.changed) {
-        this.setWorkingCopy(result.content);
-        this.reconcileAnnotations(session, result.content);
-        this.setStatus("edits tracked - one diff");
-      } else this.setStatus("no changes");
-    } catch (err) {
-      this.setStatus(err instanceof Error ? err.message : String(err));
-    }
-  }
-
-  /**
-   * Edit-exit reconciliation: re-resolve every annotation against the edited
-   * working copy with the quote-primary cascade. Annotations that stop
-   * resolving stay stored (the feedback serializer flags orphaned anchors);
-   * the count feeds the one-line banner above the sheet.
-   */
-  private reconcileAnnotations(session: ReviewSession, editedContent: string): void {
-    const editedBlocks = parseBlocks(editedContent);
-    const orphanCount = session.annotations.filter(
-      (annotation) => resolveAnchor(annotation.anchor, editedBlocks) === null,
-    ).length;
-    this.update({ editOrphanCount: orphanCount });
-  }
-
-  annotate(
-    kind: "comment" | "suggestion",
-    dispIdx: number,
-    start: number,
-    end: number,
-    body: string,
-  ): string | undefined {
-    const session = this.snap.session;
-    if (!session) return undefined;
-    let anchor;
-    if (session.artifact.type === "diff") {
-      anchor = { ...diffRowAnchor(this.rows(), dispIdx), blockIndex: dispIdx };
-    } else {
-      const display = this.display();
-      const workBlocks = display.filter((d) => d.work).map((d) => d.work!);
-      const workIdx = display.slice(0, dispIdx + 1).filter((d) => d.work).length - 1;
-      anchor = makeAnchor(workBlocks, workIdx, start, end);
-    }
-    const annotationId = newAnnotationId();
-    this.apply(
-      this.client!.sessionAnnotate(session.id, {
-        id: annotationId,
-        kind,
-        anchor,
-        body,
-      }),
-    );
-    this.setStatus(kind === "suggestion" ? "suggestion added - the agent applies it" : "comment added");
-    return annotationId;
-  }
-
-  updateAnnotation(id: string, body: string): void {
-    const session = this.snap.session;
-    if (!session) return;
-    const existing = session.annotations.find((annotation) => annotation.id === id);
-    if (!existing) return;
-    // the daemon's annotate verb upserts by id: same id + anchor, new body
-    this.apply(
-      this.client!.sessionAnnotate(session.id, {
-        id: existing.id,
-        kind: existing.kind,
-        anchor: existing.anchor,
-        body,
-      }),
-    );
-    this.setStatus("annotation updated");
-  }
-
-  removeAnnotation(id: string): void {
-    const session = this.snap.session;
-    if (!session) return;
-    this.apply(this.client!.sessionRemoveAnnotation(session.id, id));
-    this.setStatus("annotation deleted");
-  }
-
-  setWorkingCopy(content: string | undefined): void {
-    const session = this.snap.session;
-    if (!session) return;
-    this.apply(this.client!.sessionSetWorkingCopy(session.id, content));
-  }
-
-  submit(verdict: VerdictKind, summary: string): void {
-    const session = this.snap.session;
-    if (!session) return;
-    this.client!.sessionResolve(session.id, verdict, summary)
-      .then((resolved) => {
-        this.update({ session: resolved, status: `review submitted - ${verdict.replace("_", " ")}` });
-        // notes-vault export: guarded by config, default is manual (no-op)
-        const obsidian = this.obsidian;
-        const exporter = this.exporters.get("obsidian");
-        if (obsidian && exporter && shouldExport(obsidian.exportOn, verdict)) {
-          void exporter(resolved).then((r) => {
-            this.setStatus(r.success && r.path ? `exported to ${r.path}` : `export failed: ${r.error ?? "unknown"}`);
-          });
-        }
-        // hand the reviewer back to the agent: prompt or count down per config;
-        // inside herdr with a known return pane, closing is the default
-        const delay = this.autoClose;
-        const returns = returnPaneFor(resolved.artifact.meta.herdrPane) !== undefined;
-        if (delay === 0) this.finishReview();
-        else if (typeof delay === "number") this.startCounting(delay);
-        else if (returns) this.startCounting(3);
-        else this.update({ completion: { phase: "prompt" } });
-      })
-      .catch((e: unknown) => this.setStatus(String(e instanceof Error ? e.message : e)));
-  }
-
-  // ── completion hand-back ────────────────────
-  private startCounting(remaining: number): void {
-    if (remaining <= 0) return this.finishReview();
-    this.update({ completion: { phase: "counting", remaining } });
-    this.countdown = setTimeout(() => this.startCounting(remaining - 1), 1000);
-  }
-
-  finishReview(): void {
-    clearTimeout(this.countdown);
-    const pane = returnPaneFor(this.snap.session?.artifact.meta.herdrPane);
-    if (pane) focusHerdrPane(pane);
-    this.opts.onExit?.(0);
-  }
-
-  dismissCompletion(): void {
-    clearTimeout(this.countdown);
-    this.update({ completion: { phase: "dismissed" } });
-  }
-
-  optInAutoClose(): void {
-    // opt in: close in 3s from now on, persisted to the user config
-    try {
-      persistAutoClose(3);
-    } catch {
-      // a read-only config dir must not block closing the review
-    }
-    this.autoClose = 3;
-    this.startCounting(3);
-  }
-}