rovecode 0.4.0-beta.3 → 0.4.0

package/src/core/reflection.ts

@@ -0,0 +1,165 @@
+/** Reflection loop for failed edits (port #28) — a BUILT-IN hook set on the hooks-v2 seam
+ *  (core/hooks.ts HookSet: pre_run / post_tool / post_run), attached by cli/runtime.ts as
+ *  "reflection" at createRuntime; core/loop.ts is untouched.
+ *
+ *  Mechanism: when a MUTATING tool (hashline edit / write) FAILS — or succeeds but carries the LSP
+ *  gate's diagnostics note (coding/lsp.ts formatGateNote) — post_tool pushes ONE nudge into the
+ *  runtime's SteeringQueue. The loop drains steering at the next turn start as a user message
+ *  (core/loop.ts "steering drain point"), so the model's next request carries the failed tool_result
+ *  AND a user-visible `reflection: …` message: re-read, fix, retry, or say why it cannot be fixed.
+ *  That IS aider's reflected_message — the edit-failure / lint / test text becomes the next user
+ *  message and the model gets a bounded number of tries.
+ *
+ *  Bounds (pure: no I/O, no clock, never touches the tool output — hashline's text is already the
+ *  actionable one, describeEditFailure):
+ *  - per-run cap: DEFAULT_REFLECTION_MAX (2) nudges per runId, ROVECODE_REFLECTION_MAX overrides (aider
+ *    max_reflections = 3, base_coder.py:101); reset on pre_run (aider init_before_message resets
+ *    reflected_message / num_reflections per user message, base_coder.py:864-871)
+ *  - identical consecutive failures never re-nudge — repetition is the loop guard's territory
+ *    (core/guardrails.ts keeps firing: post_tool runs AFTER the guard's result pass, and a stubbed
+ *    call never reaches post_tool at all); the guard's own `[loop-guard]` warn suffix is stripped
+ *    before comparing, so a warned repeat still counts as identical
+ *  - never for an aborted result (ABORTED_TOOL_RESULT), never for non-mutating tools, never for a
+ *    clean success (which also ends the "consecutive" streak — the next identical failure is new)
+ *  - a nudge the loop never drained (budget / abort right after the failing call) is swept out of
+ *    the queue at the run boundary (post_run, and pre_run of the next run) so it cannot open the
+ *    next run's first turn; other steering messages (port #26 task notes) are preserved
+ *  - ROVECODE_REFLECTION=0 → the set is not registered (cli/runtime.ts door)
+ *  - ownership (fix-wave 4, #26 MED-A): ONE set serves ONE queue, so it acts only on runs it OWNS
+ *    (opts.owns; cli/runtime.ts binds it to `ctx.sessionId === the ACTIVE session store's id`, which
+ *    TUI session switches keep current via setSessionStore). Background-task children (port #26) run
+ *    under the runtime's hooks since 0cf2992 with their OWN store ids: before this, a child's failed
+ *    edit nudged the PARENT's next turn about an edit it never made, and a child's run boundary
+ *    swept the parent's own pending nudge. Trade-off: children get NO reflection (a child's queue is
+ *    unreachable from a hook — HookCtx carries no queue handle on purpose, hooks.ts header); their
+ *    loop guard still bounds identical repeats and their failure text reaches the parent through the
+ *    task note / `task_status result`.
+ *
+ *  Source (pattern only, no code copied; Apache-2.0, credited in THIRD_PARTY_NOTICES.md): aider
+ *  @ 5dc9490 aider/coders/base_coder.py — run_one :924-944 (`while message: self.reflected_message
+ *  = None; … if not self.reflected_message: break; if self.num_reflections >= self.max_reflections:
+ *  tool_warning("Only N reflections allowed, stopping."); return; self.num_reflections += 1;
+ *  message = self.reflected_message`), apply_updates :2296-2328 (an edit-format / apply error →
+ *  `self.reflected_message = str(err)`), lint / test errors as the reflected message :1596-1623;
+ *  editblock_coder.py:84-124 the actionable failed-block report the message carries.
+ *  Deviations: the nudge rides the steering queue (the only way a hook can add a user message), the
+ *  cap is 2 with the loop guard as the second bound, identical repeats are deduped, not re-sent. */
+
+import type { HookCtx, HookSet } from "./hooks.ts";
+import type { SteeringQueue } from "./loop.ts";
+import { ABORTED_TOOL_RESULT } from "./tools.ts";
+
+export const DEFAULT_REFLECTION_MAX = 2;
+/** chars of the tool's error text carried in a failure nudge */
+export const REFLECTION_ERROR_CHARS = 300;
+/** chars of the diagnostics list carried in a diagnostics nudge */
+export const REFLECTION_DIAG_CHARS = 400;
+export const REFLECTION_PREFIX = "reflection: ";
+/** the mutating tools watched by default — hashline's edit + write (kind "write") */
+export const DEFAULT_REFLECTION_TOOLS: readonly string[] = ["edit", "write"];
+const MAX_DIAG_LINES = 5;
+const MAX_TRACKED_RUNS = 8;
+const REMEDY = "Re-read the file, fix the anchors/content, and retry; if it cannot be fixed, say why and stop.";
+/** the loop guard's warn suffix — core/tools.ts dispatch appends `\n\n[loop-guard] …` to the output */
+const GUARD_NOTE = /\n\n\[loop-guard\] [\s\S]*$/;
+/** coding/lsp.ts formatGateNote: `\n\nlsp-gate (<server>): N error(s) in <path> — fix before proceeding:\n<lines>` */
+const LSP_NOTE = /\n\nlsp-gate \([^)\n]*\): \d+ error\(s\) in [^\n]* — fix before proceeding:\n([\s\S]*)$/;
+
+export interface ReflectionOptions {
+  /** the runtime's ONE steering queue (cli/runtime.ts rt.steering) — the nudge lands on the next turn */
+  steering: Pick<SteeringQueue, "push" | "drainAll">;
+  /** nudges per run; default reflectionMax() (ROVECODE_REFLECTION_MAX → 2) */
+  max?: number;
+  /** tool names treated as mutating; default DEFAULT_REFLECTION_TOOLS */
+  tools?: Iterable<string>;
+  /** observer for every nudge pushed (tests, surfaces) */
+  onNudge?: (text: string) => void;
+  /** which runs this set serves — false → pre_run / post_run / post_tool return at once (no nudge, no
+   *  sweep, no per-run state). Default: every run. cli/runtime.ts: the active session store's runs. */
+  owns?: (ctx: HookCtx) => boolean;
+}
+
+/** ROVECODE_REFLECTION=0 disables the built-in set; anything else (incl. unset) enables it. */
+export function reflectionEnabled(env: Record<string, string | undefined> = process.env): boolean {
+  return env["ROVECODE_REFLECTION"] !== "0";
+}
+
+/** ROVECODE_REFLECTION_MAX: a non-negative integer (0 = attached but silent); blank/invalid → default. */
+export function reflectionMax(env: Record<string, string | undefined> = process.env): number {
+  const raw = (env["ROVECODE_REFLECTION_MAX"] ?? "").trim();
+  if (raw === "") return DEFAULT_REFLECTION_MAX;
+  const v = Number(raw);
+  return Number.isFinite(v) && v >= 0 ? Math.floor(v) : DEFAULT_REFLECTION_MAX;
+}
+
+interface RunState { nudges: number; lastKey: string | null }
+
+export function createReflectionHooks(opts: ReflectionOptions): HookSet {
+  const max = opts.max ?? reflectionMax();
+  const owns = opts.owns ?? ((): boolean => true);
+  const watched = new Set(opts.tools ?? DEFAULT_REFLECTION_TOOLS);
+  const runs = new Map<string, RunState>(); // runId → state; bounded (bare dispatch has no runId → "")
+  const pending = new Set<string>(); // nudges pushed this run that the loop may not have drained yet
+  const keyOf = (ctx: HookCtx): string => ctx.runId ?? "";
+  const fresh = (): RunState => ({ nudges: 0, lastKey: null });
+  const stateFor = (ctx: HookCtx): RunState => {
+    const k = keyOf(ctx);
+    let s = runs.get(k);
+    if (s === undefined) {
+      s = fresh();
+      runs.set(k, s);
+      if (runs.size > MAX_TRACKED_RUNS) runs.delete(runs.keys().next().value!); // oldest first
+    }
+    return s;
+  };
+  /** run boundary: drop OUR undrained nudges, keep everything else in queue order */
+  const sweep = (): void => {
+    if (pending.size === 0) return;
+    for (const s of opts.steering.drainAll()) if (!pending.has(s)) opts.steering.push(s);
+    pending.clear();
+  };
+  return {
+    pre_run(ctx) { if (!owns(ctx)) return; sweep(); runs.set(keyOf(ctx), fresh()); },
+    post_run(ctx) { if (!owns(ctx)) return; sweep(); runs.delete(keyOf(ctx)); },
+    post_tool(ctx, call, result) {
+      if (!owns(ctx) || !watched.has(call.tool)) return;
+      const st = stateFor(ctx);
+      const core = result.output.replace(GUARD_NOTE, "");
+      const diag = result.ok ? diagnosticsOf(core) : null;
+      if (result.ok && diag === null) { st.lastKey = null; return; } // clean success: the streak ends
+      if (!result.ok && isAborted(core)) return;
+      const key = `${call.tool}\n${diag ?? core}`;
+      if (st.lastKey === key) return; // identical consecutive failure: the loop guard's job
+      st.lastKey = key;
+      if (st.nudges >= max) return;
+      st.nudges += 1;
+      const text = diag !== null ? diagnosticsNudge(call.tool, diag) : failureNudge(call.tool, core);
+      opts.steering.push(text);
+      pending.add(text);
+      opts.onNudge?.(text);
+    },
+  };
+}
+
+/** The bounded diagnostics list inside an LSP-gated tool output, or null when the gate note is
+ *  absent (clean output, or a gate that saw warnings only — formatGateNote emits nothing then). */
+export function diagnosticsOf(output: string): string | null {
+  const m = LSP_NOTE.exec(output);
+  if (m === null) return null;
+  const lines = m[1]!.split("\n").filter((l) => l.trim().length > 0);
+  const shown = lines.slice(0, MAX_DIAG_LINES).join("; ") + (lines.length > MAX_DIAG_LINES ? ` … and ${lines.length - MAX_DIAG_LINES} more` : "");
+  return clip(shown, REFLECTION_DIAG_CHARS);
+}
+
+function isAborted(output: string): boolean { return output.startsWith(ABORTED_TOOL_RESULT); }
+
+function failureNudge(tool: string, error: string): string {
+  const excerpt = clip(error.trim(), REFLECTION_ERROR_CHARS).replace(/[.\s]+$/, "");
+  return `${REFLECTION_PREFIX}the ${tool} call failed — ${excerpt}. ${REMEDY}`;
+}
+
+function diagnosticsNudge(tool: string, diag: string): string {
+  return `${REFLECTION_PREFIX}the ${tool} introduced diagnostics — ${diag.replace(/[.\s]+$/, "")}. Fix them or explain.`;
+}
+
+function clip(s: string, max: number): string { return s.length <= max ? s : s.slice(0, Math.max(0, max - 1)) + "…"; }

package/src/core/sandbox-config.ts

@@ -0,0 +1,167 @@
+/** Sandbox rung configuration (PORT #27): makes the port-#10 executor ladder
+ *  SELECTABLE in production — closes the #10 G7 residual ("no production
+ *  selector; getExecutor() lazily returns direct").
+ *
+ *  Pattern source: openai/codex, Apache-2.0 (snapshot research/source_snapshots/
+ *  openai-codex @ 379d50be), ported at pattern level, no code copied:
+ *  - the tier is a CONFIG CHOICE layered as file < override: config.toml
+ *    `sandbox_mode = "…"` (app-server/tests/common/config.rs:140) with the
+ *    `--sandbox` flag mapped onto the same SandboxMode enum
+ *    (utils/cli/src/shared_options.rs:40-41, utils/cli/src/sandbox_mode_cli_arg.rs:14-25).
+ *    Here: `.rovecode/sandbox.json` < `ROVECODE_SANDBOX` env (rovecode has no per-run CLI
+ *    flag for this; env is the override layer, as for every other ROVECODE_* knob);
+ *  - an explicitly requested but unprovidable tier is a HARD ERROR
+ *    (sandboxing/src/manager.rs:203-222) — the executor seam already refuses
+ *    to fall DOWN the ladder (RungUnavailableError); this module turns that
+ *    refusal into a ONE-LINE startup error every entrypoint can print.
+ *
+ *  Deliberate deviation from the modes.json idiom (src/core/modes.ts
+ *  loadModesConfig "config can never crash startup"): a malformed sandbox file
+ *  or an unknown rung is an ERROR, not a default. Degrading a misspelt "wsl"
+ *  to `direct` would be exactly the silent fallback down the ladder that #10
+ *  forbids — the user asked for isolation and would silently not get it.
+ *
+ *  Rungs are `direct` | `wsl` | `docker` only. bubblewrap/seatbelt are not
+ *  rungs on this harness (Windows-first; codex's bwrap tier has no analogue).
+ *
+ *  Scope: consumed by createRuntime (src/cli/runtime.ts) — the ONE runtime
+ *  construction behind tui/run/repl/acp/serve. The gauntlet runner
+ *  (src/eval/gauntlet-runner.ts) registers tools directly and never builds a
+ *  runtime, so `rovecode gauntlet` stays on the lazy `direct` seam regardless of
+ *  the cwd's sandbox config (by design: the eval suite measures the loop, not
+ *  the machine's WSL/Docker state). The executor seam is process-wide (#10):
+ *  in a multi-session process (serve/acp) the most recently booted session's
+ *  rung is the one every bash call uses. */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_DOCKER_IMAGE, RUNGS, RungUnavailableError, type Rung } from "./executor.ts";
+
+export type SandboxSource = "default" | "file" | "env";
+
+export interface SandboxConfig {
+  rung: Rung;
+  /** docker rung image (must contain bash); resolved to DEFAULT_DOCKER_IMAGE for
+   *  the docker rung when nothing configures it; a file-provided image is kept
+   *  verbatim for other rungs (informational) */
+  dockerImage?: string;
+  /** where `rung` came from — env beats file beats the direct default */
+  source: SandboxSource;
+}
+
+export const SANDBOX_FILE = ".rovecode/sandbox.json";
+export const SANDBOX_ENV = "ROVECODE_SANDBOX";
+export const SANDBOX_IMAGE_ENV = "ROVECODE_SANDBOX_IMAGE";
+
+const HINT = `fix ${SANDBOX_FILE} or ${SANDBOX_ENV} (default: direct)`;
+
+/** Collapse to ONE line: startup errors are printed verbatim by entrypoints. */
+function oneLine(s: string): string {
+  return s.replace(/\s*[\r\n]+\s*/g, " ").trim();
+}
+
+/** The ONE startup-error class for sandbox selection: bad config (unknown rung,
+ *  malformed file, bad image) AND a configured rung the machine cannot provide.
+ *  `.message` is always a single actionable line — never a stack. */
+export class SandboxConfigError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(oneLine(message), options);
+    this.name = "SandboxConfigError";
+  }
+}
+
+function isRung(v: string): v is Rung {
+  return (RUNGS as readonly string[]).includes(v);
+}
+
+/** Rung names are trimmed + lower-cased ("WSL" is not a typo worth an error). */
+function parseRung(raw: unknown, where: string): Rung {
+  const v = typeof raw === "string" ? raw.trim().toLowerCase() : "";
+  if (isRung(v)) return v;
+  const shown = typeof raw === "string" ? raw : JSON.stringify(raw);
+  return fail(`sandbox rung ${JSON.stringify(String(shown).slice(0, 60))} from ${where} is not a rung — use one of ${RUNGS.join(", ")} (bubblewrap is not a rung on this harness); ${HINT}`);
+}
+
+function parseImage(raw: unknown, where: string): string {
+  if (typeof raw === "string" && raw.trim() !== "") return raw.trim();
+  return fail(`sandbox dockerImage from ${where} must be a non-empty string (e.g. "${DEFAULT_DOCKER_IMAGE}"); ${HINT}`);
+}
+
+function fail(message: string): never {
+  throw new SandboxConfigError(message);
+}
+
+/** Raw file fields; values are validated only where SELECTED (an env override
+ *  makes the file's rung irrelevant), but a file that cannot be parsed at all
+ *  is always an error — intent is unreadable, and "fix or delete" is one step. */
+interface FileFields { rung?: unknown; dockerImage?: unknown; path: string }
+
+function readSandboxFile(cwd: string): FileFields | null {
+  const path = join(cwd, ".rovecode", "sandbox.json");
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === "ENOENT") return null; // no file = default rung
+    return fail(`sandbox config ${path} cannot be read (${e instanceof Error ? e.message : String(e)}) — ${HINT}`);
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (e) {
+    return fail(`sandbox config ${path} is not valid JSON (${e instanceof Error ? e.message : String(e)}) — fix or delete it; ${HINT}`);
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return fail(`sandbox config ${path} must be a JSON object like {"rung":"wsl"} or {"rung":"docker","dockerImage":"${DEFAULT_DOCKER_IMAGE}"}; ${HINT}`);
+  }
+  const o = raw as Record<string, unknown>;
+  return { rung: o.rung, dockerImage: o.dockerImage, path };
+}
+
+/** Resolve the sandbox rung for `cwd`: `ROVECODE_SANDBOX` (rung name) beats
+ *  `<cwd>/.rovecode/sandbox.json` `{ rung, dockerImage }` beats the `direct`
+ *  default; `ROVECODE_SANDBOX_IMAGE` beats the file's dockerImage. Throws
+ *  SandboxConfigError (one line) on an unknown rung, a malformed file, or a
+ *  bad dockerImage — never degrades silently. */
+export function loadSandboxConfig(cwd: string, env: Record<string, string | undefined> = process.env): SandboxConfig {
+  const file = readSandboxFile(cwd);
+  const envRung = env[SANDBOX_ENV]?.trim() ?? "";
+  const envImage = env[SANDBOX_IMAGE_ENV]?.trim() ?? "";
+  let rung: Rung = "direct";
+  let source: SandboxSource = "default";
+  if (envRung !== "") {
+    rung = parseRung(envRung, SANDBOX_ENV);
+    source = "env";
+  } else if (file && file.rung !== undefined) {
+    rung = parseRung(file.rung, file.path);
+    source = "file";
+  }
+  let dockerImage: string | undefined;
+  if (envImage !== "") dockerImage = envImage;
+  else if (file && file.dockerImage !== undefined) dockerImage = parseImage(file.dockerImage, file.path);
+  else if (rung === "docker") dockerImage = DEFAULT_DOCKER_IMAGE;
+  return dockerImage !== undefined ? { rung, dockerImage, source } : { rung, source };
+}
+
+/** Wrap a failed configureExecutor(cfg.rung) into the startup error class:
+ *  the probe detail (why the wrapper could not run `bash -c true`) plus the
+ *  fix, on one line. The original error rides along as `cause`. */
+export function unavailableRungError(cfg: SandboxConfig, cause: unknown): SandboxConfigError {
+  const detail = cause instanceof RungUnavailableError ? cause.detail
+    : cause instanceof Error ? cause.message : String(cause);
+  return new SandboxConfigError(
+    `sandbox rung "${cfg.rung}" (from ${originOf(cfg)}) unavailable: ${detail} — ${HINT}`,
+    { cause },
+  );
+}
+
+function originOf(cfg: SandboxConfig): string {
+  return cfg.source === "env" ? SANDBOX_ENV : cfg.source === "file" ? SANDBOX_FILE : "default";
+}
+
+/** One-line human form for /status: `direct (default)`, `wsl (.rovecode/sandbox.json)`,
+ *  `docker debian:stable-slim (ROVECODE_SANDBOX)`. */
+export function describeSandbox(cfg: SandboxConfig): string {
+  const image = cfg.rung === "docker" ? ` ${cfg.dockerImage ?? DEFAULT_DOCKER_IMAGE}` : "";
+  return `${cfg.rung}${image} (${originOf(cfg)})`;
+}

package/src/core/session-images.ts

@@ -0,0 +1,73 @@
+/** Port #34 image sidecars for the session store (session.ts): the persisted form ↔ the in-memory
+ *  form of a message's image parts.
+ *  Sidecars live at `<session>/attachments/<sha256>.<ext>`, content-addressed (the same image
+ *  attached twice is one file). The store references them from entries.jsonl by ONE canonical
+ *  session-relative form, `attachments/<file>` (forward slash, one segment, not `.`/`..`), and
+ *  resolves that form to an absolute path in memory only, so core/images.ts imageData() can read
+ *  it without knowing the session.
+ *  Path confinement: every other persisted path is foreign and never resolves to a readable file —
+ *  a non-canonical relative path stays relative (F2: `../outside.png` used to hydrate to
+ *  <sessions>/outside.png) and an absolute path is DROPPED (F3: the store never writes one, so a
+ *  persisted absolute path is a tampered or foreign line that would otherwise ship arbitrary
+ *  on-disk bytes to the provider as an image block). imageData()/imageByteSize() decline both, so
+ *  the part lowers to a "file unavailable" placeholder. Consequently the only file a hydrated part
+ *  can name is `<session>/attachments/<one segment>`, whatever entries.jsonl says.
+ *  `rovecode export --json` copies entries.jsonl ALONE — the attachments directory travels with the
+ *  session directory, not with the export (the JSONL stays a small, verbatim-copyable record). */
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { imageExt } from "./images.ts";
+import type { ImagePart, MessagePart } from "./types.ts";
+
+export const ATTACHMENTS_DIR = "attachments";
+
+/** F2 (port #34 hardening): the only persisted sidecar form is `attachments/<file>` — one segment,
+ *  no separators, not `.`/`..`. Anything else is undefined here and left unresolved (hydrateImageParts). */
+export function sidecarFile(persisted: string): string | undefined {
+  const prefix = `${ATTACHMENTS_DIR}/`;
+  if (!persisted.startsWith(prefix)) return undefined;
+  const file = persisted.slice(prefix.length);
+  return file !== "" && file !== "." && file !== ".." && !/[\\/]/.test(file) ? file : undefined;
+}
+
+/** The on-disk form: every inline image (`bytes`) becomes a sidecar file under `dir` and the part
+ *  keeps the session-relative `path` instead — the hash chain covers the path, the content-addressed
+ *  filename covers the bytes. A sidecar that cannot be written (read-only dir, disk full) keeps its
+ *  bytes inline, so nothing is ever dropped. undefined when there is nothing to do. */
+export function sidecarImageParts(dir: string, parts: readonly MessagePart[]): MessagePart[] | undefined {
+  if (!parts.some((p) => p.kind === "image" && p.bytes !== undefined)) return undefined;
+  return parts.map((p) => {
+    if (p.kind !== "image" || p.bytes === undefined) return p;
+    const buf = Buffer.from(p.bytes, "base64");
+    const file = `${createHash("sha256").update(buf).digest("hex")}.${imageExt(p.mime)}`;
+    try {
+      mkdirSync(join(dir, ATTACHMENTS_DIR), { recursive: true });
+      const abs = join(dir, ATTACHMENTS_DIR, file);
+      if (!existsSync(abs)) writeFileSync(abs, buf);
+    } catch {
+      return p; // inline fallback
+    }
+    const out: ImagePart = { kind: "image", mime: p.mime, path: `${ATTACHMENTS_DIR}/${file}` };
+    if (p.width !== undefined) out.width = p.width;
+    if (p.height !== undefined) out.height = p.height;
+    if (p.name !== undefined) out.name = p.name;
+    return out;
+  });
+}
+
+/** The in-memory form: the canonical `attachments/<file>` path → absolute under `dir`; a persisted
+ *  ABSOLUTE path is dropped (F3, header) so the part is unreadable rather than a read of whatever
+ *  file the line names; any other relative path stays as it is (F2). undefined when there is
+ *  nothing to do. */
+export function hydrateImageParts(dir: string, parts: readonly MessagePart[]): MessagePart[] | undefined {
+  const touched = (p: MessagePart): boolean => p.kind === "image" && p.path !== undefined && (isAbsolute(p.path) || sidecarFile(p.path) !== undefined);
+  if (!parts.some(touched)) return undefined;
+  return parts.map((p) => {
+    if (p.kind !== "image" || p.path === undefined) return p;
+    if (isAbsolute(p.path)) { const rest = { ...p }; delete rest.path; return rest; }
+    const file = sidecarFile(p.path);
+    return file === undefined ? p : { ...p, path: join(dir, ATTACHMENTS_DIR, file) };
+  });
+}