@inhuman.tools/turn 0.0.0-stage → 0.2.0

package/src/tool-runtime/plugin-context.ts

@@ -0,0 +1,68 @@
+/**
+ * Build plugin call context from live session entities. Graph objects stay
+ * host-side. Storage is the prefix projection; propose is applied onto this job after run.
+ */
+import {
+  CompletionExpectation,
+  hostingTurnOf,
+  projectionsOf,
+  reactChunks,
+  SessionRoot,
+  SessionTurn,
+  storageBefore,
+  tapeCompletion,
+  ToolCallJob,
+} from "@inhuman.tools/harness-model";
+import type { PluginCallContext } from "@inhuman.tools/plugin-sdk";
+
+export const pendingPropose = new WeakMap<object, { readonly pluginId: string; readonly action: unknown }>();
+
+function completionHosting(job: ToolCallJob): CompletionExpectation | null {
+  const turn = job.parent instanceof SessionTurn ? job.parent : null;
+  if (turn == null) return null;
+  const tape = reactChunks(turn);
+  for (let i = 0; i < tape.length; i += 1) {
+    const pew = tapeCompletion(tape[i]);
+    if (pew == null) continue;
+    if (pew.messages.includes(job)) return pew;
+    for (let index = i + 1; index < tape.length; index += 1) {
+      const cell = tape[index];
+      if (tapeCompletion(cell) != null) break;
+      if (cell === job) return pew;
+    }
+  }
+  return null;
+}
+
+export function pluginCallContextOf(
+  root: SessionRoot,
+  job: ToolCallJob,
+  signal?: AbortSignal,
+  pluginId = "",
+): PluginCallContext {
+  const turn = hostingTurnOf(root, job) ?? (job.parent instanceof SessionTurn ? job.parent : null);
+  const completion = completionHosting(job);
+  const prefix = storageBefore(root, job);
+  const projection = pluginId === "" ? undefined : projectionsOf(root).get(pluginId);
+  const initial = projection?.initial() ?? {};
+  return {
+    root: root.path.trim() === "" ? undefined : root.path,
+    callerSessionId: root.sessionId,
+    turn,
+    completion,
+    invocation: job,
+    signal,
+    storage: {
+      session: pluginId === "" ? prefix : (prefix[pluginId] ?? initial),
+      invocation: initial,
+      propose(action: unknown) {
+        if (pluginId === "") return;
+        pendingPropose.set(job, { pluginId, action });
+      },
+    },
+  };
+}
+
+export function isModelOriginContext(ctx: PluginCallContext): boolean {
+  return ctx.completion instanceof CompletionExpectation;
+}

package/src/tool-runtime/recall.ts

@@ -0,0 +1,104 @@
+/**
+ * `context_recall {ref}` — read a sealed result back from the graph, paged.
+ *
+ * It re-exposes only what the model already saw in this session, so it needs
+ * no policy floor beyond read-only. Refs resolve against turns reachable from
+ * the live head (`turnTail` chain); an abandoned branch or another session
+ * cannot be read.
+ */
+import { ProgrammaticJob, reactChunks, SessionRoot, SessionTurn, ToolCallJob } from "@inhuman.tools/harness-model";
+import type { ToolOutcomeSnap } from "@inhuman.tools/harness-model/schemas";
+
+import { SQUEEZE_COMPACT_CHARS, liftToolImages, paintObservation } from "../context/squeeze.js";
+
+export const CONTEXT_RECALL_TOOL_NAME = "context_recall";
+
+const MIN_PREFIX = 4;
+
+function reachableTurns(root: SessionRoot): SessionTurn[] {
+  const out: SessionTurn[] = [];
+  for (let cell: unknown = root.head; cell instanceof SessionTurn && !out.includes(cell); cell = cell.turnTail) {
+    out.push(cell);
+  }
+  return out;
+}
+
+function reachableJobs(root: SessionRoot): Array<ToolCallJob | ProgrammaticJob> {
+  const out: Array<ToolCallJob | ProgrammaticJob> = [];
+  for (const turn of reachableTurns(root)) {
+    for (const cell of reactChunks(turn)) {
+      if (cell instanceof ToolCallJob) out.push(cell);
+      else if (cell instanceof ProgrammaticJob) {
+        out.push(cell, ...cell.toolCalls);
+      }
+    }
+  }
+  return out;
+}
+
+export function sealedJobText(job: ToolCallJob | ProgrammaticJob): string {
+  if (job instanceof ToolCallJob) return paintObservation(liftToolImages(job.observationPayload()).payload);
+  const text = job.resultText();
+  return text !== "" ? text : (job.receiptJson ?? "");
+}
+
+function nameOf(job: ToolCallJob | ProgrammaticJob): string {
+  return job instanceof ToolCallJob ? job.name : job.toolName;
+}
+
+export function recallContext(
+  root: SessionRoot,
+  args: { readonly ref?: unknown; readonly offset?: unknown; readonly length?: unknown },
+): ToolOutcomeSnap {
+  const refused = (text: string): ToolOutcomeSnap => ({ ok: false, text: `context_recall: ${text}` });
+  let ref = typeof args.ref === "string" ? args.ref.trim() : "";
+  if (ref === "") return refused("ref is required (job:<id> or visual:<id>)");
+  const offset = typeof args.offset === "number" && args.offset > 0 ? Math.floor(args.offset) : 0;
+  const length =
+    typeof args.length === "number" && args.length > 0
+      ? Math.min(Math.floor(args.length), SQUEEZE_COMPACT_CHARS)
+      : SQUEEZE_COMPACT_CHARS;
+
+  if (ref.startsWith("visual:")) {
+    const id = ref.slice("visual:".length);
+    for (const turn of reachableTurns(root)) {
+      const visual = turn.visuals.find((v) => v.id === id);
+      if (visual === undefined) continue;
+      return {
+        ok: true,
+        value: `[recall ${ref}] [Image attached: ${visual.mime}, ${visual.width}x${visual.height}${visual.sourcePath ? `, ${visual.sourcePath}` : ""}]`,
+        json: { visualId: visual.id },
+      };
+    }
+    return refused(`unknown or unreachable ref ${ref}`);
+  }
+
+  for (let hop = 0; hop < 4; hop += 1) {
+    if (!ref.startsWith("job:")) return refused(`unknown ref ${ref} (use job:<id> or visual:<id>)`);
+    const wantArgs = ref.endsWith("#args");
+    const prefix = ref.slice("job:".length).replace(/#args$/, "");
+    if (prefix.length < MIN_PREFIX) return refused(`ref ${ref} is too short`);
+    const hits = reachableJobs(root).filter((job) => job.uuid.startsWith(prefix));
+    if (hits.length === 0) return refused(`unknown or unreachable ref ${ref}`);
+    if (hits.length > 1) return refused(`ref ${ref} is ambiguous`);
+    const job = hits[0]!;
+    if (nameOf(job) === CONTEXT_RECALL_TOOL_NAME) {
+      // A recall of a recall resolves to the original.
+      const inner = job.args?.ref;
+      if (typeof inner !== "string") return refused(`ref ${ref} names an unreadable recall`);
+      ref = inner;
+      if (ref.startsWith("visual:")) return recallContext(root, { ref, offset, length });
+      continue;
+    }
+    if (!wantArgs && !job.completed) return refused(`${ref} has no sealed result yet`);
+    const text = wantArgs ? JSON.stringify(job.args ?? {}) : sealedJobText(job);
+    const total = text.length;
+    const pages = Math.max(1, Math.ceil(total / length));
+    const end = Math.min(total, offset + length);
+    const note =
+      !wantArgs && job instanceof ToolCallJob && job.regenerateable ? "; as observed, re-read for current" : "";
+    const header = `[recall ${ref} ${nameOf(job)}${wantArgs ? " args" : ""}: chars ${offset}-${end} of ${total}, page ${Math.floor(offset / length) + 1}/${pages}${end < total ? `; next offset ${end}` : ""}${note}]`;
+    return { ok: true, value: `${header}\n${text.slice(offset, end)}` };
+  }
+  return refused("ref chain too deep");
+}

package/src/tool-runtime/run-system-tool.ts

@@ -0,0 +1,273 @@
+/**
+ * System-tool BODY. Claimed after an allow-side guard. Outcome lives on
+ * the job. This run does not vote. Effect bodies are catalog.execute.
+ */
+import {
+  cancelOutcomeText,
+  DEFAULT_SHELL_TAIL_BYTES,
+  documentRoot,
+  FileMutateToolJob,
+  isAbortError,
+  isTimeoutAbortReason,
+  type JobStopReport,
+  parseShellTailBytes,
+  outcomeText,
+  projectionsOf,
+  rememberJobResult,
+  RESULT_NOTE_CHARS,
+  reportShellTail,
+  retractShellTail,
+  SessionRoot,
+  SystemToolJob,
+  writePluginMeta,
+} from "@inhuman.tools/harness-model";
+import type { ToolOutcomeSnap } from "@inhuman.tools/harness-model/schemas";
+import { z } from "zod";
+
+import { externalizePrior } from "./blob-port.js";
+import { runWithExtraRoot } from "./extra-root.js";
+import { pendingPropose, pluginCallContextOf } from "./plugin-context.js";
+import { CONTEXT_RECALL_TOOL_NAME, recallContext } from "./recall.js";
+import { ToolError } from "./tool-error.js";
+import { workerToolAllowed } from "./worker-tools.js";
+import { lineStartOfSpan } from "./write-admit.js";
+import { behaviorEntriesOf, catalogOf, requireCatalog } from "../tool-catalog/index.js";
+
+function cancelledSnap(signal: AbortSignal): ToolOutcomeSnap {
+  return { ok: false, text: cancelOutcomeText(signal.reason) };
+}
+
+const TAIL_MS = 50;
+
+function tailPublisher(job: SystemToolJob): {
+  push: (frame: { readonly text: string; readonly totalBytes: number }) => void;
+  flush: () => void;
+} {
+  let lastAt = 0;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let latest: { text: string; totalBytes: number } | undefined;
+  const send = (frame: { text: string; totalBytes: number }): void => {
+    if (job.receiptJson != null && job.receiptJson !== "") return;
+    latest = undefined;
+    lastAt = Date.now();
+    reportShellTail(job, frame);
+  };
+  return {
+    push(frame) {
+      const now = Date.now();
+      if (now - lastAt >= TAIL_MS) {
+        if (timer !== undefined) clearTimeout(timer);
+        timer = undefined;
+        send(frame);
+        return;
+      }
+      latest = frame;
+      timer ??= setTimeout(() => {
+        timer = undefined;
+        if (latest !== undefined) send(latest);
+      }, TAIL_MS);
+    },
+    flush() {
+      if (timer !== undefined) clearTimeout(timer);
+      timer = undefined;
+      if (latest !== undefined) send(latest);
+    },
+  };
+}
+
+/** The captured prior text lands inline or by reference; the other field is cleared, so at most one is set. */
+function stampPrior(job: FileMutateToolJob, text: string | null): void {
+  if (text === null) {
+    job.priorContent = null;
+    job.priorBlobJson = null;
+    return;
+  }
+  const stamp = externalizePrior(text);
+  if ("priorBlobJson" in stamp) {
+    job.priorContent = null;
+    job.priorBlobJson = stamp.priorBlobJson;
+  } else {
+    job.priorContent = stamp.priorContent;
+    job.priorBlobJson = null;
+  }
+}
+
+export function sealToolCall(job: SystemToolJob, outcome: ToolOutcomeSnap): void {
+  rememberJobResult(job, outcomeText(outcome), RESULT_NOTE_CHARS);
+  job.outcomeSnap ??= outcome;
+  retractShellTail(job);
+}
+
+function asToolResult(out: unknown): ToolOutcomeSnap {
+  if (out != null && typeof out === "object" && "ok" in out) {
+    const row = out as {
+      ok?: unknown;
+      text?: unknown;
+      value?: unknown;
+      truncated?: unknown;
+    };
+    if (typeof row.ok === "boolean") {
+      return {
+        ok: row.ok,
+        ...(typeof row.text === "string" ? { text: row.text } : {}),
+        ...("value" in row ? { value: row.value } : {}),
+        ...(row.truncated === true ? { truncated: true } : {}),
+      };
+    }
+  }
+  return { ok: true, value: out };
+}
+
+function doorText(error: unknown): string {
+  if (error instanceof z.ZodError) {
+    const issue = error.issues[0];
+    const path = issue.path.map(String).join(".");
+    return path === "" ? issue.message : `${path}: ${issue.message}`;
+  }
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+export async function executeSystemTool(
+  job: SystemToolJob,
+  signal: AbortSignal,
+  opts?: {
+    readonly shellTailBytes?: number;
+    /** Host list/stop for `job_stop`. The tool body has no job table of its own. */
+    readonly stopJob?: (jobId: string) => JobStopReport | Promise<JobStopReport>;
+  },
+): Promise<void> {
+  const seal = (outcome: ToolOutcomeSnap): void => {
+    sealToolCall(job, outcome);
+  };
+  try {
+    if (signal.aborted) {
+      seal(cancelledSnap(signal));
+      return;
+    }
+
+    const { toolCallId, name } = job;
+    if (toolCallId === "") {
+      seal({ ok: false, text: "tool_call snapshot missing toolCallId" });
+      return;
+    }
+
+    const session = documentRoot(job);
+    if (!(session instanceof SessionRoot)) {
+      seal({ ok: false, text: "tool_call missing session" });
+      return;
+    }
+
+    const catalog = requireCatalog(catalogOf(session), name);
+    const entry = catalog.catalogEntry(name) ?? behaviorEntriesOf(session).find((row) => row.wireName === name);
+    if (session.agent.spec.name !== "" && !workerToolAllowed(catalog, session.agent.spec.name, name, session)) {
+      seal({ ok: false, text: "outside worker tool ceiling" });
+      return;
+    }
+    job.regenerateable = entry?.class === "read";
+    if (signal.aborted) {
+      seal(cancelledSnap(signal));
+      return;
+    }
+
+    const raw = job.invocation();
+    const args = job.args ?? (raw === "" ? {} : null);
+    if (args == null) {
+      seal({
+        ok: false,
+        text: `${name}: arguments were not valid JSON — ${raw.slice(0, 200)}`,
+      });
+      return;
+    }
+
+    if (name === CONTEXT_RECALL_TOOL_NAME) {
+      seal(recallContext(session, args));
+      return;
+    }
+
+    if (name === "job_stop") {
+      const jobIdRaw = args.job_id;
+      const jobId = typeof jobIdRaw === "string" ? jobIdRaw : "";
+      const report = await (opts?.stopJob?.(jobId) ?? {
+        ok: false as const,
+        text: "job_stop is not available on this host",
+      });
+      seal(report);
+      return;
+    }
+
+    const root = session.path.trim() === "" ? process.cwd() : session.path;
+    // Extra-root follows the license, not the human bit. Yolo and auto
+    // remainder leave approved null; writing it here would derive HITL.
+    // block never licenses. A folder the human said to treat as part of the session is a floor approve for
+    // reads under it (a session read root), so it opens the same door through `licenseAllows`; nothing is remembered
+    // from a single outside read.
+    const tailBytes = parseShellTailBytes(opts?.shellTailBytes ?? DEFAULT_SHELL_TAIL_BYTES);
+    const live = name === "shell" && tailBytes > 0 ? tailPublisher(job) : undefined;
+    let dispatched: unknown;
+    try {
+      ToolError.invariant(entry?.execute, () =>
+        name.startsWith("mcp__")
+          ? `unknown MCP tool "${name}" — connection missing, disabled, or not expanded`
+          : `unknown tool "${name}" — available: ${catalog.catalogWireNames().join(", ")}`,
+      );
+      try {
+        dispatched = await runWithExtraRoot(job.licenseAllows, () =>
+          entry.execute!(args, {
+            root,
+            catalog,
+            signal,
+            sessionId: session.sessionId,
+            onPriorContent:
+              job instanceof FileMutateToolJob
+                ? (text) => {
+                    stampPrior(job, text);
+                    if (typeof text === "string" && name === "edit_file") {
+                      const old = typeof args.old_string === "string" ? args.old_string : "";
+                      const line = lineStartOfSpan(text, old);
+                      if (line != null) job.priorLineStart = line;
+                    }
+                  }
+                : undefined,
+            shellTailBytes: tailBytes,
+            onTail: live?.push,
+            ...pluginCallContextOf(session, job, signal, entry.source.kind === "pack" ? entry.source.pluginName : ""),
+          }),
+        );
+      } catch (error) {
+        if (error instanceof ToolError) throw error;
+        dispatched = {
+          ok: false,
+          text: error instanceof z.ZodError ? doorText(error) : `${name}: ${doorText(error)}`,
+        };
+      }
+    } finally {
+      live?.flush();
+    }
+    const proposed = pendingPropose.get(job);
+    pendingPropose.delete(job);
+    if (proposed != null) {
+      const projection = projectionsOf(job).get(proposed.pluginId);
+      if (projection?.hostOnly?.(proposed.action) === true) {
+        seal({ ok: false, text: `${proposed.pluginId}: host-only metadata` });
+        return;
+      }
+      writePluginMeta(job, proposed.pluginId, proposed.action, false);
+    }
+    seal(asToolResult(dispatched));
+  } catch (error) {
+    if (signal.aborted) {
+      seal(cancelledSnap(signal));
+      return;
+    }
+    if (error instanceof ToolError) {
+      seal({ ok: false, text: error.message });
+      return;
+    }
+    if (isAbortError(error) && !isTimeoutAbortReason(error)) {
+      seal({ ok: false, text: cancelOutcomeText(error) });
+      return;
+    }
+    seal({ ok: false, text: `error: ${error instanceof Error ? error.message : String(error)}` });
+  }
+}

package/src/tool-runtime/tool-error.ts

@@ -0,0 +1,6 @@
+import { ErrorWithInvariant } from "@inhuman.tools/error-with-invariant";
+
+/** Failure the model is meant to read and correct — never a turn-killer. */
+export class ToolError extends ErrorWithInvariant {
+  readonly name = "ToolError";
+}

package/src/tool-runtime/worker-tools.ts

@@ -0,0 +1,76 @@
+/**
+ * Worker tool ceiling. The one implementation: the session view and admit/execute both call it.
+ * Bot-granted MCP and private plugin MCP are answered by the catalog's `workerHost`.
+ */
+import {
+  AGENT_ASK,
+  AGENT_MESSAGE,
+  AGENT_NOTIFY,
+  AGENT_RESPOND,
+  AGENT_SEND,
+  AGENT_VOID,
+  AskAgentSpec,
+  SCHEME_REPL_TOOL_NAME,
+  SCHEME_WATCH_TOOL_NAME,
+  SessionRoot,
+} from "@inhuman.tools/harness-model";
+
+import { behaviorEntriesOf, catalogTriggersReactLoop, type KernelToolCatalog } from "../tool-catalog/index.js";
+
+function isAgentComms(wire: string): boolean {
+  return (
+    wire === AGENT_RESPOND ||
+    wire === AGENT_VOID ||
+    wire === AGENT_NOTIFY ||
+    wire === AGENT_MESSAGE ||
+    wire === AGENT_SEND ||
+    wire === AGENT_ASK
+  );
+}
+
+function askWorkerToolAllowed(catalog: KernelToolCatalog, wire: string): boolean {
+  if (wire === AGENT_VOID) return false;
+  return (
+    wire === SCHEME_REPL_TOOL_NAME ||
+    wire === SCHEME_WATCH_TOOL_NAME ||
+    catalog.catalogEntry(wire)?.isSideChannel === true ||
+    isAgentComms(wire)
+  );
+}
+
+export function workerToolAllowed(
+  catalog: KernelToolCatalog,
+  recipeName: string,
+  wire: string,
+  sessionRoot?: SessionRoot,
+): boolean {
+  const spec = sessionRoot?.agent.spec;
+  if (spec instanceof AskAgentSpec) {
+    if (wire === AGENT_VOID) return spec.voidLegal === true;
+    if (behaviorEntriesOf(sessionRoot).some((entry) => entry.wireName === wire)) return true;
+    if (spec.inheritCallerTools) return true;
+    if (askWorkerToolAllowed(catalog, wire)) return true;
+    if (spec.tools?.includes(wire) === true) return true;
+    if (spec.name === "" || spec.toolsOnly) return false;
+    const named = catalog.recipe(spec.name);
+    if (named == null) return false;
+    return catalog.workerHost.recipeGrantsWire(catalog, named.spec, wire, sessionRoot?.path ?? "");
+  }
+  if (wire === AGENT_VOID && spec?.voidLegal === false) return false;
+  if (recipeName === "") return true;
+  if (behaviorEntriesOf(sessionRoot).some((entry) => entry.wireName === wire)) return true;
+  const recipe = catalog.recipe(recipeName);
+  if (recipe == null) return false;
+  if (catalog.privateWorkerEntries.some((row) => row.wireName === wire)) return true;
+  const entry = catalog.catalogEntry(wire);
+  if (entry == null) return catalog.workerHost.privateWireAllowed(recipeName, wire, sessionRoot);
+  if (
+    wire === SCHEME_REPL_TOOL_NAME ||
+    wire === SCHEME_WATCH_TOOL_NAME ||
+    !catalogTriggersReactLoop(catalog, wire) ||
+    isAgentComms(wire)
+  ) {
+    return true;
+  }
+  return catalog.workerHost.recipeGrantsWire(catalog, recipe.spec, wire, sessionRoot?.path ?? "");
+}

package/src/tool-runtime/write-admit.ts

@@ -0,0 +1,90 @@
+/**
+ * write_file overwrite gate and admit snapshot. Effect bodies stay
+ * outside this package; this is the door the guard still sees.
+ */
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+
+import { parseJsonRecord } from "@inhuman.tools/harness-model/json-record";
+
+const MAX_FILE_READ_BYTES = 4 * 1024 * 1024;
+
+const OVERWRITE_EXISTING_DOOR =
+  "tried to overwrite the existing file, use write_file with the overwriteExisting flag if you need that to happen";
+
+export function overwriteExistingDoor(pathText: string): string {
+  return `write_file: ${pathText} exists — ${OVERWRITE_EXISTING_DOOR}`;
+}
+
+/** True only for boolean true or the string "true". Missing / false → door on exist. */
+export function overwriteExistingOf(args: unknown): boolean {
+  if (args == null || typeof args !== "object") return false;
+  const rec = args as Record<string, unknown>;
+  const value = rec.overwriteExisting ?? rec.overwrite_existing ?? rec.overwrite;
+  return value === true || value === "true";
+}
+
+/** Tape line annotation. Line 1 is omitted. */
+export function lineStartOfSpan(file: string | null | undefined, span: string): number | null {
+  if (file == null || span === "") return null;
+  let idx = file.indexOf(span);
+  if (idx === -1) {
+    const firstLine = span.split("\n")[0] ?? "";
+    if (firstLine === "" || firstLine === span) return null;
+    idx = file.indexOf(firstLine);
+  }
+  if (idx === -1) return null;
+  let line = 1;
+  for (let i = 0; i < idx; i++) if (file[i] === "\n") line++;
+  return line <= 1 ? null : line;
+}
+
+/** NUL-free UTF-8 under the read budget. Empty file is "". */
+export function priorTextSync(target: string): string | null {
+  try {
+    const info = statSync(target);
+    if (!info.isFile() || info.size > MAX_FILE_READ_BYTES) return null;
+    const buf = readFileSync(target);
+    if (buf.includes(0)) return null;
+    return buf.toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+type WriteAdmitSnap = {
+  /** `null` means we could not tell — not a definite miss. */
+  readonly existed: boolean | null;
+  readonly priorContent: string | null;
+  readonly refuse: string | null;
+};
+
+function insideRoot(root: string, file: string): boolean {
+  const from = path.relative(root, file);
+  return from === "" || (!from.startsWith("..") && !path.isAbsolute(from));
+}
+
+/**
+ * Admit runs before any license. Only a path that stays inside the workspace, links resolved, may
+ * be read or probed here; anything else is left to the licensed body, which captures prior content
+ * after approval and keeps the overwrite door.
+ */
+export function writeFileAdmitSnap(root: string, argsJson: string): WriteAdmitSnap {
+  const args = parseJsonRecord(argsJson === "" ? "{}" : argsJson);
+  const raw = args !== null && typeof args.path === "string" ? args.path : "";
+  if (raw.trim() === "") return { existed: null, priorContent: null, refuse: null };
+  const target = path.resolve(root, raw);
+  const unknown: WriteAdmitSnap = { existed: null, priorContent: null, refuse: null };
+  try {
+    const realRoot = realpathSync(root);
+    if (!insideRoot(path.resolve(root), target)) return unknown;
+    if (existsSync(target) && !insideRoot(realRoot, realpathSync(target))) return unknown;
+    if (!existsSync(target)) return { existed: false, priorContent: null, refuse: null };
+    if (!statSync(target).isFile()) return { existed: null, priorContent: null, refuse: null };
+  } catch {
+    return { existed: null, priorContent: null, refuse: null };
+  }
+  const priorContent = priorTextSync(target);
+  const refuse = overwriteExistingOf(args ?? {}) ? null : overwriteExistingDoor(raw);
+  return { existed: true, priorContent, refuse };
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.