@promptctl/cc-candybar 1.30.0 → 1.32.0

package/src/daemon/config-overrides-store.ts

@@ -322,43 +322,94 @@ export function loadOverrides(
   };
 }
 
-// [LAW:no-silent-failure] Atomic write shared by set/clear: read the current
-// overrides, apply one mutation, write-to-temp + rename. Owner-only mode,
-// matching every other daemon runtime file (session-state.json, pid, lease).
+// [LAW:no-silent-failure] The atomic write/rename dance, generalized over ANY
+// JSON-serializable value — both this module's flat overrides dict and its
+// history stack (below) go through this one primitive rather than each
+// re-implementing mkdir+tmp+chmod+rename. Owner-only mode, matching every
+// other daemon runtime file (session-state.json, pid, lease). `label` names
+// the failure in the log/thrown message (the caller's own vocabulary —
+// "config-overrides"/"config-overrides-history" — not derived from the path,
+// so the wording a test might match on stays stable across either file).
 // Unlike session-state.json's debounced best-effort flush (no synchronous
-// caller waiting on it), a `persist` write is directly caused by a click that
-// expects a truthful ack — a swallowed failure here would let the verb
-// handler log "set-config: ..." as if it landed when nothing was written.
-// Logs at "error" for the daemon-log breadcrumb, then RETHROWS so the caller
-// (the click) fails loudly instead of claiming a success that didn't happen.
-function writeOverrides(
+// caller waiting on it), a `persist`/`undo`/`redo` write is directly caused
+// by a click that expects a truthful ack — a swallowed failure here would let
+// the verb handler log success for a write that didn't land. Logs at "error"
+// for the daemon-log breadcrumb, then RETHROWS so the caller (the click)
+// fails loudly instead of claiming a success that didn't happen.
+function writeJsonAtomic(
   filePath: string,
-  overrides: Readonly<Record<string, string | number | boolean>>,
+  label: string,
+  value: unknown,
   logger: DaemonLogger,
 ): void {
   try {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     const tmp = `${filePath}.tmp`;
-    fs.writeFileSync(tmp, JSON.stringify(overrides), { mode: 0o600 });
+    fs.writeFileSync(tmp, JSON.stringify(value), { mode: 0o600 });
     fs.chmodSync(tmp, 0o600);
     fs.renameSync(tmp, filePath);
   } catch (e) {
-    const message = `config-overrides write failed: ${(e as Error).message}`;
+    const message = `${label} write failed: ${(e as Error).message}`;
     logger("error", message);
     throw new Error(message);
   }
 }
 
+function writeOverrides(
+  filePath: string,
+  overrides: Readonly<Record<string, string | number | boolean>>,
+  logger: DaemonLogger,
+): void {
+  writeJsonAtomic(filePath, "config-overrides", overrides, logger);
+}
+
+// [LAW:one-source-of-truth] The one place a key's value in the flat dict
+// changes (set-or-delete) — writeConfigOverride/clearConfigOverride/
+// restoreConfigOverrideValue all fold through here, so "what was the value
+// BEFORE this write" (the fact history needs) is captured at the one site
+// that reads-then-writes it, never re-derived. `value: undefined` deletes;
+// any other value sets. Returns the previous value (or undefined if the key
+// was absent) — the caller decides whether that fact matters.
+function mutateOverride(
+  filePath: string,
+  key: string,
+  value: string | number | boolean | undefined,
+  logger: DaemonLogger,
+): string | number | boolean | undefined {
+  const overrides = loadRawOverrides(filePath, logger);
+  const prev = overrides[key];
+  if (value === undefined) {
+    if (!(key in overrides)) return prev;
+    const next = { ...overrides };
+    delete next[key];
+    writeOverrides(filePath, next, logger);
+  } else {
+    writeOverrides(filePath, { ...overrides, [key]: value }, logger);
+  }
+  return prev;
+}
+
+// [LAW:one-source-of-truth] `persist`'s write, TRACKED: mutate the key, then
+// record the transition on the SAME global history undo/redo step
+// (brandon-layout-edit-2gc.2). This is the ONE enforcement point — every
+// current and future caller of writeConfigOverride (setConfig, stepConfig,
+// apply-layout-op's append) gets history for free, with zero edits to those
+// verb handlers, because the recording lives here rather than at each call
+// site. [LAW:locality-or-seam]
 export function writeConfigOverride(
   filePath: string,
   key: string,
   value: string | number | boolean,
   logger: DaemonLogger = quietLogger,
 ): void {
-  const overrides = loadRawOverrides(filePath, logger);
-  writeOverrides(filePath, { ...overrides, [key]: value }, logger);
+  const prev = mutateOverride(filePath, key, value, logger);
+  pushHistoryEntry(filePath, { key, from: prev ?? null, to: value }, logger);
 }
 
+// [LAW:one-source-of-truth] `reset`'s write, TRACKED — mirrors
+// writeConfigOverride above. A clear that touches nothing (the key was
+// already absent) records no entry: nothing changed, so there is nothing to
+// undo back to.
 export function clearConfigOverride(
   filePath: string,
   key: string,
@@ -366,7 +417,247 @@ export function clearConfigOverride(
 ): void {
   const overrides = loadRawOverrides(filePath, logger);
   if (!(key in overrides)) return;
-  const next = { ...overrides };
-  delete next[key];
-  writeOverrides(filePath, next, logger);
+  const prev = mutateOverride(filePath, key, undefined, logger);
+  pushHistoryEntry(filePath, { key, from: prev ?? null, to: null }, logger);
+}
+
+// [LAW:one-source-of-truth] The UNTRACKED twin — restores a key to EXACTLY
+// `value` (or clears it, for `null`) without recording a new history entry.
+// The only legitimate callers are popPastEntry/popFutureEntry below: undo and
+// redo already know they're moving an entry between the past/future stacks,
+// so routing their own restoration back through the tracked writers would
+// record the undo/redo AS a new forward edit — burying the entry it just
+// popped and making the OTHER stack unreachable. This is a structurally
+// distinct function, not a boolean flag on the tracked ones
+// [LAW:no-mode-explosion] — its contract ("apply this exact value, no
+// bookkeeping") is different from theirs ("write this value, remember how to
+// undo it"), not a variant of the same one.
+function restoreConfigOverrideValue(
+  filePath: string,
+  key: string,
+  value: string | number | boolean | null,
+  logger: DaemonLogger,
+): void {
+  mutateOverride(filePath, key, value === null ? undefined : value, logger);
+}
+
+// ─── Undo/redo history (brandon-layout-edit-2gc.2) ────────────────────────
+
+// [LAW:types-are-the-program] ONE entry shape covers every scope the
+// overrides file holds — a globals field's snapshot overwrite (setConfig), a
+// segment-palette snapshot overwrite (same verb, different key shape), AND a
+// preset-root-ops APPEND (apply-layout-op's read-current-append-write) —
+// because at the STORAGE layer every one of those is indistinguishable from
+// "the value at `key` changed from `from` to `to`". apply-layout-op computes
+// its new array-of-tokens string by reading-then-appending one level up
+// (verbs/index.ts); by the time that string reaches writeConfigOverride, it
+// is just the next value at that key. Undo restoring `from` verbatim is
+// therefore ALSO the correct "pop the last op token" behavior for a rootOps
+// key, with no rootOps-specific code anywhere in this module — the ticket's
+// "one history over the overrides layer, not a layout-specific feature" falls
+// out of the shape, it isn't special-cased into it. `null` is the ABSENT
+// sentinel (a key with no prior/no resulting value): safe because no real
+// override value is ever `null` — see isValidOverrides's kind table.
+export interface HistoryEntry {
+  readonly key: string;
+  readonly from: string | number | boolean | null;
+  readonly to: string | number | boolean | null;
+}
+
+interface HistoryState {
+  readonly past: readonly HistoryEntry[];
+  readonly future: readonly HistoryEntry[];
+}
+
+const EMPTY_HISTORY: HistoryState = { past: [], future: [] };
+
+// [LAW:carrying-cost] Resolves the ticket's "depth of the ring" question:
+// bounded so a long-running daemon's history file cannot grow without limit,
+// generous enough that no realistic editing session bumps into it. Oldest
+// entries fall off first (capPush below) — a silent, documented trim, not a
+// failure.
+const MAX_HISTORY_DEPTH = 50;
+
+// [LAW:one-source-of-truth] Resolves the ticket's "where it lives relative to
+// the overrides file" question: a SIBLING file in the same directory, derived
+// as a pure function of the overrides path already passed in — no reach to
+// paths.ts/global state, so every existing call site (and every existing
+// test's XDG_STATE_HOME isolation, which already isolates configOverridesPath())
+// isolates this file too, with zero additional test-harness surface. Kept
+// SEPARATE from the overrides file itself (rather than nesting it inside a
+// wrapper shape) so the overrides file's own on-disk shape — asserted by
+// name in existing tests and callers — never changes
+// [LAW:locality-or-seam]: a change to history storage must not ripple into
+// every existing reader of the flat overrides dict.
+function historyPathFor(overridesFilePath: string): string {
+  return path.join(
+    path.dirname(overridesFilePath),
+    "config-overrides-history.json",
+  );
+}
+
+function isValidHistoryValue(
+  v: unknown,
+): v is string | number | boolean | null {
+  return (
+    v === null ||
+    typeof v === "string" ||
+    typeof v === "number" ||
+    typeof v === "boolean"
+  );
+}
+
+function isValidHistoryEntry(v: unknown): v is HistoryEntry {
+  if (v === null || typeof v !== "object") return false;
+  const obj = v as Record<string, unknown>;
+  return (
+    typeof obj.key === "string" &&
+    isValidHistoryValue(obj.from) &&
+    isValidHistoryValue(obj.to)
+  );
+}
+
+// [LAW:no-silent-failure] Missing/corrupt/wrong-shape file → the empty
+// history is the DEFINED recovery (mirrors isValidOverrides/loadRawOverrides'
+// identical "first-ever boot" treatment for the sibling file) — a single
+// malformed entry drops the WHOLE history, never a guess at which entries to
+// salvage.
+function isValidHistoryState(v: unknown): v is HistoryState {
+  if (v === null || typeof v !== "object" || Array.isArray(v)) return false;
+  const obj = v as Record<string, unknown>;
+  return (
+    Array.isArray(obj.past) &&
+    obj.past.every(isValidHistoryEntry) &&
+    Array.isArray(obj.future) &&
+    obj.future.every(isValidHistoryEntry)
+  );
+}
+
+function loadHistoryState(
+  overridesFilePath: string,
+  logger: DaemonLogger,
+): HistoryState {
+  const filePath = historyPathFor(overridesFilePath);
+  let raw: string;
+  try {
+    raw = fs.readFileSync(filePath, "utf8");
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT") {
+      logger(
+        "warn",
+        `config-overrides-history read failed (${code}); starting empty`,
+      );
+    }
+    return EMPTY_HISTORY;
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (isValidHistoryState(parsed)) return parsed;
+    logger(
+      "warn",
+      `config-overrides-history load: unexpected shape, starting empty`,
+    );
+    return EMPTY_HISTORY;
+  } catch {
+    logger(
+      "warn",
+      `config-overrides-history load: corrupt JSON, starting empty`,
+    );
+    return EMPTY_HISTORY;
+  }
+}
+
+function writeHistoryState(
+  overridesFilePath: string,
+  state: HistoryState,
+  logger: DaemonLogger,
+): void {
+  writeJsonAtomic(
+    historyPathFor(overridesFilePath),
+    "config-overrides-history",
+    state,
+    logger,
+  );
+}
+
+// [LAW:no-mode-explosion] Bounded push, oldest-drops-first, shared by both
+// stacks (past grows on a fresh edit or a redo; future grows on an undo) —
+// one shape, not two near-duplicate arms.
+function capPush<T>(arr: readonly T[], entry: T, max: number): readonly T[] {
+  const next = [...arr, entry];
+  return next.length > max ? next.slice(next.length - max) : next;
+}
+
+// [LAW:one-source-of-truth] The ONLY caller is writeConfigOverride/
+// clearConfigOverride above — every tracked write lands here, so recording
+// cannot drift from mutation. A fresh edit TRUNCATES `future`: the classic
+// undo/redo branch — diverging from history by doing something NEW abandons
+// whatever was undone, rather than silently keeping it reachable from a
+// history state the new edit has already invalidated.
+function pushHistoryEntry(
+  overridesFilePath: string,
+  entry: HistoryEntry,
+  logger: DaemonLogger,
+): void {
+  const state = loadHistoryState(overridesFilePath, logger);
+  writeHistoryState(
+    overridesFilePath,
+    { past: capPush(state.past, entry, MAX_HISTORY_DEPTH), future: [] },
+    logger,
+  );
+}
+
+// [LAW:one-source-of-truth] The daemon-GLOBAL history is ONE stack, not
+// per-session: config-overrides.json already has exactly one writer (the
+// daemon) and no session-scoping (candybar-config-engine-71o's own binding
+// guardrail — a `persist` write is daemon-global by design), so undo/redo
+// stepping that SAME single-writer file inherits the same scope rather than
+// inventing a session axis the storage layer doesn't otherwise have. Two
+// sessions clicking undo do see each other's edits — a real, DELIBERATE
+// consequence of there being one bar default, not a bug: the alternative
+// (per-session history over daemon-global state) would let one session's
+// "undo" silently fail to undo what another session's click actually did.
+//
+// [LAW:no-silent-failure] Returns `null` at the bottom of the stack — the
+// verb handler (verbs/index.ts) turns that into a loud BadVerbArgs surfaced
+// through click.error, never a silent no-op.
+export function undoLastOverride(
+  overridesFilePath: string,
+  logger: DaemonLogger = quietLogger,
+): HistoryEntry | null {
+  const state = loadHistoryState(overridesFilePath, logger);
+  const entry = state.past[state.past.length - 1];
+  if (entry === undefined) return null;
+  restoreConfigOverrideValue(overridesFilePath, entry.key, entry.from, logger);
+  writeHistoryState(
+    overridesFilePath,
+    {
+      past: state.past.slice(0, -1),
+      future: capPush(state.future, entry, MAX_HISTORY_DEPTH),
+    },
+    logger,
+  );
+  return entry;
+}
+
+// [LAW:no-silent-failure] Redo's mirror of undo above — `null` at the top of
+// the stack, same loud surfacing contract.
+export function redoLastOverride(
+  overridesFilePath: string,
+  logger: DaemonLogger = quietLogger,
+): HistoryEntry | null {
+  const state = loadHistoryState(overridesFilePath, logger);
+  const entry = state.future[state.future.length - 1];
+  if (entry === undefined) return null;
+  restoreConfigOverrideValue(overridesFilePath, entry.key, entry.to, logger);
+  writeHistoryState(
+    overridesFilePath,
+    {
+      past: capPush(state.past, entry, MAX_HISTORY_DEPTH),
+      future: state.future.slice(0, -1),
+    },
+    logger,
+  );
+  return entry;
 }

package/src/daemon/verbs/config-validators.ts

@@ -15,6 +15,7 @@ import {
   perConfigDomainsFor,
   resolveOptionDomain,
 } from "../../config/option-domain";
+import { addableSegmentDomains } from "../../config/edit-chrome";
 import type { DslConfig } from "../../config/dsl-types";
 import { isGlobalsField } from "../config-overrides-store";
 import { encodeLayoutOp } from "../../config/layout-ops";
@@ -111,6 +112,34 @@ function actionKeySpecs(
       },
     ];
   }
+  // [LAW:one-source-of-truth] brandon-layout-edit-2gc.3's domain-sourced
+  // sibling: the allow-list is the ENCODED op token for every domain member,
+  // not the raw member — mirroring how a literal `insertSegment` contributes
+  // its own single encoded token above. A click carrying an option this
+  // domain never named — or naming a real segment but the wrong anchor/
+  // relation — cannot decode to a member of this list, so it is rejected the
+  // same loud way an unknown literal op token already is.
+  if ("insertSegmentFrom" in a) {
+    return [
+      {
+        key: a.persist,
+        spec: {
+          kind: "allow-list",
+          allowed: resolveOptionDomain(
+            a.insertSegmentFrom,
+            perConfigDomains,
+          ).map((segment) =>
+            encodeLayoutOp({
+              op: "insert",
+              segment,
+              anchor: a.anchor,
+              relation: a.relation,
+            }),
+          ),
+        },
+      },
+    ];
+  }
   return [
     {
       key: a.persist,
@@ -141,7 +170,16 @@ function configKeySeeds(config: DslConfig): ReadonlyMap<string, number> {
 
 function actionContributions(config: DslConfig): KeySpecContribution[] {
   const seeds = configKeySeeds(config);
-  const perConfigDomains = perConfigDomainsFor(config);
+  // [LAW:one-source-of-truth] The "addable segment" domains
+  // (edit-chrome.ts's `addableSegmentDomains`) merge in here alongside
+  // looks/presets — the same per-preset seam `insertSegmentFrom` resolves
+  // through at render (render.ts's registerDslConfig merges the identical
+  // map), so the rendered picker options and the derived click gate can
+  // never diverge over what's addable.
+  const perConfigDomains = new Map([
+    ...perConfigDomainsFor(config),
+    ...addableSegmentDomains(config),
+  ]);
   return Object.values(config.actions).flatMap((a) =>
     actionKeySpecs(a, seeds, perConfigDomains),
   );

package/src/daemon/verbs/index.ts

@@ -37,6 +37,8 @@ import {
   isGlobalsField,
   loadConfigOverrides,
   loadOverrides,
+  redoLastOverride,
+  undoLastOverride,
   writeConfigOverride,
 } from "../config-overrides-store";
 import { configOverridesPath } from "../paths";
@@ -49,6 +51,7 @@ import {
   VERB_DISPATCH,
   VERB_OPEN_VSCODE,
   VERB_LOAD_CONFIG,
+  VERB_REDO,
   VERB_RESET_CONFIG,
   VERB_SET_CONFIG,
   VERB_SET_STATE,
@@ -57,6 +60,7 @@ import {
   VERB_SHOW_CONFIG_ERROR,
   VERB_SHOW_CONFIG_WARNING,
   VERB_TOOLBAR_TOGGLE,
+  VERB_UNDO,
 } from "../../click/wire";
 
 export interface VerbContext {
@@ -489,6 +493,35 @@ const applyLayoutOp: VerbHandler = (rawValue, ctx) => {
   );
 };
 
+// [LAW:one-source-of-truth] `reset`'s fine-grained sibling: step the ONE
+// global history over the overrides layer back one entry. No key, no value —
+// the history store (config-overrides-store.ts) owns which entry moves and
+// what it restores; this handler is pure plumbing between the wire and it.
+// [LAW:no-silent-failure] An empty stack is a loud BAD_REQUEST (dispatch's
+// aggregator turns it into a transient click.error), never a silent no-op —
+// the ticket's own done-gate.
+const undoConfig: VerbHandler = (value, ctx) => {
+  const [sessionId = ""] = decodeWire(() => decodeSegments(value));
+  const sid = requireSessionId(sessionId);
+  const entry = undoLastOverride(configOverridesPath(), ctx.dlog);
+  if (entry === null) {
+    throw new BadVerbArgs("undo: history is empty, nothing to undo");
+  }
+  ctx.dlog("info", `undo: ${entry.key} (session=${sid})`);
+};
+
+// [LAW:one-source-of-truth] undo's mirror — steps the same global history
+// forward one entry.
+const redoConfig: VerbHandler = (value, ctx) => {
+  const [sessionId = ""] = decodeWire(() => decodeSegments(value));
+  const sid = requireSessionId(sessionId);
+  const entry = redoLastOverride(configOverridesPath(), ctx.dlog);
+  if (entry === null) {
+    throw new BadVerbArgs("redo: nothing to redo");
+  }
+  ctx.dlog("info", `redo: ${entry.key} (session=${sid})`);
+};
+
 // ─── Registry ───────────────────────────────────────────────────────────────
 
 // [LAW:one-source-of-truth] The LEAF verbs — every click effect that does real
@@ -551,6 +584,8 @@ const LEAF_VERBS = new Map<string, VerbHandler>([
   [VERB_STEP_CONFIG, stepConfig],
   [VERB_RESET_CONFIG, resetConfig],
   [VERB_APPLY_LAYOUT_OP, applyLayoutOp],
+  [VERB_UNDO, undoConfig],
+  [VERB_REDO, redoConfig],
   [VERB_SHOW_CONFIG_ERROR, showConfigError],
   [VERB_SHOW_CONFIG_WARNING, showConfigWarning],
   [VERB_TOOLBAR_TOGGLE, toolbarToggle],
@@ -583,8 +618,9 @@ const dispatch: VerbHandler = (rawValue, ctx) => {
   for (const { verb, value } of parseEffects(rawValue)) {
     // Extract session ID from the first session-bearing effect for error display.
     // set-state, step-state, set-config, step-config, reset-config,
-    // apply-layout-op, and toolbar-toggle all carry the session id as their
-    // first segment, so a failing step surfaces in the bar like any other.
+    // apply-layout-op, undo, redo, and toolbar-toggle all carry the session id
+    // as their first segment, so a failing step surfaces in the bar like any
+    // other.
     if (
       !sessionId &&
       (verb === VERB_SET_STATE ||
@@ -593,6 +629,8 @@ const dispatch: VerbHandler = (rawValue, ctx) => {
         verb === VERB_STEP_CONFIG ||
         verb === VERB_RESET_CONFIG ||
         verb === VERB_APPLY_LAYOUT_OP ||
+        verb === VERB_UNDO ||
+        verb === VERB_REDO ||
         verb === VERB_TOOLBAR_TOGGLE)
     ) {
       const parts = decodeSegments(value);

package/src/dsl/render.ts

@@ -23,6 +23,7 @@ import type {
 import { HUE_STEP_VAR } from "../config/dsl-types.js";
 import { perConfigDomainsFor } from "../config/option-domain.js";
 import { PRESET_FLOOR, presetNames, presetRoot } from "../config/presets.js";
+import { addableSegmentDomains } from "../config/edit-chrome.js";
 import type { VariableStore } from "../var-system/store.js";
 import type { SourceRegistry } from "../var-system/sources.js";
 import {
@@ -340,7 +341,15 @@ export function registerDslConfig(
   // one source.
   const lookNames = Object.keys(config.looks);
   const presetOptions = presetNames(config.presets);
-  const perConfigDomains = perConfigDomainsFor(config);
+  // [LAW:one-source-of-truth] The "addable segment" per-preset domains merge
+  // in here — the SAME map config-validators.ts's deriveConfigActionValidators
+  // merges — so a synthesized `insertSegmentFrom` action's rendered options
+  // and its derived click gate resolve from one source, never two
+  // independently-computed sets.
+  const perConfigDomains = new Map([
+    ...perConfigDomainsFor(config),
+    ...addableSegmentDomains(config),
+  ]);
   const engine = createCcCandybarEngine(
     {
       ...actionFuncs(actionRuntime),

package/src/render/action.ts

@@ -34,11 +34,13 @@ import {
   VERB_APPLY_LAYOUT_OP,
   VERB_COPY,
   VERB_OPEN_VSCODE,
+  VERB_REDO,
   VERB_RESET_CONFIG,
   VERB_SET_CONFIG,
   VERB_SET_STATE,
   VERB_STEP_CONFIG,
   VERB_STEP_STATE,
+  VERB_UNDO,
   type Effect,
 } from "../click/wire.js";
 
@@ -142,7 +144,29 @@ export type CompiledActionDecl =
   // arms. Fully literal at compile time (the op IS the declaration — no
   // template-bound option, unlike persist-option), so `op` is precomputed
   // here rather than reconstructed from raw fields at every realize() call.
-  | { readonly kind: "layout-op"; readonly key: string; readonly op: LayoutOp };
+  | { readonly kind: "layout-op"; readonly key: string; readonly op: LayoutOp }
+  // [LAW:one-source-of-truth] brandon-layout-edit-2gc.3's domain-sourced
+  // sibling of layout-op: `anchor`/`relation` are fixed at compile time (the
+  // POSITION is author-time data) but the segment name comes from the
+  // template's bound option — the option-picking shape `persist-option`
+  // already has, minus the value being written VERBATIM. `requireOptionKind`
+  // (render/picker.ts) admits this kind alongside set-option/persist-option
+  // so a `{{ menu }}`/`{{ picker }}` can drive it with zero picker changes;
+  // only the WRITE (realize(), below) differs — it encodes the picked option
+  // into a LayoutOp instead of persisting it as-is.
+  | {
+      readonly kind: "layout-op-option";
+      readonly key: string;
+      readonly anchor: string;
+      readonly relation: "before" | "after";
+      readonly options: readonly string[];
+    }
+  // [LAW:one-source-of-truth] brandon-layout-edit-2gc.2's global history
+  // step over the overrides layer — `reset`'s fine-grained sibling. No key:
+  // there is nothing to carry, since the history stack (not this action) is
+  // what decides which entry moves.
+  | { readonly kind: "undo" }
+  | { readonly kind: "redo" };
 
 export type CompiledActions = ReadonlyMap<string, CompiledActionDecl>;
 
@@ -320,6 +344,17 @@ function compileAction(
         },
       };
     }
+    if ("insertSegmentFrom" in action) {
+      return {
+        kind: "layout-op-option",
+        key: action.persist,
+        anchor: action.anchor,
+        relation: action.relation,
+        options: [
+          ...resolveOptionDomain(action.insertSegmentFrom, perConfigDomains),
+        ],
+      };
+    }
     return {
       kind: "persist-bounded",
       key: action.persist,
@@ -338,7 +373,10 @@ function compileAction(
       target: parseActionTemplate(parse, action.open, name),
     };
   }
-  return { kind: "reset", key: action.reset };
+  if ("reset" in action) {
+    return { kind: "reset", key: action.reset };
+  }
+  return "undo" in action ? { kind: "undo" } : { kind: "redo" };
 }
 
 function parseActionTemplate(
@@ -548,6 +586,20 @@ function realize(
         effect: { verb: VERB_RESET_CONFIG, args: [sessionId, c.key] },
         active: false,
       };
+    // [LAW:one-source-of-truth] No key to carry — the click just says "step
+    // the history", and which entry moves is entirely server-side state
+    // (never wire input, so there is nothing here to gate). Never "active":
+    // a history step is a one-shot trigger, not a current-selection toggle.
+    case "undo":
+      return {
+        effect: { verb: VERB_UNDO, args: [sessionId] },
+        active: false,
+      };
+    case "redo":
+      return {
+        effect: { verb: VERB_REDO, args: [sessionId] },
+        active: false,
+      };
     // [LAW:one-source-of-truth] The op is fixed at compile time (see
     // compileAction) — the click just delivers it. `apply-layout-op`'s
     // handler does read-current-append-write (see verbs/index.ts), unlike
@@ -562,6 +614,28 @@ function realize(
         },
         active: false,
       };
+    // [LAW:one-source-of-truth] The picked option (boundValue ?? display — the
+    // SAME resolution persist-option uses) becomes the op's `segment`; anchor/
+    // relation are the compiled literals. Same wire shape a literal layout-op
+    // emits, so the daemon's apply-layout-op handler and undo/redo need no
+    // knowledge of where the segment name came from. Never "active": a
+    // structural edit is a one-shot trigger, not a current-selection toggle.
+    case "layout-op-option": {
+      const segment = boundValue ?? display;
+      const op: LayoutOp = {
+        op: "insert",
+        segment,
+        anchor: c.anchor,
+        relation: c.relation,
+      };
+      return {
+        effect: {
+          verb: VERB_APPLY_LAYOUT_OP,
+          args: [sessionId, c.key, encodeLayoutOp(op)],
+        },
+        active: false,
+      };
+    }
   }
 }