pi-precompact 0.0.0-stage → 0.2.0

package/src/card.ts

@@ -0,0 +1,194 @@
+import type { ExtensionContext, KeybindingsManager } from "@earendil-works/pi-coding-agent";
+import { type Component, type TUI, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { Label, StatusDetails } from "./controller.ts";
+import { formatDuration, formatShare, formatTokens } from "./format.ts";
+
+type Theme = ExtensionContext["ui"]["theme"];
+type Color = Parameters<Theme["fg"]>[0];
+type Segment = readonly [text: string, color?: Color];
+
+const MAX_WIDTH = 76;
+const CELLS = 24;
+const LABEL = 10;
+const GLYPH: Record<Label, Segment> = {
+  idle: ["○", "muted"],
+  running: ["◐", "accent"],
+  ready: ["●", "success"],
+  paused: ["‖", "warning"],
+  off: ["–", "dim"],
+  unavailable: ["×", "dim"],
+};
+
+/** What the card can change. The controller implements it. */
+export interface CardActions {
+  details(): StatusDetails;
+  reset(): void;
+  setEnabled(enabled: boolean): void;
+}
+
+/** Context bar with the background start and Pi's threshold as marks. */
+export function gauge(
+  percent: number | null,
+  start: number | undefined,
+  threshold: number | undefined,
+  fill: Color,
+) {
+  const filled = percent === null ? 0 : Math.round((Math.min(Math.max(percent, 0), 100) / 100) * CELLS);
+  const marks = new Map<number, Color>();
+  if (start !== undefined) marks.set(Math.min(CELLS - 1, Math.floor(start * CELLS)), "accent");
+  if (threshold !== undefined) marks.set(Math.min(CELLS - 1, Math.floor(threshold * CELLS)), "error");
+  const segments: Segment[] = [];
+  for (let cell = 0; cell < CELLS; cell++) {
+    const mark = marks.get(cell);
+    if (mark) segments.push(["│", mark]);
+    segments.push(cell < filled ? ["━", fill] : ["─", "dim"]);
+  }
+  return segments;
+}
+
+function contextColor(percent: number | null): Color {
+  if (percent === null) return "dim";
+  return percent > 90 ? "error" : percent > 70 ? "warning" : "text";
+}
+
+function ago(at: number, now: number): string {
+  const ms = now - at;
+  return ms < 60_000 ? "just now" : `${Math.floor(ms / 60_000)} min ago`;
+}
+
+function rows(details: StatusDetails, now: number): Segment[][] {
+  const [glyph, color] = GLYPH[details.label];
+  const label = details.applied && details.label === "idle" ? "applied" : details.label;
+  const out: Segment[][] = [
+    [
+      [glyph, color],
+      [` ${label}`, color],
+      [`   ${details.reason}`, "text"],
+    ],
+    [],
+  ];
+  const context = details.context;
+  if (context) {
+    const percent = context.percent;
+    out.push([
+      ["Context".padEnd(LABEL), "dim"],
+      ...gauge(percent, details.start, details.threshold, color ?? "muted"),
+      [
+        percent === null
+          ? "  unknown until the next response"
+          : `  ${percent.toFixed(1)}% of ${formatTokens(context.window)}`,
+        contextColor(percent),
+      ],
+    ]);
+  }
+  const marks = [
+    details.start === undefined ? undefined : `start ${formatShare(details.start)}`,
+    details.threshold === undefined ? undefined : `Pi compacts at ${formatShare(details.threshold)}`,
+  ].filter((text) => text !== undefined);
+  if (marks.length) out.push([[" ".repeat(LABEL)], [marks.join(" · "), "dim"]]);
+  const job = details.job;
+  const tokens = context?.tokens;
+  if (job?.phase === "running") {
+    out.push([
+      ["Summary".padEnd(LABEL), "dim"],
+      [`preparing for ${formatDuration(now - job.startedAt)}`, "text"],
+    ]);
+  } else if (job?.phase === "ready") {
+    const prepared = ` · prepared in ${formatDuration((job.readyAt ?? now) - job.startedAt)}, ${ago(job.readyAt ?? now, now)}`;
+    out.push([
+      ["Summary".padEnd(LABEL), "dim"],
+      job.estimate === undefined || tokens == null
+        ? ["estimate unavailable", "text"]
+        : [`${formatTokens(tokens)} → ~${formatTokens(job.estimate)} tokens`, "text"],
+      [prepared, "dim"],
+    ]);
+  } else if (details.applied) {
+    const applied = details.applied;
+    out.push([
+      ["Summary".padEnd(LABEL), "dim"],
+      [`applied ${ago(applied.at, now)}`, "text"],
+      [` · ${formatTokens(applied.tokensBefore)} → ~${formatTokens(applied.tokensAfter)} tokens`, "dim"],
+    ]);
+  } else {
+    out.push([
+      ["Summary".padEnd(LABEL), "dim"],
+      ["none", "dim"],
+    ]);
+  }
+  const usage = job?.usage ?? details.applied?.usage;
+  if (usage) {
+    const cost = usage.cost.total > 0 ? ` · $${usage.cost.total.toFixed(3)}` : "";
+    out.push([
+      ["Request".padEnd(LABEL), "dim"],
+      [
+        `${formatTokens(usage.input + usage.cacheRead + usage.cacheWrite)} in · ${formatTokens(usage.output)} out${cost}`,
+        "text",
+      ],
+    ]);
+  }
+  out.push(
+    [
+      ["Failures".padEnd(LABEL), "dim"],
+      [`${details.failures}/2`, "text"],
+    ],
+    [],
+  );
+  out.push([
+    ["r", "accent"],
+    [" reset   ", "dim"],
+    ["o", "accent"],
+    [details.enabled ? " off   " : " on    ", "dim"],
+    ["esc", "accent"],
+    [" close", "dim"],
+  ]);
+  return out;
+}
+
+function paint(theme: Theme, segments: Segment[]): string {
+  return segments.map(([text, color]) => (color ? theme.fg(color, text) : text)).join("");
+}
+
+/** Render the card. Exported for tests; `now` keeps them deterministic. */
+export function renderCard(details: StatusDetails, theme: Theme, width: number, now = Date.now()): string[] {
+  const outer = Math.min(MAX_WIDTH, width);
+  const inner = outer - 4;
+  if (inner < 8) return rows(details, now).map((row) => truncateToWidth(paint(theme, row), width, ""));
+  const title = "─ Precompact ";
+  const border = (text: string) => theme.fg("border", text);
+  const top = border(
+    `╭${truncateToWidth(title, outer - 2, "")}${"─".repeat(Math.max(0, outer - 2 - title.length))}╮`,
+  );
+  const body = rows(details, now).map((row) => {
+    const content = truncateToWidth(paint(theme, row), inner, theme.fg("dim", "…"));
+    return `${border("│ ")}${content}${" ".repeat(Math.max(0, inner - visibleWidth(content)))}${border(" │")}`;
+  });
+  return [top, ...body, border(`╰${"─".repeat(outer - 2)}╯`)];
+}
+
+/** The status card for an explicit `/precompact status`. Resolves when closed. */
+export function statusCard(
+  actions: CardActions,
+  tui: Pick<TUI, "requestRender">,
+  theme: Theme,
+  keybindings: Pick<KeybindingsManager, "matches">,
+  done: () => void,
+): Component & { dispose(): void } {
+  // Elapsed times and state changes appear without input. Stop with the card.
+  const timer = setInterval(() => tui.requestRender(), 1000);
+  timer.unref();
+  return {
+    render: (width) => renderCard(actions.details(), theme, width),
+    invalidate() {},
+    handleInput(data) {
+      if (keybindings.matches(data, "tui.select.cancel") || keybindings.matches(data, "tui.select.confirm")) {
+        done();
+        return;
+      }
+      if (data === "r") actions.reset();
+      else if (data === "o") actions.setEnabled(!actions.details().enabled);
+      else return;
+      tui.requestRender();
+    },
+    dispose: () => clearInterval(timer),
+  };
+}

package/src/controller.ts

@@ -0,0 +1,446 @@
+import {
+  buildSessionProjection,
+  type CompactionResult,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type SessionBeforeCompactEvent,
+  type SessionBeforeCompactResult,
+  type SessionCompactEvent,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import { inheritOwnFiles, isFileDetails } from "./files.ts";
+import { STATUS_KEY } from "./footer.ts";
+import { formatDuration, formatTokens } from "./format.ts";
+import type { NativeCompaction } from "./native.ts";
+import { fingerprint, type Snapshot, snapshotValid, validateResult } from "./validation.ts";
+
+export interface Options {
+  startRatio: number;
+  minimumTokens: number;
+  timeoutMs: number;
+}
+export const DEFAULT_OPTIONS: Readonly<Options> = {
+  startRatio: 0.85,
+  minimumTokens: 64_000,
+  timeoutMs: 120_000,
+};
+type State = "idle" | "running" | "ready" | "paused" | "disabled";
+/** The state shown in the footer and the status card. */
+export type Label = "idle" | "running" | "ready" | "paused" | "off" | "unavailable";
+type Usage = NonNullable<CompactionResult["usage"]>;
+
+/**
+ * What the footer draws. Shares are fractions of the model's context window.
+ * The plain `precompact: <state>` status text stays the fallback for other footers.
+ */
+export interface FooterState {
+  state: Label;
+  /** The last compaction used a background summary, and nothing happened since. */
+  applied: boolean;
+  /** Where background preparation starts. */
+  start?: number;
+  /** Where Pi compacts natively. */
+  threshold?: number;
+  /** Estimated context after Pi adopts the held summary (ready only). */
+  after?: number;
+}
+
+export interface Applied {
+  tokensBefore: number;
+  tokensAfter: number;
+  preparedMs: number;
+  waitedMs: number;
+  at: number;
+  usage?: Usage;
+}
+
+/** Everything the status card shows. */
+export interface StatusDetails {
+  label: Label;
+  reason: string;
+  failures: number;
+  enabled: boolean;
+  context?: { tokens: number | null; window: number; percent: number | null };
+  start?: number;
+  threshold?: number;
+  job?: { phase: "running" | "ready"; startedAt: number; readyAt?: number; estimate?: number; usage?: Usage };
+  applied?: Applied;
+}
+
+interface Job {
+  snapshot: Snapshot;
+  controller: AbortController;
+  promise: Promise<CompactionResult | undefined>;
+  result?: CompactionResult;
+  startedAt: number;
+  readyAt?: number;
+  /** Estimated context tokens after adoption, refreshed while the result is held. */
+  estimate?: number;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** The single-line notice after Pi adopted a background summary. */
+export function appliedNotice(applied: Applied): string {
+  const wait = applied.waitedMs < 1000 ? "no wait" : `waited ${formatDuration(applied.waitedMs)}`;
+  return `✓ Background summary applied · ${wait} · ${formatTokens(applied.tokensBefore)} → ~${formatTokens(applied.tokensAfter)} tokens · prepared in ${formatDuration(applied.preparedMs)}`;
+}
+
+/** A bounded wait even if a provider does not settle its promise on abort. */
+export async function untilAborted<T>(promise: Promise<T>, signal: AbortSignal): Promise<T | undefined> {
+  if (signal.aborted) return undefined;
+  let listener = () => {};
+  const abort = new Promise<undefined>((resolve) => {
+    listener = () => resolve(undefined);
+    signal.addEventListener("abort", listener, { once: true });
+  });
+  try {
+    return await Promise.race([promise, abort]);
+  } finally {
+    signal.removeEventListener("abort", listener);
+  }
+}
+
+export class BackgroundCompaction {
+  private job?: Job;
+  private failures = 0;
+  private enabled = true;
+  private last = "Waiting for enough context";
+  private state: State = "idle";
+  private pendingApplied?: Applied;
+  private applied?: Applied;
+  private showApplied = false;
+  private footer?: FooterState;
+
+  constructor(
+    private readonly pi: Pick<ExtensionAPI, "getSettings" | "appendEntry">,
+    private readonly native: NativeCompaction,
+    private readonly options: Options = DEFAULT_OPTIONS,
+  ) {
+    if (
+      !(options.startRatio > 0 && options.startRatio < 1) ||
+      !Number.isFinite(options.minimumTokens) ||
+      options.minimumTokens < 0 ||
+      !Number.isSafeInteger(options.timeoutMs) ||
+      options.timeoutMs < 1
+    )
+      throw new Error("Invalid background compaction options");
+  }
+
+  status(): string {
+    return `${this.enabled ? this.state : "disabled"}: ${this.last} (${this.failures}/2 failures)`;
+  }
+
+  setEnabled(enabled: boolean, ctx: ExtensionContext): void {
+    this.enabled = enabled;
+    this.reset(ctx, enabled ? "Enabled for this session" : "Disabled for this session");
+  }
+
+  reset(ctx: ExtensionContext, reason = "Session changed"): void {
+    this.pendingApplied = undefined;
+    this.discard(ctx, reason);
+    this.failures = 0;
+    this.show(ctx, this.enabled ? "idle" : "disabled", reason);
+  }
+
+  /**
+   * Called on `session_compact`. Returns the notice when Pi adopted this plugin's summary.
+   * The footer keeps the applied mark until the next state change.
+   */
+  compacted(event: SessionCompactEvent, ctx: ExtensionContext): string | undefined {
+    const applied = this.pendingApplied;
+    this.reset(ctx, "Compaction completed");
+    const details = event.compactionEntry.details;
+    if (!applied || !isRecord(details) || details.precompact !== 1) return undefined;
+    this.applied = applied;
+    this.showApplied = true;
+    this.last = "Prepared summary applied";
+    this.refreshStatus(ctx);
+    return appliedNotice(applied);
+  }
+
+  private show(ctx: ExtensionContext, state: State, reason: string): void {
+    this.state = state;
+    this.last = reason;
+    this.showApplied = false;
+    this.refreshStatus(ctx);
+  }
+
+  private label(ctx: ExtensionContext): Label {
+    const settings = SettingsManager.inMemory(this.pi.getSettings()).getCompactionSettings(ctx.model);
+    if (!this.enabled || !settings.enabled) return "off";
+    if (!ctx.model || ctx.model.api === "pi-virtual") return "unavailable";
+    return this.state === "disabled" ? "off" : this.state;
+  }
+
+  /** Start and native threshold as shares of the context window, when known. */
+  private shares(ctx: ExtensionContext, label: Label): { start?: number; threshold?: number } {
+    const model = ctx.model;
+    if (!model || model.api === "pi-virtual" || !(model.contextWindow > 0)) return {};
+    const settings = SettingsManager.inMemory(this.pi.getSettings()).getCompactionSettings(model);
+    const ceiling = model.contextWindow - settings.reserveTokens;
+    if (!settings.enabled || !(ceiling > 0)) return {};
+    const threshold = ceiling / model.contextWindow;
+    return label === "off" ? { threshold } : { start: threshold * this.options.startRatio, threshold };
+  }
+
+  refreshStatus(ctx: ExtensionContext): void {
+    if (ctx.mode !== "tui") return;
+    const label = this.label(ctx);
+    const footer: FooterState = {
+      state: label,
+      applied: label === "idle" && this.showApplied,
+      ...this.shares(ctx, label),
+    };
+    const window = ctx.model?.contextWindow ?? 0;
+    if (label === "ready" && this.job?.estimate !== undefined && window > 0)
+      footer.after = this.job.estimate / window;
+    // Store the footer data first: setStatus triggers the render that reads it.
+    this.footer = footer;
+    ctx.ui.setStatus(STATUS_KEY, `precompact: ${label}`);
+  }
+
+  /** The last footer data; undefined outside the TUI. */
+  footerState(): FooterState | undefined {
+    return this.footer;
+  }
+
+  details(ctx: ExtensionContext): StatusDetails {
+    const label = this.label(ctx);
+    const usage = ctx.getContextUsage();
+    const job = this.job;
+    return {
+      label,
+      reason: this.last,
+      failures: this.failures,
+      enabled: this.enabled,
+      ...(usage
+        ? { context: { tokens: usage.tokens, window: usage.contextWindow, percent: usage.percent } }
+        : {}),
+      ...this.shares(ctx, label),
+      ...(job
+        ? {
+            job: {
+              phase: job.result ? "ready" : "running",
+              startedAt: job.startedAt,
+              readyAt: job.readyAt,
+              estimate: job.estimate,
+              usage: job.result?.usage,
+            },
+          }
+        : {}),
+      ...(this.showApplied && this.applied ? { applied: this.applied } : {}),
+    };
+  }
+
+  /** Preview the held result against the current branch. Undefined means Pi would reject it. */
+  private estimate(job: Job, result: CompactionResult, ctx: ExtensionContext): number | undefined {
+    try {
+      const tokens = ctx.getContextUsage()?.tokens ?? job.snapshot.preparation.tokensBefore;
+      return validateResult(
+        job.snapshot,
+        result,
+        ctx.sessionManager.getBranch(),
+        ctx.model?.contextWindow ?? 0,
+        tokens,
+      )?.estimatedTokensAfter;
+    } catch {
+      return undefined;
+    }
+  }
+
+  private identity(ctx: ExtensionContext): string {
+    const settings = this.pi.getSettings();
+    return fingerprint({
+      model: ctx.model,
+      compaction: settings.compaction,
+      retry: settings.retry,
+      thinking: ctx.thinkingLevel,
+    });
+  }
+
+  private discard(ctx: ExtensionContext, reason: string): void {
+    const job = this.job;
+    this.job = undefined;
+    job?.controller.abort();
+    // Pi's public extension API has no usage-entry writer. Keep known discarded
+    // usage auditable without putting it into the conversation or double counting.
+    if (job?.result?.usage && job.snapshot.sessionId === ctx.sessionManager.getSessionId()) {
+      this.pi.appendEntry("precompact.discarded", { reason, usage: job.result.usage });
+    }
+    this.show(ctx, this.failures >= 2 ? "paused" : "idle", reason);
+  }
+
+  private valid(job: Job, ctx: ExtensionContext): boolean {
+    return snapshotValid(
+      job.snapshot,
+      ctx.sessionManager.getSessionId(),
+      this.identity(ctx),
+      ctx.sessionManager.getBranch(),
+    );
+  }
+
+  /** Called from a persisted turn boundary. This method never awaits the provider. */
+  consider(ctx: ExtensionContext): void {
+    if (!this.enabled) return;
+    const settingsManager = SettingsManager.inMemory(this.pi.getSettings());
+    const model = ctx.model;
+    const settings = settingsManager.getCompactionSettings(model);
+    if (!settings.enabled || !model || model.api === "pi-virtual") {
+      this.discard(ctx, "Native compaction disabled or model unsupported");
+      return;
+    }
+    if (this.job && !this.valid(this.job, ctx)) this.discard(ctx, "Snapshot invalidated");
+    const held = this.job;
+    if (held?.result) {
+      // Newer history stays in the retained tail, so the expected result grows.
+      const estimate = this.estimate(held, held.result, ctx);
+      if (estimate !== held.estimate) {
+        held.estimate = estimate;
+        this.refreshStatus(ctx);
+      }
+    }
+    if (this.job || this.failures >= 2) return;
+    const usage = ctx.getContextUsage();
+    const ceiling = model.contextWindow - settings.reserveTokens;
+    if (
+      !usage ||
+      usage.tokens === null ||
+      !Number.isFinite(usage.tokens) ||
+      usage.tokens < ceiling * this.options.startRatio ||
+      usage.tokens >= ceiling
+    )
+      return;
+    const branch = ctx.sessionManager.getBranch();
+    const measured = buildSessionProjection(branch).messages.findLast(
+      (message) =>
+        message.role === "assistant" && message.stopReason !== "error" && message.stopReason !== "aborted",
+    );
+    if (
+      measured?.role !== "assistant" ||
+      measured.usage.input + measured.usage.cacheRead + measured.usage.cacheWrite < this.options.minimumTokens
+    )
+      return;
+    const preparation = this.native.prepareCompaction(branch, settings);
+    if (!preparation) return;
+    inheritOwnFiles(preparation, branch);
+    const snapshot: Snapshot = {
+      sessionId: ctx.sessionManager.getSessionId(),
+      identity: this.identity(ctx),
+      entryCount: branch.length,
+      branchHash: fingerprint(branch),
+      preparation: structuredClone(preparation),
+    };
+    const controller = new AbortController();
+    const job: Job = { snapshot, controller, promise: Promise.resolve(undefined), startedAt: Date.now() };
+    this.job = job;
+    this.show(ctx, "running", "Preparing a native summary");
+    const timeout = setTimeout(() => controller.abort(), this.options.timeoutMs);
+    timeout.unref();
+    // Defer invocation so a synchronous provider error is handled identically.
+    const work = Promise.resolve().then(() => {
+      controller.signal.throwIfAborted();
+      return this.native.compact(
+        snapshot.preparation,
+        model,
+        undefined,
+        undefined,
+        undefined,
+        controller.signal,
+        ctx.thinkingLevel,
+        (requestModel, context, options) => ctx.modelRegistry.streamSimple(requestModel, context, options),
+        undefined,
+        settingsManager.getRetrySettings(),
+      );
+    });
+    job.promise = untilAborted(work, controller.signal)
+      .catch(() => undefined) // Never copy provider errors (possibly sensitive) into status or session data.
+      .then((result) => {
+        if (this.job !== job) return undefined;
+        if (!result) {
+          this.job = undefined;
+          this.failures++;
+          this.show(
+            ctx,
+            this.failures >= 2 ? "paused" : "idle",
+            "Background request failed or timed out; native fallback remains active",
+          );
+          return undefined;
+        }
+        job.result = result;
+        job.readyAt = Date.now();
+        job.estimate = this.estimate(job, result, ctx);
+        this.show(ctx, "ready", "Summary held until native threshold compaction");
+        return result;
+      })
+      .finally(() => clearTimeout(timeout));
+  }
+
+  async beforeCompact(
+    event: SessionBeforeCompactEvent,
+    ctx: ExtensionContext,
+  ): Promise<SessionBeforeCompactResult | undefined> {
+    const job = this.job;
+    if (!job) return undefined;
+    if (
+      !this.enabled ||
+      event.reason !== "threshold" ||
+      event.customInstructions !== undefined ||
+      fingerprint(event.preparation.settings) !== fingerprint(job.snapshot.preparation.settings) ||
+      !this.valid(job, ctx)
+    ) {
+      this.discard(ctx, "Using native compaction for this request");
+      return undefined;
+    }
+    const abort = () => this.discard(ctx, "Foreground compaction cancelled");
+    if (event.signal.aborted) {
+      abort();
+      return undefined;
+    }
+    event.signal.addEventListener("abort", abort, { once: true });
+    const waitStart = Date.now();
+    try {
+      const result = await job.promise;
+      const waitedMs = Date.now() - waitStart;
+      // Revalidate after awaiting: edits, switches, and model changes may race it.
+      if (event.signal.aborted || this.job !== job || !result) return undefined;
+      if (!this.valid(job, ctx)) {
+        this.discard(ctx, "Snapshot changed while waiting");
+        return undefined;
+      }
+      const accepted = validateResult(
+        job.snapshot,
+        result,
+        ctx.sessionManager.getBranch(),
+        ctx.model?.contextWindow ?? 0,
+        event.preparation.tokensBefore,
+      );
+      if (!accepted) {
+        this.discard(ctx, "Summary or retained tail exceeds the safe budget");
+        return undefined;
+      }
+      this.job = undefined;
+      this.show(ctx, "idle", "Prepared summary supplied to Pi");
+      this.pendingApplied = {
+        tokensBefore: event.preparation.tokensBefore,
+        tokensAfter: accepted.estimatedTokensAfter ?? event.preparation.tokensBefore,
+        preparedMs: (job.readyAt ?? Date.now()) - job.startedAt,
+        waitedMs,
+        at: Date.now(),
+        usage: accepted.usage,
+      };
+      return {
+        compaction: {
+          ...accepted,
+          details: isFileDetails(accepted.details)
+            ? { ...accepted.details, precompact: 1 }
+            : accepted.details,
+        },
+      };
+    } finally {
+      event.signal.removeEventListener("abort", abort);
+    }
+  }
+}

package/src/files.ts

@@ -0,0 +1,24 @@
+import { getLatestCompactionEntry, type SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { Preparation } from "./native.ts";
+
+export function isFileDetails(value: unknown): value is { readFiles: string[]; modifiedFiles: string[] } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "readFiles" in value &&
+    Array.isArray(value.readFiles) &&
+    value.readFiles.every((file) => typeof file === "string") &&
+    "modifiedFiles" in value &&
+    Array.isArray(value.modifiedFiles) &&
+    value.modifiedFiles.every((file) => typeof file === "string")
+  );
+}
+
+/** Pi 1.4.0 does not inherit file details from fromHook entries, even native-shaped ones. */
+export function inheritOwnFiles(preparation: Preparation, branch: SessionEntry[]): void {
+  const previous = getLatestCompactionEntry(branch);
+  const details: unknown = previous?.details;
+  if (!isFileDetails(details) || !("precompact" in details) || details.precompact !== 1) return;
+  for (const file of details.readFiles) preparation.fileOps.read.add(file);
+  for (const file of details.modifiedFiles) preparation.fileOps.edited.add(file);
+}