@cueloop/client 0.1.0-alpha.15 → 0.1.0-alpha.16

package/src/components/WalkWizard.tsx

@@ -0,0 +1,146 @@
+/**
+ * The guided walk's focused card wizard (#83): one card per changed file
+ * floating over the dimmed diff, with a plain step count in the title - no
+ * progress bar. Below the main card a separate gray-bordered block carries
+ * the submitting agent's note for the file, when one exists. Past the last
+ * file the end card offers the submit action directly with honest counts.
+ * The keys live in the keymap's walk overlay; this component only renders.
+ */
+
+import React from "react";
+import type { Theme } from "../theme";
+import { useComponentTheme } from "./theme-context";
+import type { WalkFile } from "../walk";
+import { viewedCount } from "../walk";
+import { Card } from "./primitives/Card";
+import { Button } from "./primitives/Button";
+import { Toolbar } from "./primitives/Toolbar";
+
+export interface WalkWizardProps {
+  files: WalkFile[];
+  /** The wizard step; index === files.length renders the end card. */
+  index: number;
+  viewedPaths: ReadonlySet<string>;
+  /** The agent's note for the current file; the gray block renders only when set. */
+  note?: string;
+  /** Terminal width bounds the card width. */
+  terminalWidth: number;
+  /** End-card submit: leaves the walk and opens the rail confirm. */
+  onSubmitRequest: () => void;
+  onBack: () => void;
+  theme?: Theme;
+}
+
+/** The card never crowds the terminal edge nor stretches past reading width. */
+function wizardWidth(terminalWidth: number): number {
+  return Math.min(72, Math.max(24, terminalWidth - 8));
+}
+
+/** Note rows from a crude wrap estimate, capped so the block stays a block. */
+function noteRows(note: string, innerWidth: number): number {
+  return Math.min(3, Math.max(1, Math.ceil(note.length / Math.max(1, innerWidth))));
+}
+
+export function WalkWizard({
+  files,
+  index,
+  viewedPaths,
+  note,
+  terminalWidth,
+  onSubmitRequest,
+  onBack,
+  theme,
+}: WalkWizardProps): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  const width = wizardWidth(terminalWidth);
+  const viewed = viewedCount(files, viewedPaths);
+  const atEnd = index >= files.length;
+  const currentFile = files[index];
+
+  return (
+    <box
+      style={{
+        position: "absolute",
+        left: 0,
+        top: 0,
+        width: "100%",
+        height: "100%",
+        alignItems: "center",
+        justifyContent: "center",
+        flexDirection: "column",
+      }}
+    >
+      <box style={{ width, flexDirection: "column" }}>
+        {atEnd || !currentFile ? (
+          <Card
+            title=" walk complete "
+            contentRows={3}
+            borderColor={tokens.green}
+            backgroundColor={tokens.panel}
+            theme={theme}
+          >
+            <text fg={tokens.text}>
+              {viewed === files.length
+                ? `every file viewed (${viewed}/${files.length})`
+                : `${viewed} of ${files.length} files viewed`}
+            </text>
+            <box style={{ height: 1 }} />
+            <Toolbar>
+              <Button variant="solid" marginRight={2} onPress={onSubmitRequest} theme={theme}>
+                {" Submit review "}
+              </Button>
+              <Button onPress={onBack} theme={theme}>
+                {" [ back "}
+              </Button>
+            </Toolbar>
+          </Card>
+        ) : (
+          <>
+            <Card
+              title={` file ${index + 1} of ${files.length} · ${viewed} viewed `}
+              contentRows={3 + Math.max(1, currentFile.preview.length)}
+              borderColor={tokens.accent}
+              backgroundColor={tokens.panel}
+              theme={theme}
+            >
+              <text fg={tokens.text}>{currentFile.path}</text>
+              <text>
+                <span fg={tokens.green}>{`+${currentFile.added}`}</span>
+                <span fg={tokens.textDim}>{" "}</span>
+                <span fg={tokens.red}>{`-${currentFile.removed}`}</span>
+                <span fg={tokens.textDim}>{viewedPaths.has(currentFile.path) ? " · viewed" : ""}</span>
+              </text>
+              <box style={{ height: 1 }} />
+              {currentFile.preview.length === 0 ? (
+                <text fg={tokens.textDim}>(no changed lines)</text>
+              ) : (
+                currentFile.preview.map((previewLine, previewIndex) => (
+                  <text
+                    key={previewIndex}
+                    style={{ wrapMode: "none" }}
+                    fg={previewLine.sign === "+" ? tokens.insFg : tokens.delFg}
+                  >
+                    {previewLine.sign + previewLine.text}
+                  </text>
+                ))
+              )}
+            </Card>
+            {note !== undefined ? (
+              <box style={{ marginTop: 1, flexDirection: "column" }}>
+                <Card
+                  title=" agent note "
+                  contentRows={noteRows(note, width - 4)}
+                  borderColor={tokens.border}
+                  backgroundColor={tokens.panel}
+                  theme={theme}
+                >
+                  <text fg={tokens.textMuted}>{note}</text>
+                </Card>
+              </box>
+            ) : null}
+          </>
+        )}
+      </box>
+    </box>
+  );
+}

package/src/components/__snapshots__/stories.test.tsx.snap

@@ -1184,6 +1184,136 @@ exports[`stories catalog theme-context/ProviderSwap renders, snapshots, and carr
                                                                                 
                                                                                 
                                                                                 
+                                                                                
+"
+`;
+
+exports[`stories catalog ConfirmCard/WithViewedSummary renders, snapshots, and carries its colors: ConfirmCard/WithViewedSummary 1`] = `
+"╭─ submit review ─────────────────────╮ 
+│ 1 annotations · 0 blocking          │ 
+│ 2/3 files viewed                    │ 
+│                                     │ 
+│  Comment  [Approve]  Changes        │ 
+│                                     │ 
+│ summary for the agent (optional)    │ 
+│                                     │ 
+│  Submit    Cancel                   │ 
+╰─────────────────────────────────────╯ 
+                                        
+                                        
+                                        
+                                        
+"
+`;
+
+exports[`stories catalog WalkWizard/EndCard renders, snapshots, and carries its colors: WalkWizard/EndCard 1`] = `
+"                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+    ╭─ walk complete ──────────────────────────────────────────────────────╮    
+    │ every file viewed (3/3)                                              │    
+    │                                                                      │    
+    │  Submit review    [ back                                             │    
+    ╰──────────────────────────────────────────────────────────────────────╯    
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+"
+`;
+
+exports[`stories catalog WalkWizard/EndCardPartialPass renders, snapshots, and carries its colors: WalkWizard/EndCardPartialPass 1`] = `
+"                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+    ╭─ walk complete ──────────────────────────────────────────────────────╮    
+    │ 1 of 3 files viewed                                                  │    
+    │                                                                      │    
+    │  Submit review    [ back                                             │    
+    ╰──────────────────────────────────────────────────────────────────────╯    
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+"
+`;
+
+exports[`stories catalog WalkWizard/FirstFile renders, snapshots, and carries its colors: WalkWizard/FirstFile 1`] = `
+"                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+    ╭─ file 1 of 3 · 0 viewed ─────────────────────────────────────────────╮    
+    │ packages/daemon/src/store.ts                                         │    
+    │ +12 -3                                                               │    
+    │                                                                      │    
+    │ +const viewed = new Set<string>();                                   │    
+    │ +record.viewedPaths = [...viewed];                                   │    
+    │ -// viewed tracking lives in the client only                         │    
+    ╰──────────────────────────────────────────────────────────────────────╯    
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+"
+`;
+
+exports[`stories catalog WalkWizard/WithAgentNote renders, snapshots, and carries its colors: WalkWizard/WithAgentNote 1`] = `
+"                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+    ╭─ file 2 of 3 · 1 viewed ─────────────────────────────────────────────╮    
+    │ packages/client/src/walk.ts                                          │    
+    │ +48 -0                                                               │    
+    │                                                                      │    
+    │ +export function firstUnviewedIndex(files, viewed) {                 │    
+    ╰──────────────────────────────────────────────────────────────────────╯    
+                                                                                
+    ╭─ agent note ─────────────────────────────────────────────────────────╮    
+    │ New module: pure helpers that pick the next unviewed file. No IO,    │    
+    │ unit tested.                                                         │    
+    ╰──────────────────────────────────────────────────────────────────────╯    
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
                                                                                 
 "
 `;

package/src/config.ts

@@ -46,6 +46,7 @@ export const DEFAULT_KEYS: Record<string, string[]> = {
   delete_annotation: ["backspace"],
   submit: ["return", "enter"],
   quit: ["q"],
+  walk: ["w"],
 };
 
 function parseToml(text: string): Record<string, unknown> {

package/src/key-bindings.test.ts

@@ -8,7 +8,7 @@ import { describe, expect, test } from "bun:test";
 import { DEFAULT_KEYS } from "./config";
 import { KeyBindings } from "./key-bindings";
 
-function bindings(context: { overlay?: "none" | "compose" | "submit"; spanMode?: boolean } = {}): KeyBindings {
+function bindings(context: { overlay?: "none" | "walk" | "compose" | "submit"; spanMode?: boolean } = {}): KeyBindings {
   const resolver = new KeyBindings(DEFAULT_KEYS);
   resolver.setContext({ overlay: context.overlay ?? "none", spanMode: context.spanMode ?? false });
   return resolver;
@@ -62,6 +62,17 @@ describe("mode layers own their keys", () => {
     expect(resolver.resolveAction({ name: "right", shift: false })).toBe("cycle_verdict_right");
     expect(resolver.resolveAction({ name: "return", shift: false })).toBe("submit_verdict");
   });
+
+  test("the walk overlay owns the bracket stepping and leaves the grammar keys dead", () => {
+    const resolver = bindings({ overlay: "walk" });
+    expect(resolver.resolveAction({ name: "]", shift: false })).toBe("walk_next");
+    expect(resolver.resolveAction({ name: "[", shift: false })).toBe("walk_prev");
+    expect(resolver.resolveAction({ name: "escape", shift: false })).toBe("walk_leave");
+    expect(resolver.resolveAction({ name: "return", shift: false })).toBe("walk_submit");
+    expect(resolver.resolveAction({ name: "q", shift: false })).toBe("quit");
+    expect(resolver.resolveAction({ name: "j", shift: false })).toBeUndefined();
+    expect(resolver.resolveAction({ name: "c", shift: false })).toBeUndefined();
+  });
 });
 
 describe("getActiveKeys-generated status hints", () => {
@@ -89,6 +100,12 @@ describe("getActiveKeys-generated status hints", () => {
     expect(bindings({ overlay: "submit" }).statusHint("submit")).toBe("verdict ←/→ · ⏎ submit · esc cancel");
   });
 
+  test("walk hint", () => {
+    expect(bindings({ overlay: "walk" }).statusHint("walk")).toBe(
+      "walk · ] next (marks viewed) · [ back · esc leave walk · q quit",
+    );
+  });
+
   test("read-only hint", () => {
     expect(bindings().statusHint("read-only")).toBe("observer - read-only · j/k move · n/p annotations · q quit");
   });

package/src/key-bindings.ts

@@ -24,7 +24,7 @@ export interface KeyLayerContext {
 }
 
 /** Hint templates keyed by the same view states the status line shows. */
-export type HintMode = "normal" | "card" | "span" | "compose" | "submit" | "read-only";
+export type HintMode = "normal" | "card" | "span" | "compose" | "submit" | "walk" | "read-only";
 
 type HintEntry =
   | { text: string }
@@ -70,6 +70,13 @@ const HINT_TEMPLATES: Record<HintMode, HintEntry[]> = {
     { commands: ["submit_verdict"], label: "submit" },
     { commands: ["cancel_submit"], label: "cancel" },
   ],
+  walk: [
+    { text: "walk" },
+    { commands: ["walk_next"], label: "next (marks viewed)" },
+    { commands: ["walk_prev"], label: "back" },
+    { commands: ["walk_leave"], label: "leave walk" },
+    { commands: ["quit"], label: "quit" },
+  ],
   "read-only": [
     { text: "observer - read-only" },
     { commands: ["down", "up"], label: "move" },
@@ -243,6 +250,20 @@ export class KeyBindings {
       bindings: SPAN_COMMANDS.map(([key, command]) => ({ key, cmd: command })),
       commands: SPAN_COMMANDS.map(([, command]) => record(command)),
     });
+    // the walk wizard: prev/next stepping, leave, and submit from the end card
+    this.keymap.registerLayer({
+      priority: 20,
+      when: () => this.context.overlay === "walk",
+      bindings: [
+        { key: "]", cmd: "walk_next" },
+        { key: "[", cmd: "walk_prev" },
+        { key: "escape", cmd: "walk_leave" },
+        { key: "return", cmd: "walk_submit" },
+        { key: "enter", cmd: "walk_submit" },
+        { key: "q", cmd: "quit" },
+      ],
+      commands: [record("walk_next"), record("walk_prev"), record("walk_leave"), record("walk_submit"), record("quit")],
+    });
     this.keymap.registerLayer({
       priority: 20,
       when: () => this.context.overlay === "compose",

package/src/keymap.test.ts

@@ -20,6 +20,7 @@ function state(patch: Partial<KeyState> = {}): KeyState {
     annotationCount: 1,
     hasFocusedAnnotation: true,
     cursorAnnotatable: true,
+    walkAtEnd: false,
     ...patch,
   };
 }
@@ -228,6 +229,42 @@ describe("diff mode", () => {
   });
 });
 
+describe("guided walk", () => {
+  test("w enters the walk in diff view; resolved and read-only sessions answer", () => {
+    expect(reduceKey(state({ view: "diff" }), key("w"))).toEqual([{ t: "walkStart" }]);
+    expect(reduceKey(state({ view: "diff", resolved: true }), key("w"))).toEqual([
+      { t: "status", msg: "review submitted - read-only" },
+    ]);
+    expect(reduceKey(state({ view: "diff", readOnly: true }), key("w"))).toEqual([
+      { t: "status", msg: "observer - read-only" },
+    ]);
+    expect(reduceKey(state(), key("w"))).toEqual([{ t: "status", msg: "the guided walk is a diff-review mode" }]);
+  });
+
+  const walking = state({ view: "diff", overlay: "walk" });
+  const table: [string, Intent[]][] = [
+    ["]", [{ t: "walkForward" }]],
+    ["[", [{ t: "walkBack" }]],
+    ["escape", [{ t: "walkLeave" }]],
+    ["q", [{ t: "exit" }]],
+    // mid-walk return does nothing: submit lives on the end card only
+    ["return", []],
+    ["j", []],
+    ["c", []],
+  ];
+  for (const [name, expected] of table) {
+    test(`walking ${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(walking, key(name))).toEqual(expected);
+    });
+  }
+
+  test("the end card's return leaves the walk and opens the submit confirm", () => {
+    const atEnd = state({ view: "diff", overlay: "walk", walkAtEnd: true });
+    expect(reduceKey(atEnd, key("return"))).toEqual([{ t: "walkLeave" }, { t: "openSubmit" }]);
+    expect(reduceKey(atEnd, key("enter"))).toEqual([{ t: "walkLeave" }, { t: "openSubmit" }]);
+  });
+});
+
 describe("duplicated-branch collapse", () => {
   test("plan and diff produce the same intents for annotation nav, delete, and submit", () => {
     for (const patch of [

package/src/keymap.ts

@@ -23,6 +23,10 @@ export type Intent =
   | { t: "editCard" }
   | { t: "nextAnn" }
   | { t: "prevAnn" }
+  | { t: "walkStart" }
+  | { t: "walkForward" }
+  | { t: "walkBack" }
+  | { t: "walkLeave" }
   | { t: "removeAnnotation" }
   | { t: "deselect" }
   | { t: "closeOverlay" }
@@ -43,10 +47,12 @@ export interface KeyState {
   keys: Record<string, string[]>;
   readOnly: boolean;
   /** Layer that owns keys before the grammar runs. */
-  overlay: "none" | "compose" | "submit" | "completion-prompt" | "completion-counting";
+  overlay: "none" | "walk" | "compose" | "submit" | "completion-prompt" | "completion-counting";
   view: "inbox" | "plan" | "diff";
   /** Plan-only span selection sub-mode. */
   spanMode: boolean;
+  /** The walk cursor sits on the end card - return offers the submit action. */
+  walkAtEnd: boolean;
   resolved: boolean;
   hasInboxItems: boolean;
   annotationCount: number;
@@ -56,7 +62,7 @@ export interface KeyState {
 }
 
 /** Verbs that write session state; an observer never reaches their handlers. */
-const MUTATING_ACTIONS = new Set(["comment", "suggest", "cut", "edit", "delete_annotation", "submit"]);
+const MUTATING_ACTIONS = new Set(["comment", "suggest", "cut", "edit", "delete_annotation", "submit", "walk"]);
 
 const SPAN_KEYS = ["l", "h", "w", "b", "$", "0"];
 
@@ -90,6 +96,19 @@ export function reduceKey(state: KeyState, key: KeyInput, resolvedAction?: strin
     if (name === "escape") return [{ t: "dismissCompletion" }];
     return [];
   }
+  // the walk wizard owns its keys while active: ] advances (marking the
+  // current file viewed), [ steps back, escape leaves keeping progress, and
+  // return on the end card hands over to the submit confirm
+  if (state.overlay === "walk") {
+    if (name === "]") return [{ t: "walkForward" }];
+    if (name === "[") return [{ t: "walkBack" }];
+    if (name === "escape") return [{ t: "walkLeave" }];
+    if ((name === "return" || name === "enter") && state.walkAtEnd) {
+      return [{ t: "walkLeave" }, { t: "openSubmit" }];
+    }
+    if (name === "q") return [{ t: "exit" }];
+    return [];
+  }
   const action = resolvedAction ?? actionFor(state.keys, name, key.shift);
   if (action === "quit") return [{ t: "exit" }];
   // the ONE read-only rule: any mutating attempt answers instead of acting
@@ -114,6 +133,11 @@ function inboxGrammar(state: KeyState, name: string): Intent[] {
 function diffGrammar(state: KeyState, action: string | undefined): Intent[] {
   const nav = navIntent(action);
   if (nav) return nav;
+  if (action === "walk") {
+    // marking viewed writes the session record, so a resolved review answers
+    if (state.resolved) return status("review submitted - read-only");
+    return [{ t: "walkStart" }];
+  }
   if (action === "comment") {
     if (state.resolved) return status("review submitted - read-only");
     if (!state.cursorAnnotatable) return status("move to a code line to comment");
@@ -139,6 +163,7 @@ function spanGrammar(name: string): Intent[] {
 function planGrammar(state: KeyState, action: string | undefined, name: string): Intent[] {
   const nav = navIntent(action);
   if (nav) return nav;
+  if (action === "walk") return status("the guided walk is a diff-review mode");
   if (name === "escape") return [{ t: "deselect" }];
   if (action === "span") return state.cursorAnnotatable ? [{ t: "startSpan" }] : [];
   if (action === "comment" || action === "suggest") {

package/src/session-controller.ts

@@ -24,6 +24,7 @@ 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 { firstUnviewedIndex, walkFiles, type WalkFile } from "./walk";
 import { editInEditor } from "./editor";
 import { focusHerdrPane, returnPaneFor } from "./herdr";
 import { persistAutoClose, type AutoClose, type CueloopConfig } from "./config";
@@ -53,6 +54,12 @@ export interface ControllerSnapshot {
    * hand-off - the reconciliation banner count. 0 = no banner.
    */
   editOrphanCount: number;
+  /**
+   * The guided walk's cursor (diff sessions): which wizard step is on
+   * screen. index === file count is the end card. null = not walking; the
+   * viewed set itself rides the session record, so leaving loses nothing.
+   */
+  walk: { index: number } | null;
 }
 
 export interface ReviewControllerOptions {
@@ -79,6 +86,8 @@ export interface ReviewController {
   /** Derived projections, cached per session identity. */
   display(): DisplayBlock[];
   rows(): DiffRow[];
+  /** The walk's step list, derived from the diff rows. */
+  files(): WalkFile[];
   working(): string;
   /** Open a session from the inbox. */
   open(id: string): void;
@@ -95,6 +104,13 @@ export interface ReviewController {
   updateAnnotation(id: string, body: string): void;
   removeAnnotation(id: string): void;
   setWorkingCopy(content: string | undefined): void;
+  /** Enter the guided walk at the first unviewed file (diff sessions). */
+  walkStart(): void;
+  /** Mark the current file viewed (persists with the session) and advance. */
+  walkForward(): void;
+  walkBack(): void;
+  /** Leave the walk; the viewed set stays on the session record. */
+  walkLeave(): 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. */
@@ -119,6 +135,7 @@ class Controller implements ReviewController {
     error: null,
     completion: { phase: "idle" },
     editOrphanCount: 0,
+    walk: null,
   };
   private listeners = new Set<() => void>();
   private autoClose: AutoClose = "off";
@@ -128,7 +145,11 @@ class Controller implements ReviewController {
   private countdown: TimerHandle | undefined;
   /** Projections keyed by session identity so renders reuse one computation. */
   private derivedFor: ReviewSession | null = null;
-  private derived: { display: DisplayBlock[]; rows: DiffRow[] } = { display: [], rows: [] };
+  private derived: { display: DisplayBlock[]; rows: DiffRow[]; files: WalkFile[] } = {
+    display: [],
+    rows: [],
+    files: [],
+  };
 
   constructor(private readonly opts: ReviewControllerOptions) {
     this.readOnly = opts.readOnly ?? false;
@@ -201,9 +222,11 @@ class Controller implements ReviewController {
     const s = this.snap.session;
     if (this.derivedFor === s) return;
     this.derivedFor = s;
+    const rows = s && s.artifact.type === "diff" ? diffRows(s.artifact.content) : [];
     this.derived = {
       display: s ? buildDisplay(s.artifact.content, s.workingCopy) : [],
-      rows: s && s.artifact.type === "diff" ? diffRows(s.artifact.content) : [],
+      rows,
+      files: walkFiles(rows),
     };
   }
 
@@ -217,6 +240,11 @@ class Controller implements ReviewController {
     return this.derived.rows;
   }
 
+  files(): WalkFile[] {
+    this.ensureDerived();
+    return this.derived.files;
+  }
+
   working(): string {
     const s = this.snap.session;
     return s ? (s.workingCopy ?? s.artifact.content) : "";
@@ -250,6 +278,7 @@ class Controller implements ReviewController {
 
   // ── verbs ───────────────────────────────────
   open(id: string): void {
+    this.locallyViewed.clear();
     const cached = this.snap.inbox?.find((s) => s.id === id);
     if (cached) this.update({ session: cached });
     else void this.refreshSession(id);
@@ -364,9 +393,54 @@ class Controller implements ReviewController {
     this.apply(this.client!.sessionSetWorkingCopy(session.id, content));
   }
 
+  // ── the guided walk ─────────────────────────
+  // Marks sent but possibly not yet reflected in the session snapshot; the
+  // union keeps the walk title truthful and rapid advances from losing marks.
+  private locallyViewed = new Set<string>();
+
+  private viewedSet(): Set<string> {
+    return new Set([...(this.snap.session?.viewedPaths ?? []), ...this.locallyViewed]);
+  }
+
+  walkStart(): void {
+    const session = this.snap.session;
+    if (!session || session.artifact.type !== "diff") return;
+    const files = this.files();
+    if (files.length === 0) return this.setStatus("nothing to walk - the diff is empty");
+    // resume at the first unviewed file; a finished walk reopens on the end card
+    this.update({ walk: { index: firstUnviewedIndex(files, this.viewedSet()) } });
+  }
+
+  walkForward(): void {
+    const walk = this.snap.walk;
+    const session = this.snap.session;
+    if (!walk || !session) return;
+    const files = this.files();
+    const current = files[walk.index];
+    if (!current) return; // already on the end card
+    // advancing IS the viewed mark: the step is complete once you move past
+    // it; the daemon verb merges, so only the new path travels
+    if (!this.viewedSet().has(current.path)) {
+      this.locallyViewed.add(current.path);
+      this.apply(this.client!.sessionSetViewed(session.id, [current.path]));
+    }
+    this.update({ walk: { index: walk.index + 1 } });
+  }
+
+  walkBack(): void {
+    const walk = this.snap.walk;
+    if (!walk) return;
+    this.update({ walk: { index: Math.max(0, walk.index - 1) } });
+  }
+
+  walkLeave(): void {
+    if (this.snap.walk) this.update({ walk: null });
+  }
+
   submit(verdict: VerdictKind, summary: string): void {
     const session = this.snap.session;
     if (!session) return;
+    this.walkLeave();
     this.client!.sessionResolve(session.id, verdict, summary)
       .then((resolved) => {
         // The completion overlay heading already states the verdict, so the