Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

118 KB
Raw Blame
import { emitSpriteChanged } from './events.js';
/**
 * Sprites — walk-animation workflow orchestration (issue #2897, phase 3).
 *
 * Per-direction lifecycle on top of the locked reference set (#2896):
 * generate ONE grok image_to_video walk clip per direction (user-triggered,
 * cloud lane), then the completion hook runs the fully deterministic Node
 * postprocess (walkPostprocess.js) into a candidate run. The user reviews,
 * optionally loop-trims, and approves per direction; when all 8 directions
 * are approved the finalized walk-set manifest freezes the set.
 *
 * Disk layout (vendor-neutral runs/ tree; the provider is a run-record field):
 *   runs/walk-<direction>-<runId8>/animation-run.json + generated/…
 *   walk/<id>-walk-selection-v1.json, walk/<id>-walk-set-v1.json
 *   walk/trims/<slug>-vNNN-{strip.png,.gif,.json}
 *
 * A finalized walk set 409s generation/approval/postprocess until deliberately
 * reopened. Revising a directional anchor also removes the approval for the
 * walk conditioned on that stale anchor while preserving its rendered run.
 */

import { join } from 'path';
import { readdir, stat } from 'fs/promises';
import { randomUUID } from 'crypto';
import {
  ensureDir, atomicWrite, readJSONFile, pathExists, sha256File, rmGuarded,
} from '../../lib/fileUtils.js';
import { ServerError } from '../../lib/errorHandler.js';
import { withBackupAssetPublication } from '../../lib/backupSnapshotBoundary.js';
import { executeTuiRun } from '../tuiPromptRunner.js';
import { GROK_TUI_ID } from '../../lib/grok.js';
import { getSettings } from '../settings.js';
import { getRecord, updateRecord } from './records.js';
import {
  spriteDir, resolveSpriteAssetPath, toRecordRelativeAssetPath, altRunLayoutPath,
  runDirOfPath, resolveDriftTolerantRel, isSourcePipelinePath, SOURCE_CLIP_NAME,
  rawFramesRelOf, RAW_FRAME_NAME, runRelPath, RUN_RECORD_NAME,
} from './paths.js';
import {
  requireCharacter, loadManifest,
  assertReferenceAnchorUnlockable, unlockReferenceAnchor,
  assertReferenceMainUnlockable, unlockReferenceMain,
  assertReferenceTurnaroundUnlockable, unlockReferenceTurnaround,
} from './reference.js';
import { SPRITE_DIRECTIONS, anchorIdForDirection, buildWalkVideoPrompt } from './prompts.js';
import {
  prepareWalkAnchorChromaInput, runWalkPostprocess, extractVideoFrames,
  WALK_CELL_SIZE, WALK_FPS, MAX_SOURCE_SECONDS,
  WALK_DEFAULT_FRAME_COUNT, WALK_DEFAULT_FPS,
  WALK_MIN_FRAME_COUNT, WALK_MAX_FRAME_COUNT, WALK_MIN_FPS, WALK_MAX_FPS,
  clampFrameCount, clampFps,
} from './walkPostprocess.js';
import {
  WALK_TRACK, resolveAnimationTarget, withTrackTarget, targetDrift, describeTargetSource,
} from './animationTargets.js';
import { verifyPackagedFrames } from './walkFrames.js';
import { probeVideoDuration } from '../../lib/ffmpeg.js';
import { resolveGrokDuration } from '../../lib/grokVideoClip.js';
import {
  withAnimationWriteTail, resolveChromaKey, lockedAnchorFor,
  GROK_TUI_IDLE_MS, GROK_TUI_TIMEOUT_MS, grokTuiProvider, buildGrokI2vTask,
  resolveAnimationProvider, isLocalProviderRun, runCreatedAtMs,
} from './animationWorkflow.js';
import {
  SCANNER_TRACK, sourceReferenceFor,
} from './animationTracks.js';
import {
  planLocalAnimationRender, enqueueLocalAnimationRender, localRenderManifest,
  normalizeStaleAnimationRun,
} from './localAnimationRender.js';
// #3152 — the anchor-invalidation sweep below must cover a USER-DEFINED track too:
// a stored row seeded from a directional anchor holds approvals descended from the
// same reference, and sweeping only the compiled table would leave them standing
// after an anchor revision (the atlas would then compile frames drawn from an
// image that no longer exists — exactly what this sweep exists to prevent).
import { getEffectiveAnimationTracks } from './animationTrackStore.js';
import {
  invalidateTrackDirectionForAnchorRevision, invalidateTrackForTurnaroundRevision,
} from './animationTrackWorkflow.js';

// grok's walk render runs as an OBSERVABLE TUI session (issue: user wants to
// watch/course-correct grok in the Shell) rather than a headless mediaJobQueue
// spawn. The thresholds and their rationale live in animationWorkflow.js, shared
// with every other animation track, so raising the lull tolerance can't fix one
// render path and leave the rest reaping early. Local aliases keep the ~6 call
// sites (including RENDER_STALE_MS below) reading as walk's own.
const WALK_TUI_IDLE_MS = GROK_TUI_IDLE_MS;
const WALK_TUI_TIMEOUT_MS = GROK_TUI_TIMEOUT_MS;

const selectionRelPath = (id) => `walk/${id}-walk-selection-v1.json`;
// Exported: atlas.js (phase 4) reads the finalized walk set as compile input.
export const walkSetRelPath = (id) => `walk/${id}-walk-set-v1.json`;
// Native generations store one run per directory under a VENDOR-NEUTRAL `runs/`
// tree — the provider (grok, or a future agent service) is recorded as the run
// record's `provider` field, never encoded in the path. Migration 202 renamed
// the historical `grok/<runId>/` layout into this one; the reader still scans
// `grok/` too (RUN_SCAN_DIRS) for pre-migration installs and forks, and
// RUN_DIR_MATCH (paths.js) still accepts both prefixes.
// The two on-disk homes a run can be found in: the neutral `runs/` layout (all
// new generations, post-migration) and `grok/` — both a straggler on an
// un-migrated install/fork AND where a source-pipeline import lands whenever its
// own manifests declare that layout (migration 202 is one-shot per install, so it
// never re-runs for an import that arrives afterwards). Approved runs resolve
// through their selection entry, so the scan covers unapproved candidates plus
// any run whose entry has been dropped by an unlock/reopen.
const RUN_SCAN_DIRS = ['runs', 'grok'];

// Serialize walk-state read-modify-writes per record (run records, the
// selection file, the walk set, and trim versioning share one lifecycle) —
// same convention as reference.js's manifestWriteTail. Exported for
// walkTrims.js so its scan-then-write version claim can't race an attach or
// a concurrent trim.
const walkWriteTail = (recordId, fn) => withAnimationWriteTail(recordId, fn);
export const withWalkWriteTail = walkWriteTail;

async function loadWalkSet(recordId) {
  return readJSONFile(join(spriteDir(recordId), walkSetRelPath(recordId)), null, { strict: true });
}

// A phase-1 imported walk set (#2895) is copied verbatim from the source
// pipeline: every embedded path stays anchored at the SOURCE repo root
// (paths.js#isSourcePipelinePath) and its packaged per-frame PNGs were never
// imported.
/**
 * The directions of a walk set that are STILL packaged by the source pipeline —
 * their approved entry names the source tree, so their per-frame PNGs are not on
 * disk here and only the source pipeline could have produced them.
 *
 * This is the precise, per-direction form of "imported" (#2993). Re-deriving a
 * direction inside PortOS rewrites its entry through `approveWalkDirection`,
 * which stores record-relative paths — so a re-derived direction drops out of
 * this list and the set converges on compilable as the user works through it.
 * A blanket set-level refusal could not express that partial state.
 */
export function importedWalkDirections(walkSet) {
  return Object.entries(walkSet?.directions || {})
    .filter(([, entry]) => isSourcePipelinePath(entry?.runPath) || isSourcePipelinePath(entry?.runManifest))
    .map(([direction]) => direction);
}

// Whether a walk set carries ANY un-re-derived source-pipeline provenance:
// either the set-level selection pointer or at least one direction entry. Single
// source of truth for the marker so its call sites (atlas.js's recompile guard,
// the un-finalize evidence gate below, and the client via the getWalkState flag)
// can't drift.
export const isImportedWalkSet = (walkSet) => (
  isSourcePipelinePath(walkSet?.selectionPath) || importedWalkDirections(walkSet).length > 0
);

async function loadSelection(recordId) {
  return readJSONFile(join(spriteDir(recordId), selectionRelPath(recordId)), null, { strict: true });
}

function seedSelection(recordId) {
  return {
    schemaVersion: 1,
    kind: 'reviewed-directional-walk-selection',
    characterId: recordId,
    status: 'in-progress',
    // Per-track cycle targets (#2985), keyed by animation track — `walk` is the
    // only member today. Seeded EMPTY and filled lazily on first resolve so a
    // selection record stays byte-identical to what an older peer expects until
    // there is an actual target to pin.
    animationTargets: {},
    directions: {},
  };
}

// Read a run record by its directory (record-relative), so `grok/<id>/` and
// the importer's `runs/<id>/` share one reader.
async function loadRunRecordAt(recordId, runDirRel) {
  return readJSONFile(join(spriteDir(recordId), runDirRel, RUN_RECORD_NAME), null, { strict: true });
}

async function loadRunRecord(recordId, runId) {
  // Runs PortOS itself just wrote (generate → attach) always live under the
  // neutral runs/ layout, so this straight lookup is exact for that path.
  // Callers that may act on a run PortOS did not create (rerun, approve) go
  // through `resolveRunById` instead — see there.
  return loadRunRecordAt(recordId, runRelPath(runId));
}

/**
 * Locate a run under EITHER on-disk layout, returning the record together with
 * the directory it ACTUALLY lives in.
 *
 * Migration 202 renamed pre-existing native `grok/<run-id>/` runs into the
 * neutral `runs/` tree, but it is a one-shot per install: a source-pipeline
 * import landing afterwards writes its runs wherever its own (hash-pinned)
 * manifests declare — commonly `grok/<run-id>/` — so `runs/`-only resolution
 * reports RUN_NOT_FOUND for a run that is right there on disk (#2993). Probing
 * both layouts is only half the fix; the resolved directory has to be threaded
 * into every subsequent write, which is why this returns it rather than just the
 * record. That is what keeps a re-derive from splitting one run across two
 * directories — the hazard the old `runs/`-only rule avoided by refusing outright.
 */
async function resolveRunAt(recordId, runDirRel) {
  const candidates = [runDirRel, altRunLayoutPath(runDirRel)].filter(Boolean);
  for (const rel of candidates) {
    // eslint-disable-next-line no-await-in-loop -- ordered preference: stop at the layout that exists
    const run = await loadRunRecordAt(recordId, rel);
    if (run) return { run, runDirRel: rel };
  }
  return null;
}

const resolveRunById = (recordId, runId) => resolveRunAt(recordId, runRelPath(runId));

// The shared `runs/` tree now holds named tracks as well as walk. Legacy walk
// records predate the field, so an absent track remains walk-compatible; a
// declared non-walk track must never surface through, or be mutated by, the
// walk endpoints.
const isWalkRun = (run) => !run?.track || run.track === WALK_TRACK;
async function resolveWalkRunById(recordId, runId) {
  const found = await resolveRunById(recordId, runId);
  return isWalkRun(found?.run) ? found : null;
}

async function saveRunRecordAt(recordId, run, runDirRel) {
  const dir = join(spriteDir(recordId), runDirRel);
  await ensureDir(dir);
  await atomicWrite(join(dir, RUN_RECORD_NAME), run);
  emitSpriteChanged(recordId);
}

const saveRunRecord = (recordId, run) => saveRunRecordAt(recordId, run, runRelPath(run.id));

// The record-relative path a selection / walk-set entry names its run by —
// `runPath` first, then the manifest it declares. An imagegen redraw entry
// resolves to a version directory rather than a run directory, which is what
// `runDirOfPath` returning null downstream distinguishes.
const entryLayoutPath = (recordId, entry) => toRecordRelativeAssetPath(recordId, entry?.runPath)
  || toRecordRelativeAssetPath(recordId, entry?.runManifest);

// The run directory a loaded run record implies, for a caller that has the
// record but not the directory it came from. Every candidate field is
// record-relative by the time a read-path consumer sees it (normalizeRunAssetPaths
// / normalizeStripPreview), and any one of them pins the run dir.
const runDirRelOf = (run) => runDirOfPath(run?.sourceVideoPath)
  || runDirOfPath(run?.postprocessManifest)
  || runDirOfPath(run?.stripPreview?.stripPath);

/**
 * The record-relative i2v clip a run can be re-derived from, or null when none
 * is on disk.
 *
 * Two candidate names, each resolved drift-tolerantly (paths.js — the declared
 * spelling or its run-layout twin): the clip the record declares, re-anchored
 * since an imported record declares it against the SOURCE repo root, then the
 * conventional `<run-dir>/generated/` name for a record that names none at all.
 * Probed together rather than in sequence — a run whose clip is genuinely gone
 * is re-checked on every poll, so the miss case must not cost a round trip per
 * candidate.
 */
async function resolveRunClipRel(recordId, run, runDirRel) {
  const dir = spriteDir(recordId);
  // Deduped: a native run's declared clip IS the conventional path, and probing
  // it twice would double the stats on the healthy majority.
  const candidates = [...new Set([
    toRecordRelativeAssetPath(recordId, run?.sourceVideoPath),
    runDirRel ? `${runDirRel}/generated/${SOURCE_CLIP_NAME}` : null,
  ].filter(Boolean))];
  const resolved = await Promise.all(candidates.map((rel) => resolveDriftTolerantRel(dir, rel)));
  return resolved.find(Boolean) || null;
}

// What a frozen set says when a mutating op reaches it. A factory rather than a
// literal because two paths raise it: this guard, and the shared re-derive gate
// below (which resolves the frozen set from state it already loaded rather than
// re-reading the file). One producer, so the two can't drift apart.
const walkSetFinalError = () => new ServerError('Walk set is finalized — revisions require a new character version', { status: 409, code: 'WALK_SET_FINAL' });

async function requireUnfinalized(recordId) {
  if (await loadWalkSet(recordId)) throw walkSetFinalError();
}

// A 'rendering' run's status is flipped to a terminal state by attachTuiWalkResult
// when executeTuiRun settles — including on grok's 30-min hard timeout. So a run
// still 'rendering' well past that cap can only be stranded: the server process
// died mid-render (the in-memory PTY run and its completion handler went with it).
// Present it as an error at read time — never persisted — so the UI stops polling
// forever, surfaces regenerate, and the in-flight guard in startWalkGeneration
// stops treating it as live. RENDER_STALE_MS is the hard cap plus a buffer.
// Which lane a run came from, for logs shared by both.
const runProviderLabel = (run) => (isLocalProviderRun(run) ? 'local' : 'grok-tui');
const STALE_RENDER_ERROR = 'Walk render was interrupted (server restart or timeout) — regenerate to retry.';
// Both lanes' staleness rules live in one place (localAnimationRender.js) so the
// walk and non-walk tracks cannot drift on when a render counts as stranded —
// only the user-facing wording differs.
const normalizeStaleRendering = (run) => normalizeStaleAnimationRun(run, STALE_RENDER_ERROR);

// PortOS's own postprocess stamps `stripPreview.stripPath` record-relative
// (walkPostprocess.js). The imported source pipeline stamps the same field
// as `stripPreview.path`, anchored at ITS repo root — the importer copies
// manifests byte-for-byte (hashes are pinned and verified against the
// source, so importer.js never rewrites them), so the mismatch is fixed up
// here, in memory, at read time instead. Never written back to disk.
function normalizeStripPreview(recordId, run) {
  if (!run?.stripPreview) return run;
  const patch = {};

  const raw = run.stripPreview.stripPath ?? run.stripPreview.path;
  const stripPath = toRecordRelativeAssetPath(recordId, raw);
  if (stripPath) patch.stripPath = stripPath;

  // Collapse the strip's cache-busting token to ONE field the client reads
  // (#3020). The packer rewrites a strip in place at a stable path, so the URL
  // needs a token that changes with the bytes — but the two run flavors can
  // afford different tokens: a native run persists the real content hash, while
  // a synthesized redraw run has no hash in its manifest and sets `stripVersion`
  // itself from an mtime-size stat. Deriving the native case HERE — the one
  // choke point every run reader passes through — means the client never learns
  // that difference, and a strip consumer cannot silently paint a stale image by
  // forgetting to apply the precedence rule by hand. (That is not hypothetical:
  // the first cut of this fix resolved it client-side and the Loop Trimmer read
  // a flattened object that never carried either field, so its half was inert.)
  //
  // Truncated to 12 chars because a sha256 is 64 and only needs to be unique
  // across one file's own history; `stripVersion` is set verbatim by its
  // producer, since a composite token can't be cut without losing a component.
  if (!run.stripPreview.stripVersion && typeof run.stripPreview.stripSha256 === 'string' && run.stripPreview.stripSha256) {
    patch.stripVersion = run.stripPreview.stripSha256.slice(0, 12);
  }

  if (!Object.keys(patch).length) return run;
  return { ...run, stripPreview: { ...run.stripPreview, ...patch } };
}

// Same fixup as normalizeStripPreview, for the OTHER repo-anchored path fields
// an imported run record carries. `postprocessManifest` names the packaged
// manifest as `art-source/sprites/<id>/runs/<run-id>/generated/…json`, and
// `sourceVideoPath` names the run's i2v clip the same way. Left raw,
// `resolveSpriteAssetPath` appends the value whole to the record dir —
// producing `data/sprites/<id>/art-source/sprites/<id>/…`, which is still
// INSIDE the record (so the traversal gate passes) but does not exist. That
// 409'd every loop-trim save on an imported record (#2978), would have failed
// approveRun the same way, and would leave an imported run's freshly-imported
// clip (#2984) unfindable. Normalizing here — the one choke point every run
// reader passes through — fixes every consumer at once. In memory only, never
// written back to the hash-pinned record.
// A path toRecordRelativeAssetPath can't re-anchor (it returns null for a
// repo-anchored path belonging to some OTHER record, e.g. pipeline provenance)
// is left untouched rather than blanked, so a genuinely foreign pointer stays
// readable instead of being rewritten into a bogus record-relative one.
const REPO_ANCHORED_RUN_FIELDS = ['postprocessManifest', 'sourceVideoPath'];

function normalizeRunAssetPaths(recordId, run) {
  let out = run;
  for (const field of REPO_ANCHORED_RUN_FIELDS) {
    const rel = out[field] && toRecordRelativeAssetPath(recordId, out[field]);
    if (rel && rel !== out[field]) out = { ...out, [field]: rel };
  }
  // A run whose packaged manifest is STILL named against the source repo was
  // packaged there, which means its per-frame images were never imported (the
  // importer skips frames/). Stamped here because this is where that fact is
  // still visible — one line up it has been re-anchored away — and it costs no
  // I/O, unlike stat-ing every frame on a read the client polls. The client gates
  // Approve on it: approving such a run 409s RUN_FRAMES_MISSING, and the flag
  // clears by itself the moment a reprocess rewrites the manifest record-relative.
  return isSourcePipelinePath(run.postprocessManifest) ? { ...out, importedPackaging: true } : out;
}

// A candidate/approved run's stripPreview names a packed strip PNG on disk. If
// that file has since gone missing — a botched migration dropped it, a manual
// cleanup nuked it — the run record still advertises the path, so the native
// render path (unlike loadRedrawRun, which returns null on a missing strip)
// hands the client a healthy-looking run and StripLoop paints a blank
// background-image with no signal that anything is wrong. That's exactly how the
// pioneer north/west strips vanished silently. Flag it at read time — never
// persisted — so the card renders an explicit "strip missing" indicator instead
// of a mystery blank, and drop the dangling stripPath so StripLoop and the trim
// button don't try to render it. A run with no stripPreview
// (rendering/postprocessing/pre-package) is untouched.
//
// Deliberately does NOT flip status to 'error': the run's status is orthogonal
// to whether its strip survived on disk. Overloading 'error' here mis-drives the
// UI — DirectionCard's error block offers "Retry postprocess", which 409s
// (WALK_SET_FINAL / RUN_APPROVED) for exactly the finalized/approved directions
// this guard most often fires on (the pioneer north/west population), and pairs a
// red error with the green "approved" badge. Keeping the status lets the client
// route recovery correctly off `stripMissing` + the direction's approved/finalized
// state (regenerate an unapproved candidate; unlock the set for a finalized one).
//
// Resolved drift-tolerantly, like the source clip below: an imported manifest can
// name the strip under one run layout for a file stored under the other, and both
// spellings denote the same PNG (paths.js#resolveDriftTolerantRel). Healing that
// here — rather than only for the clip — is what keeps a drifted import from
// badging "strip missing" over an intact strip, losing its loop preview, its trim
// link, and its contribution to the set's packaged geometry.
async function normalizeMissingStrip(recordId, run) {
  const stripPath = run?.stripPreview?.stripPath;
  if (!stripPath) return run;
  const found = await resolveDriftTolerantRel(spriteDir(recordId), stripPath);
  if (found === stripPath) return run;
  if (found) return { ...run, stripPreview: { ...run.stripPreview, stripPath: found } };
  const { stripPath: _dropped, ...stripPreviewRest } = run.stripPreview;
  return { ...run, stripMissing: true, stripPreview: stripPreviewRest };
}

/**
 * Fold a resolved i2v source clip onto a run, so "can this direction be
 * re-derived?" is answered by evidence rather than by whether the record happens
 * to name a clip (#2993).
 *
 * Three distinct outcomes, deliberately not collapsed: the clip is found (and
 * `sourceVideoPath` is rewritten to where it actually is, healing a layout-drift
 * mismatch for the player, the trimmer, and the re-derive); the record declares a
 * clip that is NOT on disk, or names none while its run directory has none
 * either (`sourceClipMissing: true`, the same read-time flag shape as
 * `stripMissing`); or the run is an imagegen redraw cycle, which never had an
 * i2v clip and is left untouched.
 *
 * The declared path is kept alongside the flag rather than dropped — it is the
 * record's own provenance, and consumers gate on the flag. In memory only; the
 * hash-pinned record on disk is never rewritten here.
 */
function applySourceClip(run, clipRel, runDirRel) {
  if (clipRel) return clipRel === run.sourceVideoPath ? run : { ...run, sourceVideoPath: clipRel };
  if (!runDirRel && !run?.sourceVideoPath) return run;
  return { ...run, sourceClipMissing: true };
}

// PortOS stamps `id` on every run record it writes; imported source-pipeline
// records don't carry one at all (see importer.test.js's fixtures). The run
// DIRECTORY is the run id under both layouts, so fall back to it. Two
// consumers break on an undefined id, which is why this isn't cosmetic:
//   - WalkWorkflow.jsx's `runs.find((r) => r.id === sel.runId)` — an imported
//     entry's `sel.runId` is ALSO undefined, so `undefined === undefined`
//     matches the first idless run in the list whatever its direction, and
//     that run gets pinned to the wrong direction's card.
//   - the `resolvedRunIds` dedup below, where every idless run collapses onto
//     the single `undefined` key.
// In-memory only, like normalizeStripPreview — never written back to disk.
function normalizeRunRecord(recordId, run, runDirRel) {
  const withId = run.id ? run : { ...run, id: runDirRel.split('/')[1] };
  return normalizeRunAssetPaths(recordId, normalizeStripPreview(recordId, withId));
}

// Strip candidates on an imported redraw manifest, in preference order. The
// clean straight-alpha derivative comes first so the preview matches native
// runs (which are always transparent); the keyed matte is the last resort
// because it renders with the chroma background baked in.
const REDRAW_STRIP_FIELDS = ['stripAlpha', 'stripAlphaOriginal', 'stripKeyed'];

/**
 * Synthesize a preview-only run object for a direction approved from an
 * imagegen **redraw** manifest (issue #2924) rather than a grok walk run.
 *
 * The source pipeline's video-first redraw path (e.g. pioneer's east, packaged
 * as `imagegen/vN/…-manifest.json` with a 12-frame cycle) predates PortOS's own
 * grok-direct walk workflow, so the selection's `runPath` points at an
 * `imagegen/` directory with no matching `grok/` run record — `getWalkState`
 * surfaced nothing and the direction rendered its "approved" badge with no
 * loop preview. Rather than model a second full run-record type, read the
 * redraw manifest's `cycle` block and shape the minimum the UI needs. Returns
 * null when the manifest isn't a redraw cycle or its strip is missing on disk,
 * so a genuinely absent run stays absent instead of rendering a broken image.
 */
async function loadRedrawRun(recordId, direction, entry) {
  const manifestRel = toRecordRelativeAssetPath(recordId, entry.runManifest);
  if (!manifestRel) return null;
  // Read-only redraw projection; this fallback never enters a manifest write.
  const manifest = await readJSONFile(join(spriteDir(recordId), manifestRel), null);
  const cycle = manifest?.cycle;
  const frameCount = Number(cycle?.frameCount);
  if (!Number.isInteger(frameCount) || frameCount < 2) return null;

  // `stat` answers BOTH questions in one syscall — does the strip exist, and
  // what is its cache-busting token (#3020) — so this deliberately stats rather
  // than calling pathExists and then stat-ing the winner again. A redraw
  // manifest carries no strip hash, and this is a READ path (it runs on every
  // walk-state load, per direction), so hashing a multi-MB PNG here would be a
  // real per-request cost; mtime+size is the cheap stand-in that still changes
  // whenever a re-import rewrites the strip at its stable path. Size matters
  // alongside mtime because mtime resolution can be too coarse to catch a fast
  // rewrite — which is also why this token must never be truncated.
  let stripPath = null;
  let stripStat = null;
  for (const field of REDRAW_STRIP_FIELDS) {
    const rel = toRecordRelativeAssetPath(recordId, cycle[field]);
    // eslint-disable-next-line no-await-in-loop -- ordered preference: stop at the first strip that exists
    const found = rel && await stat(join(spriteDir(recordId), rel)).catch(() => null);
    if (found) {
      stripPath = rel;
      stripStat = found;
      break;
    }
  }
  if (!stripPath) return null;
  const stripVersion = `${Math.round(stripStat.mtimeMs)}-${stripStat.size}`;

  const cellSize = Number(manifest.cellSize) > 0 ? Number(manifest.cellSize) : WALK_CELL_SIZE;
  const fps = Number(cycle.referenceFps) > 0 ? Number(cycle.referenceFps) : WALK_FPS;
  return {
    schemaVersion: 1,
    kind: 'imported-redraw-walk-cycle',
    status: 'approved',
    // Imported entries carry no runId (it is an approveWalkDirection field),
    // so fall back to the manifest path — stable across reads and unique per
    // direction, which is all the client's list key needs.
    id: entry.runId || manifestRel,
    characterId: recordId,
    direction,
    createdAt: entry.approvedAt,
    // Deliberately NOT `postprocessManifest`: that field names a packaged grok
    // manifest (frames[] + alignment), and approve/trim resolve it as one. A
    // redraw manifest is a different schema, so it gets a distinct field.
    redrawManifest: manifestRel,
    // …which is also why the flag `normalizeRunAssetPaths` stamps off
    // `postprocessManifest` has to be set explicitly here: a synthesized redraw
    // run never passes through that normalizer, so without this it reads as
    // PortOS-owned once the frozen walk set is gone, and the client would offer a
    // Reopen the server refuses (a redraw entry names no run dir, so it has no
    // clip to re-derive from — this is the pioneer `east` shape).
    ...(isSourcePipelinePath(entry.runManifest) || isSourcePipelinePath(entry.runPath)
      ? { importedPackaging: true } : {}),
    stripPreview: {
      stripPath,
      stripVersion,
      frameCount,
      fps,
      cellWidth: cellSize,
      cellHeight: cellSize,
      row: 0,
      startColumn: 0,
    },
  };
}

/**
 * Resolve the run behind ONE selection/walk-set entry (issue #2928). The
 * entry names its own storage layout via `runPath`/`runManifest`, so this is
 * the single dispatch point every walk source routes through — adding a
 * fourth layout means another branch here, not another append-and-dedupe
 * block in `getWalkState`:
 *
 *   runs/<run-id>/  → PortOS's own generations + the importer's layout
 *   grok/<run-id>/  → legacy native generations (pre-migration-202 / forks)
 *   anything else   → an imagegen/vN redraw manifest (#2924), synthesized
 *
 * Every branch returns the same run-shaped object, so routes and the client
 * are layout-agnostic. Returns null when the entry names nothing readable.
 */
async function loadRunForEntry(recordId, direction, entry) {
  // The run directory names the layout; fall back to the manifest's own path
  // for an entry that carries only a manifest. An entry that declares one layout
  // for a run stored under the other still resolves (`resolveRunAt`), and the
  // directory it really came from is what the record is normalized against.
  const layoutPath = entryLayoutPath(recordId, entry);
  if (!layoutPath) return null;
  const runDirRel = runDirOfPath(layoutPath);
  if (runDirRel) {
    const found = await resolveRunAt(recordId, runDirRel);
    return found ? normalizeRunRecord(recordId, found.run, found.runDirRel) : null;
  }
  return loadRedrawRun(recordId, direction, entry);
}

/**
 * The clip behind ONE approved direction, or null when that direction has
 * nothing to re-derive from — the evidence the un-finalize gate below keys on.
 */
async function directionClipRel(recordId, entry) {
  const runDirRel = runDirOfPath(entryLayoutPath(recordId, entry));
  if (!runDirRel) return null;
  const found = await resolveRunAt(recordId, runDirRel);
  return resolveRunClipRel(recordId, found?.run, found?.runDirRel || runDirRel);
}

/**
 * The cycle geometry ONE run was packed at.
 *
 * Native runs stamp `frameCount`/`fps` on the run record; imported and redraw
 * runs only carry them inside `stripPreview`, and older native records predate
 * the run-level fields entirely — so every reader has to look through both, and
 * they do it through here rather than each re-deriving the fallback order.
 * Absent reports as null rather than a default, so "unknown" can't masquerade as
 * "packed at the default".
 */
const runCycleOf = (run) => ({
  frameCount: run?.frameCount ?? run?.stripPreview?.frameCount ?? null,
  fps: run?.fps ?? run?.stripPreview?.fps ?? null,
});

/**
 * The packed geometry of each direction that actually carries one, in ATLAS
 * order (SPRITE_DIRECTIONS) so "the first packaged direction" means the same
 * thing here as it does in the compiler's first-wins rule. An approved run wins
 * over a candidate for the same direction — approval is what the atlas compiles.
 *
 * A run the server flagged `stripMissing` contributes nothing: its packed strip
 * is gone from disk, so it can never compile, and letting it win the
 * first-packaged slot would derive the whole set's target from artwork that no
 * longer exists — badging every healthy direction as drifted against a dead one.
 * It is dropped AFTER the per-direction pick, not filtered out before it, so a
 * direction whose approved run lost its strip reports no geometry rather than
 * silently falling back to a superseded older candidate that will never be
 * frozen. (A stripMissing run keeps its `stripPreview`; only `stripPath` is
 * dropped, so the check has to name the flag.)
 */
function packagedCyclesFrom(runs, approvedDirections) {
  return SPRITE_DIRECTIONS.flatMap((direction) => {
    const forDirection = runs.filter((r) => r.direction === direction && r.stripPreview);
    const approvedRunId = approvedDirections?.[direction]?.runId;
    const run = forDirection.find((r) => r.id === approvedRunId)
      || forDirection.find((r) => r.status === 'approved')
      || forDirection.find((r) => r.status === 'candidate');
    if (!run || run.stripMissing) return [];
    return [{ direction, ...runCycleOf(run) }];
  });
}

/**
 * Resolve the walk track's pinned cycle target, plus the packaged directions
 * that disagree with it. Pure assembly over state the caller already loaded —
 * `getWalkState` stamps the result so the client never re-derives the precedence
 * chain (nor the provenance wording), and the queue-time guards compare against
 * it. `publishBinding.runtimeContract` is read defensively: it lands with #2982
 * and may be absent on this install, on an older peer's record, or on any record
 * with no binding at all.
 */
function resolveWalkTargetFor({ record, selection, packagedCycles }) {
  const target = resolveAnimationTarget({
    track: WALK_TRACK,
    runtimeContract: record?.publishBinding?.runtimeContract || null,
    animationTargets: selection?.animationTargets,
    packagedCycles,
  });
  const appId = record?.publishBinding?.appId || null;
  return {
    ...target,
    appId,
    // Stamped server-side rather than re-mapped in the client, so the label the
    // user reads and the 409 message they hit can never describe the same
    // target differently.
    sourceLabel: describeTargetSource(target, appId),
    drift: targetDrift(target, packagedCycles),
  };
}

/**
 * Walk-workflow view for the detail endpoint: every animation run (newest
 * first), the per-direction selection, the resolved cycle target, and the
 * finalized set when present.
 *
 * The selection (or the finalized walk set) is the index: each approved
 * direction resolves through `loadRunForEntry`, whatever layout it names.
 * The directory scan (RUN_SCAN_DIRS) then only has to cover runs that have NO
 * selection entry by definition — unapproved candidates and in-flight
 * generations, which PortOS writes under the neutral `runs/` tree.
 */
export async function getWalkState(recordId) {
  // The scan is independent of the index — start it first so the two reads
  // overlap, as they did when the scan WAS the entry point. Scan both the
  // neutral runs/ tree and the legacy grok/ tree, remembering each entry's
  // parent so the run loads from where it actually lives (a name could only
  // appear in one post-migration, but a fork/un-migrated install may still
  // have grok/).
  // Any directory, not just PortOS's own `walk-<direction>-<id8>` naming: the
  // source pipeline names its run directories freely (`run-1`, …), and those runs
  // are reachable ONLY through a selection entry — so the moment unlock or reopen
  // drops that entry (which is exactly when the user is about to re-derive them)
  // a name-prefix scan made them vanish from the workflow. A directory with no
  // `animation-run.json` loads as null and is filtered out below, so widening the
  // scan costs one absent-file read per non-run directory and admits nothing new.
  const scanPromise = Promise.all(RUN_SCAN_DIRS.map((base) => readdir(join(spriteDir(recordId), base), { withFileTypes: true })
    .then((entries) => entries.filter((e) => e.isDirectory() && !e.name.startsWith('.')).map((e) => ({ base, name: e.name })))
    .catch(() => []))) // dir absent → no runs there yet
    .then((lists) => lists.flat());
  // The record read (for the publish binding's runtime contract) is independent
  // of everything below — start it here so it overlaps the run resolution
  // instead of tacking a serial round-trip onto the end of this hot read.
  const recordPromise = getRecord(recordId);
  const [selection, walkSet] = await Promise.all([loadSelection(recordId), loadWalkSet(recordId)]);

  const approvedDirections = walkSet?.directions || selection?.directions || {};
  const entryRuns = (await Promise.all(
    Object.entries(approvedDirections)
      // Gate on `approved` because loadRedrawRun stamps that status
      // unconditionally — a rejected/pending entry must not surface as an
      // approved run next to live Generate/Approve buttons. A rejected grok
      // entry still surfaces via the scan below, with its own real status.
      //
      // Deliberately NOT gated on `entry.runId`: that field is written only by
      // approveWalkDirection, so IMPORTED entries — the whole population this
      // read path exists for — never carry one (importer.test.js's walk-set
      // fixtures are runId-less). Gating on it filtered out every imported
      // direction and made the layout dispatch below unreachable for them.
      .filter(([, entry]) => entry?.status === 'approved'
        && (entry.runPath || entry.runManifest))
      .map(([direction, entry]) => loadRunForEntry(recordId, direction, entry)),
  )).filter(Boolean);
  const resolvedRunIds = new Set(entryRuns.map((run) => run.id));

  const scannedRuns = (await Promise.all(
    (await scanPromise)
      .filter(({ name }) => !resolvedRunIds.has(name))
      .map(({ base, name }) => {
        const runDirRel = `${base}/${name}`;
        return loadRunRecordAt(recordId, runDirRel)
          .then((run) => (run ? normalizeRunRecord(recordId, run, runDirRel) : null));
      }),
  )).filter((run) => run && isWalkRun(run))
    // Second pass: a record whose own `id` differs from its directory name is
    // already covered by an entry that named it by id. Dedupe on id too, so a
    // run that somehow exists under both scan roots surfaces once.
    .filter((run, i, all) => !resolvedRunIds.has(run.id) && all.findIndex((r) => r.id === run.id) === i);

  const allRuns = (await Promise.all(
    [...entryRuns, ...scannedRuns]
      .map(normalizeStaleRendering)
      // The strip and the clip are different files, so probe them CONCURRENTLY
      // and merge — chaining would add a serialized stat per run to a read the
      // client polls every few seconds while a run packages.
      .map(async (run) => {
        // Resolved from the ORIGINAL run: normalizeMissingStrip may drop a
        // dangling stripPath, which is one of the fields the run directory is
        // inferred from.
        const runDirRel = runDirRelOf(run);
        const [stripped, clip] = await Promise.all([
          normalizeMissingStrip(recordId, run),
          resolveRunClipRel(recordId, run, runDirRel),
        ]);
        return applySourceClip(stripped, clip, runDirRel);
      }),
  )).sort((a, b) => runCreatedAtMs(b.createdAt) - runCreatedAtMs(a.createdAt));
  // Stamp the imported provenance so the client reads intent instead of
  // re-deriving the source-pipeline path convention itself — and stamp the
  // per-direction LIST alongside the boolean, because that is the precise fact:
  // a direction leaves the list the moment it is re-derived here, so the client
  // can gate each card (and name the blocking directions) on the same evidence
  // the compiler will apply, not on a set-wide approximation.
  // …and stamp WHY unlock is blocked (and whether it can be acknowledged past)
  // from the same resolver the unlock gate uses, so the client can offer the
  // escape rather than re-deriving the rule — or, as before #3043, render a dead
  // "no clips to re-derive" label with no action behind it.
  // The clip evidence is handed over rather than re-resolved: `allRuns` above
  // already stat'd every approved direction's clip, and re-deriving it here would
  // put ~16-32 redundant file ops on a read the client polls every 4s. What is
  // left is a single manifest read, and only on the blocked path.
  const clipByDirection = Object.fromEntries(allRuns
    .filter((run) => resolvedRunIds.has(run.id))
    .map((run) => [run.direction, Boolean(run.sourceVideoPath) && !run.sourceClipMissing]));
  // Reopen has the same informed escape as the set-wide unlock, but its scope is
  // one approved direction. Stamp the resolver's result on that direction's run
  // so the card never recreates the import/clip rule from a second reading. When
  // the frozen set is gone, the selection retains the source-path provenance the
  // resolver needs for the still-approved directions.
  const reopenState = walkSet || selection;
  const reopenByDirection = Object.fromEntries(await Promise.all(
    Object.keys(approvedDirections).map(async (direction) => [
      direction,
      await resolveUnlockBlock(recordId, reopenState, clipByDirection, [direction]),
    ]),
  ));
  const stampedRuns = allRuns.map((run) => (
    run.direction in reopenByDirection ? { ...run, reopen: reopenByDirection[run.direction] } : run
  ));
  const stampedWalkSet = walkSet ? {
    ...walkSet,
    imported: isImportedWalkSet(walkSet),
    importedDirections: importedWalkDirections(walkSet),
    unlock: await resolveUnlockBlock(
      recordId,
      walkSet,
      clipByDirection,
      importedWalkDirections(walkSet),
    ),
  } : null;
  const walkTarget = resolveWalkTargetFor({
    record: await recordPromise,
    selection,
    packagedCycles: packagedCyclesFrom(allRuns, approvedDirections),
  });
  return {
    runs: stampedRuns, selection, walkSet: stampedWalkSet, walkTarget,
  };
}

/**
 * Refuse a render/reprocess whose cycle geometry disagrees with the set's pinned
 * target (#2985). Rejecting rather than clamping is deliberate: a silent clamp
 * hands back an artifact the user did not ask for with no explanation, and the
 * atlas would still refuse to compile later. Enforced server-side because the
 * API is directly reachable — client gating alone would not hold.
 *
 * This moves the FIRST point of detection earlier; it does not move the
 * invariant. atlas.js keeps its own compile-time checks as the backstop for
 * imported and legacy sets that never passed this gate.
 */
function assertWalkTargetMatch(target, { frameCount, fps }, what = 'render') {
  if (frameCount === target.frameCount && fps === target.fps) return;
  throw new ServerError(
    `This walk set targets ${target.frameCount} frames @ ${target.fps}fps (${target.sourceLabel}). `
    + `Requested ${frameCount} frames @ ${fps}fps — change the set's cycle target, `
    + `or ${what} at ${target.frameCount} frames @ ${target.fps}fps.`,
    { status: 409, code: 'WALK_TARGET_MISMATCH' },
  );
}

/**
 * Resolve the geometry ONE render/reprocess will actually pack: an omitted knob
 * adopts the set target, a supplied one must agree with it, and resolving a
 * previously-implicit target records it. Shared by both queue paths so the
 * adopt/enforce/pin contract cannot drift between them.
 */
async function resolveRenderGeometry(recordId, { walkTarget, selection }, overrides = {}) {
  const frameCount = overrides.frameCount === undefined
    ? walkTarget.frameCount : clampFrameCount(overrides.frameCount);
  const fps = overrides.fps === undefined ? walkTarget.fps : clampFps(overrides.fps);
  assertWalkTargetMatch(walkTarget, { frameCount, fps });
  await pinDerivedWalkTarget(recordId, walkTarget, selection);
  return { frameCount, fps };
}

/**
 * Write an inferred ('derived') target back onto the selection the first time a
 * write path resolves one, so the value stops being implicit — the same
 * first-approved-direction rule the compiler applies, but recorded. Deliberately
 * lazy (write-on-first-resolve from a write path, never from a read) rather than
 * an eager backfill, so a record an older peer holds stays byte-identical until
 * PortOS actually acts on it. Never persists an 'app' target: the contract is
 * the app's to change, and copying it here would strand a stale value on the
 * record when the binding moves.
 *
 * Callers must already hold the per-record write tail.
 */
async function pinDerivedWalkTarget(recordId, target, loadedSelection) {
  if (target.source !== 'derived') return;
  // A 'derived' target means the set already HAS packaged geometry, so the walk
  // is underway even when no direction is approved yet — seed the selection
  // rather than skipping the pin and letting the target stay implicit. Callers
  // resolving the target through `getWalkState` already hold the selection;
  // reuse it rather than re-reading the same file inside the write tail.
  const selection = loadedSelection || (await loadSelection(recordId)) || seedSelection(recordId);
  const pinned = selection.animationTargets?.[WALK_TRACK];
  if (pinned?.frameCount === target.frameCount && pinned?.fps === target.fps) return;
  selection.animationTargets = withTrackTarget(selection.animationTargets, WALK_TRACK, {
    frameCount: target.frameCount, fps: target.fps, source: 'derived',
  });
  await ensureDir(join(spriteDir(recordId), 'walk'));
  await atomicWrite(join(spriteDir(recordId), selectionRelPath(recordId)), selection);
  console.log(`📌 sprite walk target pinned for ${recordId} · ${target.frameCount}f @ ${target.fps}fps (derived)`);
}

/**
 * Pin the walk track's cycle target explicitly — a deliberate SET-level action,
 * not a per-render slider. Changing it does not mutate existing runs; it makes
 * already-packaged directions *drift*, which `getWalkState`'s `walkTarget.drift`
 * surfaces per direction so they can be re-derived from their clips.
 *
 * Refused when the bound app's `runtimeContract` pins a different frame count:
 * changing the target then means changing the binding, which is the honest
 * requirement.
 */
export function setWalkTarget(recordId, body) {
  return walkWriteTail(recordId, () => setWalkTargetImpl(recordId, body));
}

async function setWalkTargetImpl(recordId, { frameCount, fps }) {
  const record = await requireCharacter(recordId);
  await requireUnfinalized(recordId);
  // Only the app-contract rung can REFUSE a retarget, and that rung is derived
  // from the record alone — so resolve it directly rather than paying for a full
  // getWalkState (a two-tree run scan plus every approved direction's manifest)
  // inside the write tail just to read two booleans.
  const locked = resolveAnimationTarget({
    track: WALK_TRACK,
    runtimeContract: record?.publishBinding?.runtimeContract || null,
  });
  const appId = record?.publishBinding?.appId || 'bound app';
  for (const [knob, label, requested] of [
    ['frameCount', 'Frame count', frameCount],
    ['fps', 'Playback fps', fps],
  ]) {
    if (locked[`${knob}Locked`] && locked[knob] !== requested) {
      throw new ServerError(
        `${label} is locked to ${locked[knob]} by the publish binding (${appId}) — change the binding's runtime contract to target ${requested}.`,
        { status: 409, code: 'WALK_TARGET_LOCKED' },
      );
    }
  }
  const selection = (await loadSelection(recordId)) || seedSelection(recordId);
  // `withTrackTarget` merges rather than replaces so a sibling track key written
  // by a newer PortOS (or a peer) round-trips untouched.
  selection.animationTargets = withTrackTarget(selection.animationTargets, WALK_TRACK, {
    frameCount, fps, source: 'set',
  });
  await ensureDir(join(spriteDir(recordId), 'walk'));
  await atomicWrite(join(spriteDir(recordId), selectionRelPath(recordId)), selection);
  console.log(`🎯 sprite walk target set for ${recordId} · ${frameCount}f @ ${fps}fps`);
  return getWalkState(recordId);
}

/**
 * The chroma key a walk operation should key against, most specific first: the
 * run's own frozen key, then the reference manifest's, then the record's.
 *
 * The record rung is not optional garnish — it is the ONLY rung a source-pipeline
 * import populates (the importer stamps the key it used on the record and copies
 * a manifest carrying none), and the rest of the sprite code has always resolved
 * it this way (reference.js does, at eight sites). Reading only the first two
 * rungs is what made an imported run un-generatable (`MAIN_NOT_LOCKED`) and its
 * reprocess die inside sharp with `Invalid hex color: undefined` — the same
 * missing rung surfacing as two unrelated-looking failures.
 *
 * Returns null when no rung has one, so callers refuse explicitly rather than
 * handing `undefined` to a color parser.
 */
export { resolveChromaKey } from './animationWorkflow.js';


/**
 * Whether a fresh walk render is possible for ONE direction: its anchor must be
 * locked, and the set must carry the frozen chroma key the i2v input is
 * composited onto.
 *
 * Shared by the render path (which throws `error` and then uses `anchor`/
 * `chromaKey`) and the un-finalize gate's regenerability probe (which only reads
 * whether there IS an error). That sharing is load-bearing, not tidiness: the
 * gate tells the user "every direction can be regenerated" and then drops all
 * eight approvals on the strength of it, so a predicate that checked less than
 * the render actually requires would walk them into exactly the dead end the
 * acknowledgement promises can't happen (#3043). `error` is a factory so the
 * probe never builds a ServerError it discards.
 *
 * The chroma key falls back `manifest → record`, which is the resolution order
 * the rest of the sprite code already uses (reference.js resolves it that way at
 * eight sites). Reading `manifest.chromaKey` alone made every SOURCE-PIPELINE
 * IMPORT unrenderable: the importer stamps the key it used on the record and the
 * imported manifest carries none, so a fully-locked imported set reported "no
 * frozen chroma key" and refused every Generate. Absent on BOTH is still the
 * genuine "main was never locked" refusal.
 *
 * Deliberately I/O-free: the on-disk anchor probe (`ANCHOR_MISSING`) stays in the
 * render path, since this runs per-direction from a read.
 */
function resolveWalkRenderability(manifest, record, direction) {
  const anchor = lockedAnchorFor(manifest, direction);
  if (!anchor) {
    return {
      anchor: null,
      chromaKey: null,
      error: () => new ServerError(`Lock the ${anchorIdForDirection(direction)} anchor before animating it`, { status: 409, code: 'ANCHOR_NOT_LOCKED' }),
    };
  }
  const chromaKey = resolveChromaKey({ manifest, record });
  if (!chromaKey) {
    return {
      anchor,
      chromaKey: null,
      error: () => new ServerError('Reference set has no frozen chroma key', { status: 409, code: 'MAIN_NOT_LOCKED' }),
    };
  }
  return { anchor, chromaKey, error: null };
}

/**
 * Start one observable grok walk-video render for a direction whose anchor is
 * locked. User-triggered only (route-invoked); exactly one image_to_video call
 * per run — all derivatives are deterministic local work.
 *
 * grok runs as an interactive TUI session (executeTuiRun) rather than a headless
 * job so the user can pop into the Shell page to watch it, and — if needed —
 * type to course-correct or Stop it. The session id IS the run id, so the walk
 * card can deep-link to `/shell/<runId>` the moment the render starts. The
 * render itself runs OUTSIDE the per-record write tail (a ~10-min PTY run must
 * not block other walk ops); its completion re-enters the tail to attach.
 */
export function startWalkGeneration(recordId, body) {
  return walkWriteTail(recordId, () => startWalkGenerationImpl(recordId, body));
}

async function startWalkGenerationImpl(recordId, body) {
  const record = await requireCharacter(recordId);
  await requireUnfinalized(recordId);
  const direction = body.direction;
  const manifest = await loadManifest(recordId);
  const { anchor, chromaKey, error } = resolveWalkRenderability(manifest, record, direction);
  if (error) throw error();
  // Refuse a second render for a direction already in flight. A fresh runId per
  // call is the only reservation, and the client's Generate button can briefly
  // re-enable between the media-poll eviction of its optimistic key and the next
  // getWalkState refetch — without this backstop, a click in that window fires a
  // second paid grok render for the same direction. Serialized by the write tail,
  // so no TOCTOU. getWalkState normalizes a stale 'rendering' run (server died
  // mid-render) to 'error', so this blocks only a genuinely live render.
  const { runs: inFlight, walkTarget, selection } = await getWalkState(recordId);
  if (inFlight.some((r) => r.direction === direction && (r.status === 'rendering' || r.status === 'postprocessing'))) {
    throw new ServerError(`A walk render for ${direction} is already in progress`, { status: 409, code: 'WALK_RENDER_IN_PROGRESS' });
  }
  // Cycle geometry is pinned at the SET level (#2985) — every direction in one
  // atlas must share it. An omitted count/fps adopts the target; a disagreeing
  // one is refused here rather than at atlas-compile time, eight renders later.
  const { frameCount, fps } = await resolveRenderGeometry(recordId, { walkTarget, selection }, body);
  const anchorAbs = resolveSpriteAssetPath(recordId, anchor.path);
  if (!await pathExists(anchorAbs)) {
    throw new ServerError('Locked anchor file is missing on disk', { status: 500, code: 'ANCHOR_MISSING' });
  }

  // WHICH lane renders the clip (#4876). Absent → grok, so every pre-existing
  // client, persisted retry, and test renders exactly where it did before the
  // local lane existed.
  const provider = resolveAnimationProvider(body.provider);
  // Clip length grok will actually deliver — a request it does not offer falls
  // back to its shortest (see lib/grokVideoClip.js). The walk's look comes from
  // frameCount/fps below, not from how much footage the packer had to pick from.
  // The local lane snaps the same request onto H3's 17n+5 frame grid instead,
  // which is why `duration` stays the shared unit rather than a grok-only field.
  const duration = resolveGrokDuration(body.duration);
  // Resolved BEFORE the run directory is created, not just before the run
  // record: an install with no runnable local model must leave NOTHING behind.
  // An empty run directory is not inert — the run scan reads it back, finds no
  // record, and (before this) took getWalkState down with it.
  const localPlan = provider === 'local'
    ? await planLocalAnimationRender({ durationSeconds: duration })
    : null;

  const runId = `walk-${direction}-${randomUUID().slice(0, 8)}`;
  const runRel = runRelPath(runId);
  const runAbs = join(spriteDir(recordId), runRel);
  const generatedAbs = join(runAbs, 'generated');
  await ensureDir(generatedAbs);

  // i2v motion input: the anchor composited onto the SOLID chroma matte grok
  // must animate over (NOT a transparent PNG — that made grok composite over
  // black and reinvent an off-spec magenta from the prompt text; see
  // prepareWalkAnchorChromaInput). Saved without mutating the locked anchor.
  // Overlap the input prep with the (independent) settings read.
  const inputAbs = join(generatedAbs, 'input-anchor-chroma.png');
  const [{ preparation, sha256: inputSha256, canvas }, settings] = await Promise.all([
    prepareWalkAnchorChromaInput(anchorAbs, inputAbs, chromaKey, localPlan?.chooseCanvas || null),
    getSettings(),
  ]);
  // Frame count + playback fps are the deterministic-postprocess knobs, not the
  // clip's — the provider animates the same clip regardless, and the packer
  // resamples/labels the cycle afterward. Resolved from the set target above and
  // stored on the run so the completion hook's packageRun (and any later
  // reprocess) applies exactly what the set is pinned to.
  // Optional re-roll note (#3134): appended to the motion prompt so a second
  // render can be told what the first got wrong. Trimmed here and stamped on the
  // run record below only when non-empty, so a blank note leaves both the prompt
  // and the persisted run byte-identical to a blind regenerate.
  const correctionPrompt = typeof body.correctionPrompt === 'string' ? body.correctionPrompt.trim() : '';
  const prompt = buildWalkVideoPrompt({ name: record.name, direction, chromaKey, correctionPrompt });
  const videoAbs = join(generatedAbs, 'source-video.mp4');
  const grokPath = settings.imageGen?.grok?.grokPath;
  // Run record BEFORE the job is queued: the completion hook finds the run by
  // `runId` out of the job's own params, so the record must already exist when
  // the job can first settle. (The grok lane persists first for the mirror
  // reason — a crash between the two leaves an inert 'rendering' run rather
  // than a session the attach can't file.) `shellSession` is the id the walk
  // card deep-links to; a local render is a queued media job, not a PTY, so it
  // carries `jobId` instead — the two are mutually exclusive on purpose.
  const now = new Date().toISOString();
  const run = {
    schemaVersion: 1,
    kind: 'grok-game-animation-frames-run',
    // Vendor recorded as metadata, not baked into the storage path — the local
    // lane stamps its own provider and stores under the same runs/ tree.
    provider: GROK_TUI_ID,
    status: 'rendering',
    id: runId,
    // The TUI run id doubles as the attachable Shell session id (executeTuiRun
    // registers the PTY under this id), so the card can link to /shell/<id>.
    shellSession: runId,
    characterId: recordId,
    direction,
    chromaKey,
    duration,
    frameCount,
    fps,
    anchorPath: anchor.path,
    anchorSha256: anchor.sha256 || await sha256File(anchorAbs),
    animationInputPath: `${runRel}/generated/input-anchor-chroma.png`,
    animationInputSha256: inputSha256,
    animationInputPreparation: preparation,
    ...(correctionPrompt ? { correctionPrompt } : {}),
    createdAt: now,
    // Spread LAST so the local lane's provider/geometry provenance overrides the
    // grok defaults above rather than being silently overwritten by them.
    ...(localPlan ? { ...localRenderManifest(localPlan, canvas), shellSession: null } : {}),
  };
  await saveRunRecord(recordId, run);

  if (localPlan) {
    // Queued AFTER the record is durable. Nothing here awaits the render: the
    // boot-registered completion hook stages the clip and runs the attach, which
    // is what lets a render outlive this request, the client, and a restart.
    // A refused admission (#8325) must not strand the run at `rendering`
    // with no job behind it — settle it as an error before surfacing.
    const jobId = await enqueueLocalAnimationRender({
      plan: localPlan, canvas, prompt, inputAbs, recordId, runId, track: WALK_TRACK, direction,
    }).catch(async (err) => {
      Object.assign(run, { status: 'error', postprocessError: err.message, completedAt: new Date().toISOString() });
      await saveRunRecord(recordId, run);
      throw err;
    });
    // Stamped in a SECOND write so a failure here cannot strand the job: the
    // hook already has everything it needs from the job's own params, and a run
    // that misses this only degrades `localRunLiveness` to `unknown`, whose
    // wall-clock fallback still resolves it.
    run.jobId = jobId;
    await saveRunRecord(recordId, run);
    console.log(`🚶 sprite walk local render started ${recordId}/${runId} (job ${jobId.slice(0, 8)}, ${localPlan.numFrames}f @ ${localPlan.fps}fps)`);
    return { runId, direction, duration, provider: 'local', jobId };
  }

  // Fire the observable grok-tui render fire-and-forget (do NOT await — this
  // impl holds the per-record write tail, which a ~10-min render must not).
  // Completion re-enters the tail via attachTuiWalkResult; errors are captured
  // onto the run record (no request lifecycle to bubble to).
  runWalkTuiRender(recordId, {
    runId, direction, grokPath, task: buildGrokI2vTask({ prompt, inputAbs, videoAbs, duration }),
    generatedAbs, videoAbs,
  }).catch((err) => console.error(`❌ sprite walk grok-tui render crashed ${recordId}/${runId}: ${err?.message || err}`));

  console.log(`🚶 sprite walk grok-tui render started ${recordId}/${runId} (shell session ${runId})`);
  return { runId, direction, duration, provider: 'grok', shellSession: runId };
}

/**
 * Drive the observable grok-tui render to completion, then attach its result.
 * executeTuiRun spawns grok in a PTY and registers it as a Shell session under
 * `runId`; its promise resolves on success OR failure, so the attach decides
 * outcome from whether the directed MP4 actually landed on disk.
 */
async function runWalkTuiRender(recordId, { runId, direction, grokPath, task, generatedAbs, videoAbs }) {
  const provider = grokTuiProvider(grokPath);
  await executeTuiRun({
    runId,
    provider,
    prompt: task,
    workspacePath: generatedAbs,
    idleMs: WALK_TUI_IDLE_MS,
    timeout: WALK_TUI_TIMEOUT_MS,
    label: `sprite walk ${recordId}/${direction}`,
  }).catch((err) => {
    console.error(`❌ sprite walk grok-tui run failed ${recordId}/${runId}: ${err?.message || err}`);
  });
  // The lease comes first, like the completion hook's: the clip grok wrote, the
  // decoded frames and the run record naming them are one publication (#9982).
  await withBackupAssetPublication(() => walkWriteTail(recordId, () => attachTuiWalkResult(recordId, runId, videoAbs)));
}

/**
 * Attach the finished clip and run the deterministic postprocess — shared by
 * BOTH render lanes, because everything downstream of `source-video.mp4` is
 * provider-agnostic. Guards against overwriting frozen evidence (finalized set /
 * already-approved run). The source video is already at its final path by the
 * time this runs (grok writes it there directly; the local lane copies it out of
 * the media-job output), so there is no copy here either way.
 */
export async function attachTuiWalkResult(recordId, runId, videoAbs) {
  const run = await loadRunRecord(recordId, runId);
  if (!run) {
    console.error(`❌ sprite walk run record missing for ${recordId}/${runId} — skipping attach`);
    return;
  }
  if (await loadWalkSet(recordId)) {
    console.error(`❌ sprite walk attach skipped for ${recordId}/${runId} — walk set is finalized`);
    return;
  }
  const selection = await loadSelection(recordId);
  if (selection?.directions?.[run.direction]?.runId === runId) {
    console.error(`❌ sprite walk attach skipped for ${recordId}/${runId} — run is approved (immutable)`);
    return;
  }
  if (!await pathExists(videoAbs)) {
    run.status = 'error';
    run.postprocessError = isLocalProviderRun(run)
      ? 'The local render produced no walk video — check the Render Queue for the failed job'
      : 'Grok finished without writing the walk video — check the shell session output';
    run.completedAt = new Date().toISOString();
    await saveRunRecord(recordId, run);
    console.error(`❌ sprite walk ${runProviderLabel(run)} produced no video ${recordId}/${runId}`);
    return;
  }
  run.sourceVideoSha256 = await sha256File(videoAbs);
  run.status = 'postprocessing';
  // Anchors the packaging staleness window (normalizeStaleAnimationRun). It MUST
  // be measured from here rather than from `createdAt`: a local render can have
  // been queued hours before packaging starts, so a createdAt-anchored window
  // reports every healthy local run as interrupted the moment it begins to pack.
  run.postprocessingStartedAt = new Date().toISOString();
  await saveRunRecord(recordId, run);
  await packageRun(recordId, run);
  await saveRunRecord(recordId, run);
  console.log(`🚶 sprite walk ${runProviderLabel(run)} run ${recordId}/${runId} → ${run.status}`);
}

/**
 * Run the deterministic postprocess for a run and apply the outcome to the
 * run record (candidate on success, captured error otherwise) — shared by
 * the completion-hook attach and the manual rerun so the two can't drift.
 * The caller persists the mutated record.
 *
 * `location` pins WHERE the run lives and which clip to read: the attach path
 * omits it (PortOS just wrote the run under `runs/<id>/`), while a rerun that
 * resolved the run under the other layout passes both, so the regenerated frames
 * land beside the clip they came from instead of in a phantom twin directory.
 */
async function packageRun(recordId, run, overrides = {}, location = {}) {
  const runRel = location.runDirRel || runRelPath(run.id);
  const runAbs = join(spriteDir(recordId), runRel);
  // Frame count + playback fps: an explicit reprocess override wins, else the
  // values stored at generate time, else the current defaults (older runs
  // predate the fields). Clamped + stamped back onto the run so the record
  // always reflects exactly what was packed and a later reprocess can reuse it.
  const frameCount = clampFrameCount(overrides.frameCount ?? run.frameCount ?? WALK_DEFAULT_FRAME_COUNT);
  const fps = clampFps(overrides.fps ?? run.fps ?? WALK_DEFAULT_FPS);
  run.frameCount = frameCount;
  run.fps = fps;
  // Record-relative path to the raw clip, stamped BEFORE the (possibly failing)
  // postprocess so a run that errors in packaging still surfaces the video the
  // provider actually produced in the UI, not just the error text. Set here (shared by
  // attach + rerun) so a retry backfills it onto an older run too — and for an
  // imported run that means persisting the record-relative form in place of the
  // source-repo anchor its manifest was copied with.
  run.sourceVideoPath = location.clipRel || `${runRel}/generated/${SOURCE_CLIP_NAME}`;
  try {
    // Inside the try on purpose: unlike the old `join(runAbs, …)` this can throw
    // (the confinement gate), and this function's contract is that a packaging
    // failure is CAPTURED onto the run record — a throw escaping here would
    // strand an attach at 'postprocessing' with no error text.
    const videoAbs = resolveSpriteAssetPath(recordId, run.sourceVideoPath);
    // What the provider DELIVERED, as opposed to what `run.duration` asked for —
    // the requested length is not a promise on either lane (grok picks from its
    // own menu, see lib/grokVideoClip.js; H3 snaps to its 17n+5 grid). Stamped
    // here, shared by attach + rerun, so a reprocess backfills it onto an older
    // run. Overlap the probe with the (independent) manifest read.
    //
    // probeVideoDuration returns null when ffprobe is missing or the file has no
    // parseable duration; leave the field ABSENT in that case rather than
    // stamping 0, so "unknown" never reads as "a zero-length clip". A previously
    // stamped value survives — a probe that can't run is not evidence of change.
    const [probedSeconds, manifest, record] = await Promise.all([
      probeVideoDuration(videoAbs),
      loadManifest(recordId),
      getRecord(recordId),
    ]);
    if (probedSeconds) run.sourceVideoSeconds = Math.round(probedSeconds * 100) / 100;
    const anchor = manifest?.anchors?.find((a) => a.direction === run.direction);
    if (!anchor?.path) throw new Error(`No locked ${run.direction} anchor in the reference manifest`);
    // Refuse HERE rather than letting an absent key reach the un-key step, which
    // reported it as `Invalid hex color: undefined` — a parser's complaint about
    // its argument, naming neither the field nor the record that lacks it.
    const chromaKey = resolveChromaKey({ manifest, record, run });
    if (!chromaKey) {
      throw new Error(`No chroma key for ${recordId} — the run, the reference manifest, and the record all lack one, so the matte cannot be keyed out`);
    }
    const result = await runWalkPostprocess({
      recordId,
      direction: run.direction,
      chromaKey,
      runAbs,
      runRel,
      anchorRel: anchor.path,
      anchorAbs: resolveSpriteAssetPath(recordId, anchor.path),
      videoAbs,
      frameCount,
      fps,
    });
    run.status = 'candidate';
    run.postprocessManifest = result.manifestPath;
    run.stripPreview = result.stripPreview;
    delete run.postprocessError;
  } catch (err) {
    // May run outside the request lifecycle (hook) — capture, don't crash.
    run.status = 'error';
    run.postprocessError = err.message;
    console.error(`❌ sprite walk postprocess failed ${recordId}/${run.id}: ${err.message}`);
  }
  run.completedAt = new Date().toISOString();
}

/**
 * Why this run's cycle cannot be re-derived from its clip right now, or null
 * when it can — stated ONCE, in the order the write path applies the refusals.
 *
 * Both sides read it: `rerunWalkPostprocessImpl` throws the matching error, and
 * `getWalkSourceFrames` reports it as `lockReason` so the Loop Trimmer can offer
 * the unlock/reopen that clears it instead of a re-derive that would 409. A read
 * path with its own copy of this rule is precisely how the two would drift —
 * #2993 already moved the underlying question from provenance ("is this an
 * import?") to evidence ("is the clip actually on disk?"), and a second
 * definition would strand one of them on the old answer.
 *
 * A frozen set outranks an approved direction because the set gate is the
 * coarser one; a missing clip is last because it is the one state the user
 * cannot unlock their way out of.
 */
function reDeriveLockReason({
  walkSet, selection, run, runId, clipRel,
}) {
  if (walkSet) return 'finalized';
  if (selection?.directions?.[run.direction]?.runId === runId) return 'approved';
  if (!clipRel) return 'no-source-video';
  return null;
}

const RE_DERIVE_REFUSALS = {
  finalized: walkSetFinalError,
  approved: () => new ServerError('Run is approved — approved runs are immutable', { status: 409, code: 'RUN_APPROVED' }),
  'no-source-video': () => new ServerError('Run has no source video yet', { status: 409, code: 'VIDEO_NOT_READY' }),
};

/**
 * Re-run the deterministic postprocess for a run whose source video already
 * landed — crash recovery, determinism verification, or (the common case since
 * #2985/#2980) bringing a direction onto the set's cycle target from the clip
 * already on disk. Approved/finalized runs are immutable.
 */
export function rerunWalkPostprocess(recordId, { runId, frameCount, fps }) {
  return walkWriteTail(recordId, () => rerunWalkPostprocessImpl(recordId, runId, { frameCount, fps }));
}

async function rerunWalkPostprocessImpl(recordId, runId, overrides) {
  await requireCharacter(recordId);
  // Layout-aware (#2993): an imported run commonly lives under `grok/<run-id>/`,
  // and its regenerated frames + record must go back to that same directory.
  const found = await resolveWalkRunById(recordId, runId);
  if (!found) throw new ServerError(`Unknown walk run: ${runId}`, { status: 404, code: 'RUN_NOT_FOUND' });
  const { run, runDirRel } = found;
  // One state read serves the re-derive gate and the target below.
  const { walkTarget, selection, walkSet } = await getWalkState(recordId);
  const clipRel = await resolveRunClipRel(recordId, run, runDirRel);
  const refusal = reDeriveLockReason({
    walkSet, selection, run, runId, clipRel,
  });
  if (refusal) throw RE_DERIVE_REFUSALS[refusal]();
  // Same set-level gate as generation (#2985): a reprocess is exactly how a
  // drifted direction is brought INTO line with the target, so it must land on
  // the target — not somewhere new. An omitted override adopts the target.
  const geometry = await resolveRenderGeometry(recordId, { walkTarget, selection }, overrides);
  // An imported record carries no `id` at all; stamp the run directory's name
  // (what every reader already falls back to) so the re-derived record is
  // self-describing from here on.
  if (!run.id) run.id = runId;
  // Reprocess the SAME on-disk clip at the pinned frame count / playback speed —
  // no grok call, no regeneration.
  await packageRun(recordId, run, geometry, { runDirRel, clipRel });
  await saveRunRecordAt(recordId, run, runDirRel);
  if (run.status === 'error') {
    throw new ServerError(`Postprocess failed: ${run.postprocessError}`, { status: 422, code: 'POSTPROCESS_FAILED' });
  }
  return run;
}

// The raw-frame location + naming come from paths.js, which builds
// `listSpriteAssets`' exclusion from the same two values — this reader is the
// sanctioned narrow window onto the directory that listing deliberately skips.
async function listRawFrameNames(recordId, rawRel) {
  const names = await readdir(join(spriteDir(recordId), rawRel)).catch(() => []);
  return names.filter((name) => RAW_FRAME_NAME.test(name)).sort();
}

/**
 * Re-express the packer's chosen cycle window in the numbering the client
 * renders frames in.
 *
 * `cycleSelection.windowStart` counts from the start of the longest USABLE span
 * the packer kept (walkPostprocess.js slices the clip's fade-in frames off
 * before selecting), while `frames[].sourceFrameIndex` counts raw `source-NNNN`
 * files 1-based. The two are different coordinate spaces and differ by
 * `span.start`, which the manifest never records — but it doesn't need to:
 * `indices[0] === windowStart`, so the FIRST packed frame's source index IS the
 * window's first raw frame. Without this translation the highlight would sit
 * `span.start` frames to the left of the frames it claims to cover.
 *
 * `windowEndFrame` is EXCLUSIVE — it is the seam frame the packer scored the
 * window's endpoints against, not a member of the cycle. Only ever called for a
 * manifest whose packed frames were verified against disk (see
 * `manifestCycleProvenance`), so the per-field null degradation below covers a
 * malformed `cycleSelection`, not a missing `frames[]`.
 */
function cycleWindowOf(packaged) {
  const cycle = packaged?.cycleSelection;
  if (!cycle) return null;
  const windowLength = Number.isInteger(cycle.windowLength) ? cycle.windowLength : null;
  const first = packaged?.frames?.[0]?.sourceFrameIndex;
  const windowStartFrame = Number.isInteger(first) ? first : null;
  return {
    windowStart: Number.isInteger(cycle.windowStart) ? cycle.windowStart : null,
    windowLength,
    windowStartFrame,
    windowEndFrame: windowStartFrame !== null && windowLength !== null
      ? windowStartFrame + windowLength : null,
    periodEstimate: Number.isInteger(cycle.periodEstimate) ? cycle.periodEstimate : null,
    periodAgreement: typeof cycle.periodAgreement === 'string' ? cycle.periodAgreement : null,
  };
}

/**
 * The packed-strip provenance to report against the raw frames actually on disk:
 * the cycle window, the source indices that became columns, and whether the two
 * can be trusted to address the same files.
 *
 * The check is not paranoia. `cycleSelection` and `frames[].sourceFrameIndex`
 * were recorded when the run was PACKAGED — for an imported run, by the source
 * pipeline's own extraction — while the frames listed here may have been
 * re-extracted by this install's ffmpeg (`fps=12`, first 8s). If those two
 * extractions disagree at all, the indices address different PNGs and the panel
 * would confidently mark the wrong frames as "the gait cycle" and "packed into
 * the strip" — a false claim about provenance is worse than no claim.
 *
 * **Presence is not identity, which is why this hashes.** Both extractions name
 * their output `source-%04d.png`, so a source pipeline that sampled at 24fps
 * declares a `source-0010.png` that also exists here — holding a different
 * moment of the clip. A basename check would call that 'verified' and mark the
 * wrong frames, i.e. miss the exact hazard it exists for. The packer records
 * `sourceSha256` per frame (walkPostprocess.js), so compare one declared frame's
 * bytes; a manifest too old to carry hashes falls back to presence, which is
 * still better than nothing and never worse than not checking.
 *
 *   'verified'  the declared source frames are the ones on disk → markers are real
 *   'stale'     they are not → markers withheld, and the client says why
 *   'none'      the run carries no packaged cycle to map (never packaged, or a
 *               minimal manifest) → nothing to verify, nothing to withhold
 */
async function manifestCycleProvenance(recordId, rawRel, packaged, names) {
  const packedFrames = Array.isArray(packaged?.frames) ? packaged.frames : [];
  const indices = packedFrames
    .map((frame) => frame?.sourceFrameIndex)
    .filter((index) => Number.isInteger(index));
  const withheld = { cycle: null, selectedSourceIndices: [], cycleProvenance: 'stale' };
  if (!indices.length) return { ...withheld, cycleProvenance: 'none' };
  const declared = packedFrames.map((frame) => (typeof frame?.sourcePath === 'string'
    ? { name: frame.sourcePath.split('/').pop(), sha256: frame.sourceSha256 }
    : null));
  // Partial declaration is not partial evidence: two of twelve frames naming a
  // path that happens to exist says nothing about the other ten, so treat an
  // incompletely-declared manifest as unverifiable rather than verified. A
  // manifest that declares NOTHING (older/minimal packaging) is taken at its
  // word — there is nothing to compare, and withholding the markers would punish
  // a record for being terse rather than wrong.
  if (!declared.some(Boolean)) {
    return { cycle: cycleWindowOf(packaged), selectedSourceIndices: indices, cycleProvenance: 'verified' };
  }
  const onDisk = new Set(names);
  if (!declared.every((frame) => frame && onDisk.has(frame.name))) return withheld;
  // One hash settles it: the declared frames come from a single extraction, so
  // if one is byte-identical the numbering they share is the numbering on disk.
  const hashed = declared.find((frame) => typeof frame.sha256 === 'string' && frame.sha256);
  if (hashed && await sha256File(join(spriteDir(recordId), rawRel, hashed.name)) !== hashed.sha256) {
    return withheld;
  }
  return {
    cycle: cycleWindowOf(packaged),
    selectedSourceIndices: indices,
    cycleProvenance: 'verified',
  };
}

/**
 * One source-frame response, defaulted to the "nothing to show" shape and
 * overridden with whatever was actually found.
 *
 * Written as one builder rather than two hand-assembled object literals so that
 * adding a field is one edit: the absent case has to stay as informative as the
 * populated one (the client still seeds its re-derive control from `target` and
 * labels the run's current geometry off `current`), and a shape that only two
 * thirds matched would defeat that quietly.
 */
function sourceFrameResponse(runId, run, walkTarget, walkSet, found) {
  return {
    runId,
    direction: run?.direction || null,
    // Whether the run is still packaged by the source pipeline — the client picks
    // the right remedy from it (re-import vs "this was generated here"), rather
    // than assuming every clipless run is an import.
    imported: Boolean(run?.importedPackaging),
    extractionFps: WALK_FPS,
    maxSourceSeconds: MAX_SOURCE_SECONDS,
    current: runCycleOf(run),
    // The set-level cycle target (#2985) — the re-derive control's bounds come
    // from here, not from a free authoring range: re-deriving ONE direction to a
    // geometry the rest of the set doesn't share just recreates a ragged set from
    // the other end (and the reprocess would 409 WALK_TARGET_MISMATCH anyway).
    target: walkTarget,
    available: false,
    reason: null,
    frames: [],
    cycle: null,
    selectedSourceIndices: [],
    cycleProvenance: 'none',
    editable: false,
    lockReason: null,
    // Only meaningful alongside lockReason 'finalized': whether the set-level
    // Unlock this panel offers is itself blocked, and whether that block can be
    // acknowledged past (#3043). Passed through from the walk state the caller
    // already loaded, so this panel and the walk workflow offer the same action
    // for the same set.
    unlock: walkSet?.unlock || null,
    ...found,
  };
}

/**
 * Every frame the run's source video produced, plus the provenance that maps
 * them onto the packed strip (#2980).
 *
 * The Loop Trimmer can only ever DROP columns from an already-packed strip, so
 * the raw frames are the only path back to a HIGHER frame count — and they are
 * invisible everywhere else by design (`listSpriteAssets` skips the directory so
 * ~73 near-identical PNGs don't swamp the asset browser). This is the narrow
 * read that surfaces them, and only them.
 *
 * Three absence sentinels, kept distinct per the repo's absent-vs-empty rule:
 *   - `available: false, reason: 'no-source-video'`   no clip on disk at all
 *   - `available: false, reason: 'raw-frames-cleaned'` the clip IS here, but its
 *     extracted frames were pruned — recoverable, see `extract` below
 *   - `available: false, reason: 'run-not-packaged'`  a synthesized redraw cycle
 *     (#2924), which never had an i2v clip or a run directory behind it
 * …none of which is a 500, nor an empty-looking success.
 *
 * `editable`/`lockReason` answer a SEPARATE question from `available`: frames can
 * be listed for a run whose clip has since been deleted (nothing to re-derive
 * from), and a run with a clip can still be locked by approval or by a frozen
 * set. Collapsing the two would make the UI claim a re-derive is possible whenever
 * it had something to show.
 *
 * **`extract` is opt-in, and this read is otherwise side-effect free.** The
 * importer never copies `raw/` (its EXCLUDED_RUN_SEGMENTS skips it), so EVERY
 * imported run reaches this with an empty raw directory — exactly the population
 * the feature exists for. Extracting from the read would therefore mean opening
 * the trimmer and clicking through eight directions silently spawns eight ffmpeg
 * decodes (~96 PNGs each), each holding the per-record write tail while an
 * approve or trim queues behind it, and lands >100MB of re-derivable
 * intermediates that flow into backups — all for a panel the user may never
 * expand. So the plain read reports `raw-frames-cleaned` and the caller asks for
 * `extract: true` from an explicit user action (`POST …/source-frames/extract`).
 * The extraction itself is idempotent (`ffmpeg -y`) and runs inside the
 * per-record write tail like every other walk write.
 */
export async function getWalkSourceFrames(recordId, runId, { extract = false } = {}) {
  // All three reads are independent — the character gate, the run lookup, and
  // the walk state (which serves the target, the lock gate, and the redraw
  // fallback below) — so pay for them once, concurrently.
  const [, found, state] = await Promise.all([
    requireCharacter(recordId),
    resolveWalkRunById(recordId, runId),
    getWalkState(recordId),
  ]);
  const { walkTarget, selection, walkSet } = state;
  if (!found) {
    // A run the walk state knows but that has no run DIRECTORY is a redraw cycle
    // synthesized from an imagegen manifest — a legitimate trimmer source with no
    // clip behind it, so it gets the soft sentinel rather than the 404 an
    // unknown id earns.
    const known = state.runs.find((r) => r.id === runId);
    if (!known) throw new ServerError(`Unknown walk run: ${runId}`, { status: 404, code: 'RUN_NOT_FOUND' });
    return sourceFrameResponse(runId, known, walkTarget, walkSet, {
      reason: 'run-not-packaged',
      // A frozen set outranks the missing clip, matching `reDeriveLockReason`'s
      // own ordering. Hardcoding 'no-source-video' here made the Loop Trimmer
      // treat a FINALIZED set as merely clipless for a redraw-only direction
      // (an imagegen cycle has no run directory) — so it left `CycleTarget`
      // enabled, which 409s on change, and suppressed the lock panel that
      // carries the unlock. That is the pair of defects #3043 set out to fix,
      // still reachable through the one direction that has no run behind it.
      lockReason: walkSet ? 'finalized' : 'no-source-video',
    });
  }
  const { runDirRel } = found;
  const run = normalizeRunRecord(recordId, found.run, runDirRel);
  const rawRel = rawFramesRelOf(runDirRel);
  // Three independent probes (the clip, the raw listing, the packaged manifest)
  // — none feeds the next, so they overlap rather than serializing three round
  // trips onto a read the trimmer makes on every source switch.
  const [clipRel, listed, packaged] = await Promise.all([
    resolveRunClipRel(recordId, run, runDirRel),
    listRawFrameNames(recordId, rawRel),
    run.postprocessManifest
      // Read-only source-frame inspection; postprocess writes a fresh authoritative manifest.
      ? readJSONFile(join(spriteDir(recordId), run.postprocessManifest), null)
      : null,
  ]);
  let names = listed;
  if (!names.length && clipRel && extract) {
    await walkWriteTail(recordId, () => extractVideoFrames(
      resolveSpriteAssetPath(recordId, clipRel),
      resolveSpriteAssetPath(recordId, rawRel),
    ));
    // Re-listed rather than taking the extractor's return, so what counts as a
    // raw frame is defined in exactly one place.
    names = await listRawFrameNames(recordId, rawRel);
  }
  const frames = names.map((name) => ({
    index: Number(RAW_FRAME_NAME.exec(name)[1]),
    path: `${rawRel}/${name}`,
  }));
  const lockReason = reDeriveLockReason({
    walkSet, selection, run, runId, clipRel,
  });
  return sourceFrameResponse(runId, run, walkTarget, walkSet, {
    available: frames.length > 0,
    // "No clip at all" and "clip present, frames pruned" are different states
    // with different remedies — the second is one click from recoverable.
    reason: frames.length > 0 ? null : (clipRel ? 'raw-frames-cleaned' : 'no-source-video'),
    frames,
    ...(await manifestCycleProvenance(recordId, rawRel, packaged, names)),
    editable: !lockReason,
    lockReason,
  });
}

/**
 * Approve one direction's candidate run. When all 8 directions are approved
 * the finalized walk-set manifest is written and the record advances to
 * walk-complete — after which the set is immutable.
 */
export function approveWalkDirection(recordId, args) {
  return withBackupAssetPublication(() => walkWriteTail(recordId, () => approveWalkDirectionImpl(recordId, args)));
}

/**
 * Unlock (un-freeze) a finalized walk set so it can be revised in place.
 *
 * The finalized walk set is normally one-way — `requireUnfinalized` 409s every
 * mutating walk op while `walk/<id>-walk-set-v1.json` exists — with "a new
 * character version" as the only escape. This gives the single user a
 * deliberate way back to the editable state (#2933 follow-up): it removes the
 * frozen walk-set file and resets the per-direction selection to in-progress,
 * so every direction returns to the generate/regenerate/approve flow with its
 * already-rendered clips preserved on disk (the `runs/<runId>/` run records are
 * never touched). Re-approving all 8 directions re-freezes the set exactly as
 * the original finalize did. The record status drops back to
 * `reference-complete` (all anchors locked, walk in progress).
 *
 * A source-pipeline import (#2895) is refused only when it genuinely has nothing
 * to re-derive from — see `assertReDerivable`. `acknowledgeNoClips` is the
 * caller's informed override of exactly that refusal: re-deriving is not the only
 * way back when the directional anchors are still locked, so a user who means to
 * REGENERATE the set can say so.
 */
export function unlockWalkSet(recordId, { acknowledgeNoClips = false } = {}) {
  return withBackupAssetPublication(() => walkWriteTail(recordId, () => unlockWalkSetImpl(recordId, { acknowledgeNoClips })));
}

/**
 * The directions among `scope` that have no clip on disk to re-derive from.
 * Bounded at eight, so fan out rather than walking them serially — the path that
 * examines every direction is the refusal path.
 */
async function directionsWithoutClip(recordId, walkSet, scope) {
  const clips = await Promise.all(scope
    .map((direction) => directionClipRel(recordId, walkSet.directions?.[direction])));
  return scope.filter((_, i) => !clips[i]);
}

/**
 * One refusal for "this imported set has nothing on disk to re-derive from".
 *
 * `regenerable` only extends the message with the way past it — the CODE stays
 * the same either way, following the `FORK_SYNC_REQUIRED`/`acknowledgeFork`
 * precedent in the self-update path: a code names WHAT was refused, and the
 * message names the acknowledgement that overrides it. Whether a given block is
 * overridable is carried by the stamped `walkSet.unlock.acknowledgeable` that
 * clients already read, so a second code would be an unread parallel channel for
 * a fact they have — while forking a string three call sites match on (#3043).
 */
const notReDerivable = (detail, {
  regenerable = false,
  acknowledgement = 're-open the set and regenerate each direction from its locked anchor instead (one new render each)',
} = {}) => new ServerError(
  [
    detail,
    regenerable && `Re-submit with acknowledgeNoClips to ${acknowledgement}.`,
    'Re-import this character to bring its walk clips across, or create a new character version to revise it.',
  ].filter(Boolean).join(' '),
  { status: 409, code: 'LEGACY_IMPORTED_WALK_SET' },
);

/**
 * Refuse un-finalizing an imported walk set that has nothing to re-derive from.
 *
 * The original guard refused EVERY imported set, on the stated grounds that it
 * "has no regenerable clips behind it" — true when it was written, and false
 * since #2984 taught the importer to copy each run's `source-video.mp4`. So the
 * gate now keys on the evidence the justification always named: is a clip
 * actually on disk? (#2993)
 *
 * Provenance still selects WHO gets examined, and only that: a native set is
 * never gated, exactly as before — a user who cleaned up their own rendered
 * clips must not suddenly find Unlock refused.
 *
 * The scope is what separates the two callers, and it is not cosmetic. `reopen`
 * un-approves ONE direction, so one direction's clip is the whole question.
 * `unlock` drops EVERY approval and the frozen set with them — and a
 * source-packaged direction with no clip can be neither reprocessed (nothing to
 * re-derive from) nor re-approved (its frames were never imported, so
 * RUN_FRAMES_MISSING), which means unlock must name the dropped directions before
 * it un-approves every run. A usable locked anchor permits the user to
 * acknowledge a fresh-render recovery; otherwise the refusal remains.
 */
async function assertSetReDerivable(recordId, walkSet, { acknowledgeNoClips = false } = {}) {
  // No `isImportedWalkSet` pre-check: the resolver encodes that same answer as
  // `blocked: false`, and enforcing "native sets are never gated" in two places
  // is how the two would eventually disagree.
  const { blocked, stranded, acknowledgeable } = await resolveUnlockBlock(
    recordId,
    walkSet,
    null,
    importedWalkDirections(walkSet),
  );
  if (!blocked) return;
  // Acknowledged: the caller was shown what they lose (re-derivation) and what it
  // costs them instead (a fresh render per stranded direction), and said yes.
  // Honored ONLY where `resolveUnlockBlock` proved a way back exists, so an
  // acknowledgement can never be the thing that strands a set (#3043).
  if (acknowledgeNoClips && acknowledgeable) {
    console.log(`🔓 sprite walk unlock acknowledged without re-derivable clips for ${recordId} · ${stranded.join(', ') || 'set-level import'}`);
    return;
  }
  // "no directions to examine" is the set-level-marker case: an empty or
  // already-re-anchored `directions` map behind a copied selectionPath, where
  // there is no per-direction evidence either way.
  // The "reopen them one at a time" pointer is offered only when some direction
  // actually HAS a clip — for a wholly clipless set that advice names an empty
  // list, and (since the acknowledgement landed) would be strictly worse than the
  // button beside it.
  const partial = stranded.length && stranded.length < importedWalkDirections(walkSet).length;
  const detail = stranded.length
    ? `Unlocking re-opens every direction, and ${stranded.join(', ')} would be left with no source clip to re-derive from and no packaged frames to re-approve — so ${stranded.length === 1 ? 'it' : 'they'} could not be brought back by re-deriving.${partial ? ' Reopen the directions that do have clips one at a time instead.' : ''}`
    : 'This walk set was imported from the source pipeline and carries no directions that can be re-derived here.';
  throw notReDerivable(detail, { regenerable: acknowledgeable });
}

/**
 * Why a walk re-open action is (or is not) blocked for a scope, and whether that
 * block can be acknowledged past. Set-wide unlock passes every imported
 * direction; per-direction reopen passes one direction. One resolver for both
 * gates and the reads clients render, so the button they offer and the 409 they
 * might hit are computed from the same evidence rather than two copies of the
 * rule.
 *
 * `blocked` is its own field rather than something a reader infers from
 * `stranded`: the evidence-free set-level-marker case IS blocked and strands an
 * EMPTY list, so `stranded.length` would read that as "fine" — the exact
 * empty-vs-absent conflation the repo's sentinel rule exists to prevent.
 * `acknowledgeable` says whether regeneration is a real way back, resolved
 * through the render path's own precondition (`resolveWalkRenderability`).
 *
 * `clipByDirection` lets a caller that has ALREADY resolved every approved
 * direction's clip hand that evidence over instead of paying for it twice —
 * `getWalkState` stamps this field and had just done exactly that work. Omit it
 * and the clips are resolved here, which is what the write path does.
 *
 * Returns a fresh object per call: this value is stamped onto a walk-state
 * response, so a hoisted shared constant would be one downstream mutation away
 * from poisoning every later response process-wide.
 */
/**
 * Which of `scope` has no clip to re-derive from, using a caller's pre-resolved
 * clip map where it covers a direction and probing disk where it doesn't.
 *
 * The partition is the whole point. `getWalkState` builds its map from the runs
 * it resolved, and it only resolves entries whose status is `approved` — while
 * `importedWalkDirections` filters on provenance alone and so includes entries
 * in any state. So a direction can be legitimately absent from the map, and
 * reading absent as "proven to have no clip" is the repo's own absent-vs-empty
 * conflation: a `pending` source-anchored entry whose clip is sitting on disk
 * would be reported stranded, and the client would either quote the user eight
 * needless renders or (with an unlocked anchor anywhere) hide the unlock
 * entirely — re-creating, through a different door, the dead end #3043 removes.
 * `in` distinguishes resolved-false from unresolved; the probe answers the rest.
 */
async function strandedDirections(recordId, walkSet, scope, clipByDirection) {
  if (!clipByDirection) return directionsWithoutClip(recordId, walkSet, scope);
  const unresolved = scope.filter((direction) => !(direction in clipByDirection));
  const probed = new Set(unresolved.length
    ? await directionsWithoutClip(recordId, walkSet, unresolved)
    : []);
  // Filtered over `scope` rather than concatenated, so the reported order stays
  // the walk set's own — it is read aloud in the refusal message.
  return scope.filter((direction) => (direction in clipByDirection
    ? !clipByDirection[direction]
    : probed.has(direction)));
}

async function resolveUnlockBlock(
  recordId,
  walkSet,
  clipByDirection = null,
  scope = importedWalkDirections(walkSet),
) {
  const notBlocked = { blocked: false, stranded: [], acknowledgeable: false };
  const imported = importedWalkDirections(walkSet);
  // A source selection pointer with no source-packaged entry is the legacy
  // evidence-free import shape. It is set-level for unlock (all eight directions
  // must be renderable) and one-direction for reopen; once any explicit source
  // entry exists, a native direction in the same mixed set is not blocked by a
  // different direction's provenance.
  const stale = scope.filter((direction) => imported.includes(direction));
  const setLevelImport = isSourcePipelinePath(walkSet?.selectionPath);
  if (!stale.length && (!setLevelImport || imported.length)) return notBlocked;
  // `resolveWalkRenderability` is deliberately I/O-free, so it checks the
  // manifest's CLAIM that an anchor is locked but not that the file is still
  // there — and the render path's own `ANCHOR_MISSING` probe does. A manifest
  // that still marks a since-deleted anchor locked would therefore pass the
  // gate, drop all eight approvals on the acknowledged unlock, and then fail
  // every Generate — precisely the stranding the acknowledgement promises can't
  // happen. So the promise is only made after probing the files too. Bounded at
  // eight stats, and only on the blocked path.
  const regenerable = async (scope) => {
    const [manifest, record] = await Promise.all([loadManifest(recordId), getRecord(recordId)]);
    const resolved = scope.map((direction) => resolveWalkRenderability(manifest, record, direction));
    if (resolved.some((r) => r.error)) return false;
    const present = await Promise.all(resolved
      .map((r) => pathExists(resolveSpriteAssetPath(recordId, r.anchor.path))));
    return present.every(Boolean);
  };
  // No per-direction evidence to examine: unlock re-opens the whole set, while a
  // reopen has already supplied its one-direction scope. Each action only promises
  // regeneration for exactly what it will re-open.
  if (!stale.length) {
    const regenerationScope = scope.length ? scope : SPRITE_DIRECTIONS;
    return { blocked: true, stranded: [], acknowledgeable: await regenerable(regenerationScope) };
  }
  const stranded = await strandedDirections(recordId, walkSet, stale, clipByDirection);
  if (!stranded.length) return notBlocked;
  return { blocked: true, stranded, acknowledgeable: await regenerable(stranded) };
}

/**
 * Reopen's one-direction use of the shared scope resolver. `walkState` is the
 * frozen set when present, otherwise the editable selection; that selection keeps
 * source-packaged entries after an earlier reopen, so later directions are still
 * protected and offered the same acknowledged regeneration escape.
 */
async function assertDirectionReDerivable(recordId, walkState, direction, { acknowledgeNoClips = false } = {}) {
  const { blocked, acknowledgeable } = await resolveUnlockBlock(
    recordId,
    walkState,
    null,
    [direction],
  );
  if (!blocked) return;
  if (acknowledgeNoClips && acknowledgeable) {
    console.log(`🔓 sprite walk reopen acknowledged without a re-derivable clip for ${recordId}/${direction}`);
    return;
  }
  throw notReDerivable(
    `The ${direction} direction is still packaged by the source pipeline and has no source clip on disk — reopening would leave nothing to re-derive from and its packaged frames were never imported.`,
    {
      regenerable: acknowledgeable,
      acknowledgement: `re-open ${direction} and regenerate it from its locked anchor instead (one new render)`,
    },
  );
}

// Un-finalize: drop the canonical "finalized" signal (the walk-set file) FIRST,
// then downgrade the record status — the exact inverse of finalize's order, so a
// crash mid-unfinalize can only leave a cosmetic stale status, never a
// walk-complete record with no frozen set behind it. Shared by unlock (re-opens
// all directions) and reopen (re-opens one).
async function dropFinalizedWalkSet(recordId, recordStatus = 'reference-complete') {
  await rmGuarded(join(spriteDir(recordId), walkSetRelPath(recordId)), { force: true });
  await updateRecord(recordId, { status: recordStatus });
}

async function unlockWalkSetImpl(recordId, { acknowledgeNoClips = false } = {}) {
  await requireCharacter(recordId);
  const walkSet = await loadWalkSet(recordId);
  if (!walkSet) {
    throw new ServerError('No finalized walk set to unlock', { status: 409, code: 'WALK_SET_NOT_FINAL' });
  }
  await assertSetReDerivable(recordId, walkSet, { acknowledgeNoClips });
  // Validate the selection before removing the intact finalized authority.
  const previous = await loadSelection(recordId);
  await dropFinalizedWalkSet(recordId);
  // Seed a fresh (empty) selection so EVERY direction re-opens: with the walk
  // set gone each direction would still read `approved` from the old selection
  // and keep the generate/regenerate buttons gated off, so reset it. The
  // rendered runs remain on disk, so re-approval is a single click per direction.
  // The set's pinned cycle targets survive: unlocking revises the SAME set, and
  // dropping them would silently re-derive a target from whatever direction the
  // user happened to re-approve first.
  await atomicWrite(join(spriteDir(recordId), selectionRelPath(recordId)), {
    ...seedSelection(recordId),
    animationTargets: previous?.animationTargets || {},
  });
  console.log(`🔓 sprite walk set unlocked for ${recordId}`);
  return getWalkState(recordId);
}

/**
 * Re-open ONE approved direction so it returns to the generate / regenerate /
 * reprocess / approve flow — without disturbing the other directions' approvals.
 *
 * This is the finer-grained sibling of unlockWalkSet: the user notices one walk
 * is too fast (or wrong) and wants to redo just that direction. Removing a
 * direction's approval necessarily un-finalizes a frozen set (a walk set is
 * "final" only when all 8 are approved), so when a walk-set file exists we drop
 * it and downgrade the record status the same way unlock does — but we keep
 * every OTHER direction's selection entry intact, so re-freezing is a single
 * re-approval of the one direction rather than all eight. The rendered clip is
 * preserved on disk, so the reopened direction can be reprocessed at a new
 * speed/frame-count with no regeneration. A clipless source-packaged direction
 * requires an acknowledgement only when the shared resolver proves a locked
 * anchor can provide its fresh-render recovery.
 */
export function reopenWalkDirection(recordId, { direction, acknowledgeNoClips = false }) {
  return withBackupAssetPublication(() => walkWriteTail(
    recordId, () => reopenWalkDirectionImpl(recordId, direction, { acknowledgeNoClips }),
  ));
}

/**
 * Drop the approval for a walk whose conditioning anchor is being revised.
 *
 * This differs from the user's "reopen walk" action: a stale walk must be
 * discarded even when an imported run has no source clip, because the next
 * valid action is a fresh generation from the replacement anchor. The old run
 * stays on disk; only its approval pointer is removed.
 */
export function invalidateWalkDirectionForAnchorRevision(recordId, { direction }) {
  return withBackupAssetPublication(() => walkWriteTail(
    recordId, () => invalidateWalkDirectionForAnchorRevisionImpl(recordId, direction),
  ));
}

/**
 * Reopen a directional anchor and invalidate the walk conditioned on it.
 *
 * Preflight before touching the dependent selection, then remove the stale
 * approval before clearing the anchor pointer. If the reference write fails,
 * the safe partial state has no approved walk claiming a stale source; rendered
 * runs and the old locked anchor file both remain recoverable.
 */
export async function unlockDirectionalAnchor(recordId, { direction }) {
  await assertReferenceAnchorUnlockable(recordId, { direction });
  const walkInvalidated = await invalidateWalkDirectionForAnchorRevision(recordId, { direction });
  const tracksInvalidated = await invalidateAnchorDependentTracks(recordId, direction);
  const reference = await unlockReferenceAnchor(recordId, { direction });
  return { ...reference, walkInvalidated, ...tracksInvalidated };
}

/**
 * Drop every non-walk track's approval for one facing, because the anchor those
 * clips were rendered from is being reopened.
 *
 * Iterates the registry rather than naming `scanner`: a stale approved clip whose
 * source image no longer exists would let the atlas compile frames drawn from it,
 * so leaving a second anchor-seeded track out of this loop is silent bad pixels
 * in a published atlas with no error anywhere. Only anchor-seeded tracks are
 * affected — a main-seeded one has no dependency on a directional anchor.
 *
 * Returns `{ tracksInvalidated: { <trackId>: bool }, scannerInvalidated }`; the
 * scalar is kept because `ReferenceWorkflow.jsx` and the route tests read it.
 */
async function invalidateAnchorDependentTracks(recordId, direction) {
  const tracksInvalidated = {};
  for (const row of anchorSeededTracks()) {
    // eslint-disable-next-line no-await-in-loop -- ordered: each track's selection write settles before the next
    tracksInvalidated[row.id] = await invalidateTrackDirectionForAnchorRevision(row.id, recordId, { direction });
  }
  return { tracksInvalidated, scannerInvalidated: tracksInvalidated[SCANNER_TRACK] ?? false };
}

/**
 * Every non-walk track seeded from a directional anchor — the ones a reference
 * anchor revision invalidates. Walk is excluded because it owns its own
 * invalidation path above.
 */
const anchorSeededTracks = () => {
  const tracks = getEffectiveAnimationTracks();
  return Object.values(tracks)
    .filter((row) => row.id !== WALK_TRACK && sourceReferenceFor(row.id, tracks) === 'anchor');
};

/**
 * Reopen the main (south) reference and invalidate only animations conditioned
 * on it. The locked turnaround and every non-south anchor remain usable.
 */
export async function unlockMainReference(recordId) {
  await assertReferenceMainUnlockable(recordId);
  const direction = 'south';
  const walkInvalidated = await invalidateWalkDirectionForAnchorRevision(recordId, { direction });
  const tracksInvalidated = await invalidateAnchorDependentTracks(recordId, direction);
  const reference = await unlockReferenceMain(recordId);
  return { ...reference, walkInvalidated, ...tracksInvalidated };
}

/**
 * Reopen the turnaround and invalidate every approved walk descended from it.
 *
 * The reference preflight runs before any dependent state is touched. Approved
 * walks are then removed under one walk write tail before the reference layer
 * clears the turnaround, main, and anchor pointers. Old reference PNGs, clips,
 * packaged strips, and runtime atlases remain as versioned history.
 */
export async function unlockTurnaroundReference(recordId) {
  await assertReferenceTurnaroundUnlockable(recordId);
  const walkInvalidatedDirections = await invalidateWalkForTurnaroundRevision(recordId);
  // Same registry sweep as the per-anchor path, across every facing: a
  // regenerated turnaround resets the whole identity chain, so no anchor-seeded
  // track may keep an approval descended from the old sheet.
  const tracksInvalidatedDirections = {};
  for (const row of anchorSeededTracks()) {
    // eslint-disable-next-line no-await-in-loop -- ordered: each track's selection write settles before the next
    tracksInvalidatedDirections[row.id] = await invalidateTrackForTurnaroundRevision(row.id, recordId);
  }
  const reference = await unlockReferenceTurnaround(recordId);
  return {
    ...reference,
    walkInvalidatedDirections,
    tracksInvalidatedDirections,
    scannerInvalidatedDirections: tracksInvalidatedDirections[SCANNER_TRACK] ?? [],
  };
}

function invalidateWalkForTurnaroundRevision(recordId) {
  return withBackupAssetPublication(() => walkWriteTail(recordId, async () => {
    const invalidated = [];
    for (const direction of SPRITE_DIRECTIONS) {
      if (await invalidateWalkDirectionForAnchorRevisionImpl(recordId, direction)) {
        invalidated.push(direction);
      }
    }
    return invalidated;
  }));
}

async function invalidateWalkDirectionForAnchorRevisionImpl(recordId, direction) {
  await requireCharacter(recordId);
  const [walkSet, loaded] = await Promise.all([loadWalkSet(recordId), loadSelection(recordId)]);
  const approved = loaded?.directions?.[direction] || walkSet?.directions?.[direction];
  if (approved?.status !== 'approved') return false;

  const selection = loaded || {
    ...seedSelection(recordId),
    directions: { ...(walkSet?.directions || {}) },
  };
  if (walkSet) await dropFinalizedWalkSet(recordId, 'reference');
  delete selection.directions[direction];
  selection.status = 'in-progress';
  await ensureDir(join(spriteDir(recordId), 'walk'));
  await atomicWrite(join(spriteDir(recordId), selectionRelPath(recordId)), selection);
  // Preserve the run as reviewable history, but remove its candidate status so
  // the UI and approval endpoint cannot promote an animation conditioned on
  // the superseded anchor. Redraw-manifest imports have no mutable run record;
  // once their selection pointer is gone they are no longer addressable here.
  const runDirRel = runDirOfPath(entryLayoutPath(recordId, approved));
  if (runDirRel) {
    const found = await resolveRunAt(recordId, runDirRel);
    if (found?.run?.direction === direction) {
      await saveRunRecordAt(recordId, {
        ...found.run,
        status: 'superseded-anchor',
        supersededAt: new Date().toISOString(),
        supersededReason: 'directional-anchor-revised',
      }, found.runDirRel);
    }
  }
  console.log(`♻️ sprite walk direction ${recordId}/${direction} invalidated after anchor revision`);
  return true;
}

async function reopenWalkDirectionImpl(recordId, direction, { acknowledgeNoClips = false } = {}) {
  await requireCharacter(recordId);
  const [walkSet, loaded] = await Promise.all([loadWalkSet(recordId), loadSelection(recordId)]);
  const selection = loaded || seedSelection(recordId);
  // The frozen set is canonical until the first reopen; afterwards its editable
  // selection retains the source-path entry the scope resolver reads.
  await assertDirectionReDerivable(recordId, walkSet || selection, direction, { acknowledgeNoClips });
  if (selection.directions?.[direction]?.status !== 'approved') {
    throw new ServerError(`Direction ${direction} is not approved`, { status: 409, code: 'DIRECTION_NOT_APPROVED' });
  }
  // If the set was finalized, un-finalize it FIRST (a set is "final" only when
  // all 8 are approved) — keeping every OTHER direction's approval intact, so
  // re-freezing is a single re-approval rather than all eight.
  if (walkSet) await dropFinalizedWalkSet(recordId);
  delete selection.directions[direction];
  selection.status = 'in-progress';
  await ensureDir(join(spriteDir(recordId), 'walk'));
  await atomicWrite(join(spriteDir(recordId), selectionRelPath(recordId)), selection);
  console.log(`🔓 sprite walk direction ${recordId}/${direction} reopened`);
  return getWalkState(recordId);
}

async function approveWalkDirectionImpl(recordId, { direction, runId }) {
  await requireCharacter(recordId);
  await requireUnfinalized(recordId);
  // Layout-aware, like the rerun above: a re-derived import stays in the run
  // directory it was imported into, and its approval must record THAT path.
  const found = await resolveWalkRunById(recordId, runId);
  if (!found) throw new ServerError(`Unknown walk run: ${runId}`, { status: 404, code: 'RUN_NOT_FOUND' });
  const { run, runDirRel } = found;
  if (run.direction !== direction) {
    throw new ServerError(`Run ${runId} animates "${run.direction}", not "${direction}"`, { status: 400, code: 'RUN_DIRECTION_MISMATCH' });
  }
  if (run.status !== 'candidate' || !run.postprocessManifest) {
    throw new ServerError('Run has no packaged candidate to approve', { status: 409, code: 'RUN_NOT_CANDIDATE' });
  }
  // A candidate is valid only for the exact locked anchor that conditioned its
  // render. Native runs carry the anchor hash; imported legacy runs may not, so
  // retain their existing compatibility path while still requiring a current
  // locked anchor. This backstops the revision flow even if an old candidate
  // remains addressable outside the normal UI.
  const referenceManifest = await loadManifest(recordId);
  const currentAnchor = lockedAnchorFor(referenceManifest, direction);
  if (!currentAnchor) {
    throw new ServerError(`Lock the ${anchorIdForDirection(direction)} anchor before approving its walk`, { status: 409, code: 'ANCHOR_NOT_LOCKED' });
  }
  if (run.anchorSha256) {
    const currentAnchorSha256 = currentAnchor.sha256
      || await sha256File(resolveSpriteAssetPath(recordId, currentAnchor.path));
    if (run.anchorSha256 !== currentAnchorSha256) {
      throw new ServerError('This walk was rendered from an older directional anchor — generate a new walk from the current anchor', { status: 409, code: 'RUN_ANCHOR_STALE' });
    }
  }
  // Tamper check: the packaged manifest and strip must still be on disk with
  // self-consistent geometry before their approval is frozen into the selection.
  // Frame count / fps are no longer pinned to a single value (variable-frame
  // walks) — instead they must fall inside the supported authoring range and the
  // declared frameCount must match the actual packed frames. Cross-direction
  // consistency against the SET target is enforced below (#2985); atlas.js keeps
  // its own compile-time check as the backstop for imported/legacy sets.
  // `resolveRunById` deliberately returns the RAW record (its results flow into
  // saveRunRecordAt elsewhere, and an imported manifest's bytes are hash-pinned
  // to the source), so re-anchor the repo-anchored path here at the point of use
  // rather than in the loader — same fixup normalizeRunRecord applies to the
  // read-only view (#2978).
  const manifestRel = toRecordRelativeAssetPath(recordId, run.postprocessManifest)
    || run.postprocessManifest;
  const manifestAbs = resolveSpriteAssetPath(recordId, manifestRel);
  // Approval validates this immutable evidence below; it never writes back the fallback.
  const packaged = await readJSONFile(manifestAbs, null);
  const frameCountValid = Number.isInteger(packaged?.frameCount)
    && packaged.frameCount >= WALK_MIN_FRAME_COUNT && packaged.frameCount <= WALK_MAX_FRAME_COUNT
    // If the manifest carries its frames[], they must agree with the declared
    // count (deep per-frame validation happens at atlas compile). A minimal
    // manifest that omits frames[] still approves — the strip sha below is the
    // primary tamper check.
    && (!Array.isArray(packaged.frames) || packaged.frames.length === packaged.frameCount);
  const fpsValid = Number.isFinite(packaged?.frameRate)
    && packaged.frameRate >= WALK_MIN_FPS && packaged.frameRate <= WALK_MAX_FPS;
  if (!packaged || !frameCountValid || !fpsValid
    || packaged.direction !== direction || packaged.characterId !== recordId) {
    throw new ServerError('Packaged run manifest is missing or inconsistent', { status: 409, code: 'RUN_MANIFEST_INVALID' });
  }
  // An imported manifest's OWN stripPath is repo-anchored too — re-anchor before
  // resolving, or the tamper check 409s on a strip that is present and intact.
  const packagedStripRel = toRecordRelativeAssetPath(recordId, packaged.stripPath)
    || packaged.stripPath;
  const stripAbs = resolveSpriteAssetPath(recordId, packagedStripRel);
  if (!await pathExists(stripAbs) || await sha256File(stripAbs) !== packaged.stripSha256) {
    throw new ServerError('Packed strip is missing or was modified after packaging', { status: 409, code: 'RUN_STRIP_INVALID' });
  }
  // The per-frame images the manifest declares must be on disk too. Approval is
  // what freezes this direction into the set the compiler reads, and the compiler
  // verifies every frame's BYTES — so a manifest whose frames were never written
  // here (exactly the shape a source-pipeline import has: its manifest was copied,
  // its frames/ was not) would sail through the strip check above and surface at
  // compile time as an unexplained sha mismatch. Refuse it where the cause is
  // still legible, and name the remedy. This is the SAME frame-validity definition
  // the compiler uses (verifyPackagedFrames) run in its existence-only mode, so
  // the approve gate is a strict prefix of the compile gate and the two can no
  // longer disagree (#3001). A minimal manifest that declares no frames[] is
  // unchanged — the strip sha stays the primary tamper check. (#2993)
  const { total: declaredFrames, missing: missingFrames } = await verifyPackagedFrames(recordId, packaged);
  if (missingFrames) {
    throw new ServerError(
      `${missingFrames} of this run's ${declaredFrames} packaged frames are missing on disk — reprocess the direction from its source clip to re-derive them before approving.`,
      { status: 409, code: 'RUN_FRAMES_MISSING' },
    );
  }

  // Approval — not generation — is the moment a direction's geometry gets frozen
  // into the set the compiler will read, so the target has to hold HERE too. The
  // queue-time gate alone leaves a real hole: retargeting the set mid-run is a
  // sanctioned action, so a user could approve one direction at the old target,
  // retarget, then approve the rest — and only find out at atlas-compile time,
  // which is exactly the failure this issue exists to move earlier.
  const { walkTarget, selection: currentSelection } = await getWalkState(recordId);
  assertWalkTargetMatch(
    walkTarget,
    { frameCount: packaged.frameCount, fps: packaged.frameRate },
    'reprocess this direction',
  );
  await pinDerivedWalkTarget(recordId, walkTarget, currentSelection);

  const selection = (await loadSelection(recordId)) || seedSelection(recordId);
  selection.directions[direction] = {
    status: 'approved',
    runId,
    runPath: runDirRel,
    // Store the re-anchored path: the selection is PortOS-owned state (unlike the
    // hash-pinned imported manifest), and every reader already normalizes it.
    runManifest: manifestRel,
    runManifestSha256: await sha256File(manifestAbs),
    approvedAt: new Date().toISOString(),
  };
  const allApproved = SPRITE_DIRECTIONS.every((d) => selection.directions[d]?.status === 'approved');
  // Freezing is the LAST moment the set can still be fixed, so the per-direction
  // gate above is not sufficient on its own: retargeting mid-set is sanctioned,
  // so a direction approved under the OLD target stays drifted while every later
  // approval matches the new one. Without this check the 8th approval would
  // happily freeze that ragged set and hand the failure to atlas.js — the exact
  // outcome this issue moves earlier. Reuse the drift the state read already
  // computed, minus the direction being approved: its geometry was verified
  // against the target above, and `packagedCyclesFrom` may have resolved a
  // different (newer candidate) run for it, which would otherwise false-block.
  if (allApproved) {
    const drifted = walkTarget.drift.filter((d) => d.direction !== direction);
    if (drifted.length) {
      throw new ServerError(
        `Cannot finalize: ${drifted.map((d) => d.direction).join(', ')} ${drifted.length === 1 ? 'is' : 'are'} `
        + `packaged at a different cycle than the set's ${walkTarget.frameCount} frames @ ${walkTarget.fps}fps `
        + `(${walkTarget.sourceLabel}) — reopen and reprocess ${drifted.length === 1 ? 'it' : 'them'} to the target first.`,
        { status: 409, code: 'WALK_TARGET_MISMATCH' },
      );
    }
  }
  selection.status = allApproved ? 'complete' : 'in-progress';
  const selectionAbs = join(spriteDir(recordId), selectionRelPath(recordId));
  await ensureDir(join(spriteDir(recordId), 'walk'));
  await atomicWrite(selectionAbs, selection);

  if (allApproved) {
    const walkSet = {
      schemaVersion: 1,
      kind: 'finalized-eight-direction-walk-set',
      characterId: recordId,
      status: 'final',
      directionOrder: SPRITE_DIRECTIONS,
      selectionPath: selectionRelPath(recordId),
      selectionSha256: await sha256File(selectionAbs),
      directions: selection.directions,
      finalizedAt: new Date().toISOString(),
    };
    await atomicWrite(join(spriteDir(recordId), walkSetRelPath(recordId)), walkSet);
    // Walk-set before record: the walk-set file is the canonical "finalized"
    // signal (requireUnfinalized and the UI key off it), so a crash between
    // the two leaves only a cosmetic stale record status — the reverse order
    // would advertise walk-complete with no frozen set behind it.
    await updateRecord(recordId, { status: 'walk-complete' });
    console.log(`🏁 sprite walk set finalized for ${recordId}`);
  }
  console.log(`✅ sprite walk ${recordId}/${direction} approved from ${runId}`);
  return getWalkState(recordId);
}