@inhuman.tools/turn 0.0.0-stage → 0.1.0

package/src/policy-processor/cluster.ts

@@ -0,0 +1,31 @@
+/**
+ * Classifier-lambda payload. Cluster table and args parse live in
+ * harness-model. This module keeps the unknown[] shape the remainder
+ * ports apply.
+ */
+import { clusterOf, fileQuestion } from "@inhuman.tools/harness-model";
+
+/**
+ * Strings the agent controls are JSON-encoded here: the judge prompt places them in a
+ * labelled "untrusted" block, and encoding keeps a newline-and-label from forging a new section.
+ */
+/** Arguments for the matching `classifier/*` lambda, or undefined if the payload is missing. */
+export function classifierArgs(name: string, args: Readonly<Record<string, unknown>> | null): unknown[] | undefined {
+  switch (clusterOf(name)) {
+    case "bash": {
+      if (typeof args?.command !== "string" || args.command === "") return undefined;
+      const cwd = typeof args.cwd === "string" && args.cwd !== "" && args.cwd !== "." ? args.cwd : undefined;
+      return cwd === undefined
+        ? [JSON.stringify(args.command)]
+        : [JSON.stringify(args.command), `cwd ${JSON.stringify(cwd)}`];
+    }
+    case "read":
+      return [JSON.stringify(fileQuestion(name, args) ?? ".")];
+    case "write": {
+      const question = fileQuestion(name, args);
+      return question == null ? undefined : [JSON.stringify(question)];
+    }
+    case "mcp":
+      return [JSON.stringify(name), JSON.stringify(args ?? {})];
+  }
+}

package/src/policy-processor/evidence.ts

@@ -0,0 +1,214 @@
+/**
+ * Classifier request cuts from the job's owning turn. Nested jobs keep
+ * that turn; a caller-supplied turn would be the wrong one. Privileged
+ * is user prompts on the owning turn and its tail ancestry — continue
+ * mints `prompt: ""` with the authorization on the tail. Unattended /
+ * eval with no user text: owning ProgrammaticJob expr (approval.md
+ * EVIDENCE). The bag itself is not a remainder subject — only inner
+ * ToolCallJob leaves.
+ */
+import {
+  clusterOf,
+  fileQuestion,
+  ProgrammaticJob,
+  reactChunks,
+  SessionTurn,
+  tapeCompletion,
+  ToolCallJob,
+} from "@inhuman.tools/harness-model";
+import { parseTirithEvidence, tirithPolicyCut } from "@inhuman.tools/policy-tirith";
+
+export type EvidenceCuts = {
+  /** Oldest-first user prompts on the owning turn and its tails (the eval expression when there are none). */
+  readonly userMessages?: readonly string[];
+  /** The agent's last completed answer before the most recent user message. Round 2 of the soft-deny judge only. */
+  readonly agentAnswer?: string;
+  readonly privileged: string;
+  readonly priorTurn: string;
+  readonly quarantined: string;
+  readonly policy?: string;
+};
+
+export function evidenceCuts(job: ToolCallJob): EvidenceCuts {
+  const turn = owningTurn(job);
+  const program = owningProgram(job);
+  if (turn == null) {
+    const expr = program?.expr.trim() || "";
+    return {
+      userMessages: expr === "" ? [] : [expr],
+      agentAnswer: "",
+      privileged: expr,
+      priorTurn: "",
+      quarantined: "",
+      policy: policyPipCut(job.policyEvidenceJson),
+    };
+  }
+  const prior: string[] = [];
+  const quarantined: string[] = [];
+  for (const chunk of reactChunks(turn)) {
+    const completion = tapeCompletion(chunk);
+    if (completion != null) {
+      if (!completion.isDone || underJob(completion, job)) continue;
+      if (completion.responseText !== "") prior.push(completion.responseText);
+      continue;
+    }
+    if (!(chunk instanceof ToolCallJob) || chunk === job) continue;
+    if (chunk.sealedOutcomeJson() == null) continue;
+    const text = observationText(chunk.observationPayload());
+    if (text === "") continue;
+    quarantined.push(`${chunk.name} → ${text}`);
+  }
+  const messages = userPrompts(turn, program);
+  return {
+    userMessages: messages,
+    agentAnswer: agentAnswerBefore(turn),
+    privileged: messages.join("\n"),
+    priorTurn: prior.join("\n"),
+    quarantined: quarantined.join("\n"),
+    policy: policyPipCut(job.policyEvidenceJson),
+  };
+}
+
+function policyPipCut(json: string | null): string {
+  if (json == null || json === "") return "";
+  const report = parseTirithEvidence(json);
+  if (report != null) return tirithPolicyCut(report);
+  return json;
+}
+
+/** Oldest-first user prompts on `turn` then tails. Expr only when none exist. */
+function userPrompts(turn: SessionTurn, program: ProgrammaticJob | null): string[] {
+  const seen = new Set<SessionTurn>();
+  const prompts: string[] = [];
+  let cell: SessionTurn | null = turn;
+  while (cell != null && !seen.has(cell)) {
+    seen.add(cell);
+    const text = cell.prompt.trim();
+    if (text !== "") prompts.push(text);
+    cell = cell.turnTail instanceof SessionTurn ? cell.turnTail : null;
+  }
+  prompts.reverse();
+  if (prompts.length > 0) return prompts;
+  const expr = program?.expr.trim() || "";
+  return expr === "" ? [] : [expr];
+}
+
+/**
+ * The agent's last completed answer that precedes the most recent user message: the proposal a short
+ * reply ("let's do it") refers to. Not the current turn's text, never tool output. Empty when there is
+ * none (the most recent user message opens the conversation).
+ */
+function agentAnswerBefore(turn: SessionTurn): string {
+  const seen = new Set<SessionTurn>();
+  let cell: SessionTurn | null = turn;
+  while (cell != null && !seen.has(cell) && cell.prompt.trim() === "") {
+    seen.add(cell);
+    cell = cell.turnTail instanceof SessionTurn ? cell.turnTail : null;
+  }
+  // `cell` carries the most recent user prompt. Its tails hold the answers that came before it.
+  let earlier: SessionTurn | null = cell != null && cell.turnTail instanceof SessionTurn ? cell.turnTail : null;
+  while (earlier != null && !seen.has(earlier)) {
+    seen.add(earlier);
+    const chunks = reactChunks(earlier);
+    for (const chunk of chunks.toReversed()) {
+      const completion = tapeCompletion(chunk);
+      if (completion != null && completion.isDone && completion.responseText !== "") return completion.responseText;
+    }
+    earlier = earlier.turnTail instanceof SessionTurn ? earlier.turnTail : null;
+  }
+  return "";
+}
+
+export function evidenceIdentity(cuts: EvidenceCuts): string {
+  return JSON.stringify([cuts.privileged, cuts.priorTurn, cuts.quarantined, cuts.policy ?? "", cuts.agentAnswer ?? ""]);
+}
+
+/** Cluster+payload remainder skip key. */
+export function evidencePayloadKey(job: ToolCallJob): string | null {
+  const payload = canonicalPayload(job);
+  if (payload == null || payload === "") return null;
+  // The tier and classes are part of the key: a payload that was an ask under one policy and a
+  // soft-deny under another must not share a vote.
+  return JSON.stringify([clusterOf(job.name), payload, job.policyResult, job.policyClassesJson ?? ""]);
+}
+
+export function owningTurn(job: ToolCallJob): SessionTurn | null {
+  return ancestor(job, (parent): parent is SessionTurn => parent instanceof SessionTurn);
+}
+
+function owningProgram(job: ToolCallJob): ProgrammaticJob | null {
+  return ancestor(job, (parent): parent is ProgrammaticJob => parent instanceof ProgrammaticJob);
+}
+
+function ancestor<T>(job: { parent: unknown }, match: (parent: unknown) => parent is T): T | null {
+  const seen = new Set<object>();
+  let node: { parent: unknown } | null = job;
+  while (node != null) {
+    if (seen.has(node)) return null;
+    seen.add(node);
+    const parent: unknown = node.parent;
+    if (match(parent)) return parent;
+    if (parent instanceof SessionTurn) return null;
+    node = parent !== null && typeof parent === "object" && "parent" in parent ? (parent as { parent: unknown }) : null;
+  }
+  return null;
+}
+
+function underJob(node: { parent: unknown }, job: ToolCallJob): boolean {
+  const seen = new Set<object>();
+  let cur: { parent: unknown } | null = node;
+  while (cur != null) {
+    if (seen.has(cur)) return false;
+    seen.add(cur);
+    if (cur === job) return true;
+    const parent: unknown = cur.parent;
+    if (parent instanceof SessionTurn) return false;
+    cur = parent !== null && typeof parent === "object" && "parent" in parent ? (parent as { parent: unknown }) : null;
+  }
+  return false;
+}
+
+function observationText(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value === undefined) return "";
+  try {
+    const json = JSON.stringify(value);
+    return typeof json === "string" ? json : "";
+  } catch {
+    return String(value);
+  }
+}
+
+function canonicalPayload(job: ToolCallJob): string | null {
+  const args = job.args;
+  switch (clusterOf(job.name)) {
+    case "bash": {
+      const command = args?.command;
+      if (typeof command !== "string" || command === "") return null;
+      const cwd = args?.cwd;
+      if (typeof cwd === "string" && cwd !== "" && cwd !== ".") return `${command}\ncwd ${cwd}`;
+      return command;
+    }
+    case "read":
+      return fileQuestion(job.name, args) ?? ".";
+    case "write":
+      return fileQuestion(job.name, args);
+    case "mcp":
+      return `${job.name}\n${stableJson(args ?? {})}`;
+  }
+}
+
+function sortKeys(value: unknown): unknown {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((item) => sortKeys(item));
+  const rec = value as Record<string, unknown>;
+  return Object.fromEntries(
+    Object.keys(rec)
+      .toSorted()
+      .map((key) => [key, sortKeys(rec[key])]),
+  );
+}
+
+function stableJson(value: unknown): string {
+  return JSON.stringify(sortKeys(value));
+}

package/src/policy-processor/explain.ts

@@ -0,0 +1,310 @@
+/**
+ * "What would happen to this call right now?" The same floor, grant and resolution code as a real
+ * call, with no judge and no effect, so the answer cannot drift from the real path.
+ */
+import nodePath from "node:path";
+
+import {
+  activeAcks,
+  clusterOf,
+  collectAckFlags,
+  coveringGrants,
+  type GrantRow,
+  type GrantSubject,
+  grantOptionsFor,
+  isShellHatch,
+  layersOf,
+  matchAckFlags,
+  readRootList,
+  resolveAcks,
+  resolveCall,
+  ruleStampFor,
+  type CallSubject,
+  type PermissionMode,
+} from "@inhuman.tools/harness-model";
+import { CLASSES, classesOf, join, cast, type ClassId, type FloorVerdict } from "@inhuman.tools/policy/floor";
+import { tirithClass, tirithDisposition, tirithFailure } from "@inhuman.tools/policy-tirith";
+
+import { floorVerdict, withRealRoots, type LicenseScope } from "./scope.js";
+
+export type ExplainProbe =
+  | { readonly kind: "shell"; readonly command: string; readonly cwd?: string }
+  | { readonly kind: "path"; readonly cluster: "read" | "write"; readonly path: string }
+  | { readonly kind: "mcp"; readonly server: string; readonly account?: string; readonly tool: string }
+  | { readonly kind: "tool"; readonly name: string; readonly args?: Readonly<Record<string, unknown>> };
+
+export type Tier = "block" | "soft-deny" | "ask" | "allow";
+
+export type Explanation = {
+  readonly tier: Tier;
+  readonly classes: Array<{ readonly id: ClassId; readonly label: string }>;
+  readonly votes: Array<{
+    readonly tier: Tier;
+    readonly class: ClassId;
+    readonly ruleId: string;
+    readonly lift?: string;
+  }>;
+  readonly resolver: {
+    readonly kind: "allow" | "judge" | "human" | "deny";
+    readonly layer: "dist" | "managed" | "user" | "project" | "session";
+    readonly onDeny?: "human" | "deny";
+    readonly onFail?: "human" | "deny";
+  } | null;
+  readonly grant: GrantRow | null;
+  readonly grantable: GrantSubject[];
+  /** Acknowledgement flags that cover the call in this mode and the stored ack that satisfies them. */
+  readonly ack: {
+    readonly flags: Array<{ readonly label: string; readonly why?: string; readonly layer: string }>;
+    readonly satisfiedBy: GrantRow | null;
+  } | null;
+  readonly outcome: "runs" | "judge-ask" | "judge-soft-deny" | "prompts-you" | "denied" | "blocked";
+  readonly reason: string;
+};
+
+const TIER: Readonly<Record<string, Tier>> = { block: "block", deny: "soft-deny", ask: "ask", policyApprove: "allow" };
+
+function nameAndArgs(probe: ExplainProbe): { name: string; args: Record<string, unknown>; mcpName: string } {
+  switch (probe.kind) {
+    case "shell":
+      return {
+        name: "shell",
+        args: { command: probe.command, ...(probe.cwd === undefined ? {} : { cwd: probe.cwd }) },
+        mcpName: "shell",
+      };
+    case "path":
+      return { name: probe.cluster === "read" ? "read_file" : "write_file", args: { path: probe.path }, mcpName: "" };
+    case "mcp":
+      return { name: `mcp__${probe.server}__${probe.tool}`, args: {}, mcpName: probe.tool };
+    case "tool":
+      return { name: probe.name, args: { ...probe.args }, mcpName: probe.name };
+  }
+}
+
+export async function explainCall(
+  scope: LicenseScope,
+  probe: ExplainProbe,
+  options: { readonly mode?: PermissionMode; readonly unattended?: boolean } = {},
+): Promise<Explanation> {
+  const root = scope.root;
+  const { name, args, mcpName } = nameAndArgs(probe);
+  const source = root.policyProgram.trim() === "" ? scope.distSource() : root.policyProgram;
+  let verdict: FloorVerdict;
+  const layers = layersOf({
+    user: root.authorizationUserJson,
+    project: root.authorizationProjectJson,
+    session: root.authorizationOverlayJson,
+  });
+  const ruleMcp =
+    probe.kind === "mcp"
+      ? { server: probe.server, account: probe.account ?? probe.server, tool: probe.tool }
+      : undefined;
+  const rule =
+    clusterOf(name) === "mcp"
+      ? ruleStampFor(layers, { tool: name, ...(ruleMcp === undefined ? {} : { mcp: ruleMcp }) })
+      : {};
+  try {
+    const policy = await scope.compiledPolicy(source, await withRealRoots(readRootList(root.readRoots).toSorted()));
+    verdict = await floorVerdict(policy, name, args, root.path, mcpName, rule);
+  } catch (error) {
+    verdict = cast("block", "policy-fault", "host:policy-invalid");
+    return finish(
+      verdict,
+      null,
+      null,
+      [],
+      `the policy is invalid, so every call is blocked: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  if (clusterOf(name) === "bash" && typeof args.command === "string") {
+    try {
+      const report = await scope.checkShell(args.command, {
+        cwd: nodePath.resolve(root.path, typeof args.cwd === "string" ? args.cwd : "."),
+      });
+      verdict = join([
+        verdict,
+        cast(
+          tirithDisposition(report),
+          tirithClass(report),
+          `tirith:${report.findings.map((f) => f.rule_id).join("+")}`,
+        ),
+      ]);
+    } catch (error) {
+      const report = tirithFailure(error);
+      verdict = join([verdict, cast(tirithDisposition(report), tirithClass(report), "tirith:error")]);
+    }
+  }
+  const tierVotes = verdict.votes.filter((vote) => vote.disposition === verdict.disposition);
+  const classes = classesOf(verdict);
+  const cluster = clusterOf(name);
+  const mcp = ruleMcp;
+  const hatch = typeof args.command === "string" && isShellHatch(args.command);
+  const call = {
+    tier: verdict.disposition,
+    cluster,
+    hatch,
+    votes: tierVotes,
+    mcp,
+    toolName: name,
+  } as const;
+  const grant = verdict.disposition === "ask" ? (coveringGrants(scope.visibleGrants(), call)?.[0] ?? null) : null;
+  const grantable = grantOptionsFor(call).map((option) => option.subject);
+  const subject: CallSubject = {
+    tool: name,
+    units: tierVotes.flatMap((vote) => (vote.unit === undefined ? [] : [vote.unit])),
+    paths: tierVotes.flatMap((vote) => (vote.path === undefined ? [] : [vote.path])),
+    ...(mcp === undefined ? {} : { mcp }),
+  };
+  const resolution =
+    verdict.disposition === "ask" || verdict.disposition === "deny"
+      ? resolveCall(layers, {
+          mode: options.mode ?? root.permissionMode,
+          cluster,
+          tier: verdict.disposition,
+          classes,
+          unattended: options.unattended ?? false,
+          subject,
+        })
+      : null;
+  const mode = options.mode ?? root.permissionMode;
+  const ackCall = {
+    classes,
+    ...(mcp === undefined ? {} : { mcp }),
+    tool: name,
+    units: [...(verdict.seen ?? []), ...verdict.votes.flatMap((vote) => (vote.unit === undefined ? [] : [vote.unit]))],
+  };
+  const active =
+    verdict.disposition === "block" ? [] : activeAcks(matchAckFlags(collectAckFlags(layers), ackCall), mode);
+  const acks = resolveAcks(active, scope.visibleAcks(), ackCall);
+  const ack =
+    active.length === 0
+      ? null
+      : {
+          flags: active.map((flag) => ({
+            label: flag.label,
+            ...(flag.why === undefined ? {} : { why: flag.why }),
+            layer: flag.layer,
+          })),
+          satisfiedBy:
+            acks.state === "satisfied" ? (scope.visibleAcks().find((row) => row.id === acks.ackedBy[0]) ?? null) : null,
+        };
+  return withAck(
+    finish(verdict, resolution, grant, grantable, undefined, options.unattended ?? false),
+    ack,
+    options.unattended ?? false,
+  );
+}
+
+/**
+ * An unsatisfied flag stops a call that would run, and follows one that waits for a judge or a person.
+ * `block` and denials are untouched: an acknowledgement never lifts anything.
+ */
+function withAck(base: Explanation, ack: Explanation["ack"], unattended: boolean): Explanation {
+  if (ack === null || ack.satisfiedBy !== null) return { ...base, ack };
+  const what = ack.flags.map((flag) => flag.label).join("; ");
+  if (base.outcome === "blocked" || base.outcome === "denied") return { ...base, ack };
+  if (unattended) {
+    return {
+      ...base,
+      ack,
+      outcome: "denied",
+      reason: `${base.reason} It also needs your acknowledgement (${what}); this run is unattended, so it is denied as interaction_required and the run continues.`,
+    };
+  }
+  if (base.outcome === "runs") {
+    return {
+      ...base,
+      ack,
+      outcome: "prompts-you",
+      reason: `${base.reason} It is flagged to need your acknowledgement (${what}), so you are asked before it runs.`,
+    };
+  }
+  return { ...base, ack, reason: `${base.reason} If it is allowed, you are still asked to acknowledge it (${what}).` };
+}
+
+function finish(
+  verdict: FloorVerdict,
+  resolution: ReturnType<typeof resolveCall> | null,
+  grant: GrantRow | null,
+  grantable: GrantSubject[],
+  forced?: string,
+  unattended = false,
+): Explanation {
+  const tier = TIER[verdict.disposition] ?? "ask";
+  const classes = classesOf(verdict);
+  const base = {
+    tier,
+    classes: classes.map((id) => ({ id, label: CLASSES[id].label })),
+    votes: verdict.votes.map((vote) => ({
+      tier: TIER[vote.disposition] ?? "ask",
+      class: vote.class,
+      ruleId: vote.ruleId,
+      ...(vote.lift === undefined ? {} : { lift: vote.lift }),
+    })),
+    grant,
+    grantable,
+    ack: null,
+  };
+  const what = classes.map((id) => CLASSES[id].label.toLowerCase()).join(", ");
+  if (verdict.disposition === "block") {
+    return {
+      ...base,
+      resolver: null,
+      outcome: "blocked",
+      reason: forced ?? `Blocked (${what}). Nothing lifts a block: no mode, grant, judge or answer.`,
+    };
+  }
+  if (resolution === null) {
+    return { ...base, resolver: null, outcome: "runs", reason: "The floor allows it." };
+  }
+  const { resolver, layer, interaction } = resolution;
+  const cell = {
+    kind: resolver.kind,
+    layer,
+    ...(resolver.kind === "judge" ? { onDeny: resolver.onDeny, onFail: resolver.onFail } : {}),
+  } as const;
+  const tierName = tier === "soft-deny" ? "Soft-deny" : "Ask";
+  if (grant !== null) {
+    return {
+      ...base,
+      resolver: cell,
+      outcome: "runs",
+      reason: `${tierName} (${what}), covered by a stored grant: ${grant.label}.`,
+    };
+  }
+  switch (resolver.kind) {
+    case "allow":
+      return {
+        ...base,
+        resolver: cell,
+        outcome: "runs",
+        reason: `${tierName} (${what}); the ${layer} table allows it in this mode.`,
+      };
+    case "deny":
+      return {
+        ...base,
+        resolver: cell,
+        outcome: "denied",
+        reason:
+          interaction.resolver || (unattended && interaction.onDeny)
+            ? `${tierName} (${what}) needs a person, and this run is unattended: denied as interaction_required.`
+            : `${tierName} (${what}); the ${layer} table denies it.`,
+      };
+    case "human":
+      return {
+        ...base,
+        resolver: cell,
+        outcome: "prompts-you",
+        reason: `${tierName} (${what}): you are asked${tier === "soft-deny" ? " every time; nothing is remembered" : ""}.`,
+      };
+    case "judge":
+      return {
+        ...base,
+        resolver: cell,
+        outcome: tier === "soft-deny" ? "judge-soft-deny" : "judge-ask",
+        reason:
+          tier === "soft-deny"
+            ? `Soft-deny (${what}): the judge decides whether you explicitly asked for exactly this; a "no" ${resolver.onDeny === "human" ? "asks you" : "denies it"}. Grants do not apply.`
+            : `Ask (${what}): the judge decides; a "no" ${resolver.onDeny === "human" ? "asks you" : "denies it"}.`,
+      };
+  }
+}

package/src/policy-processor/index.ts

@@ -0,0 +1,6 @@
+/**
+ * YAML floor compiler and license wait. Remainder classifiers stay Scheme.
+ * Authors edit policy.json; they do not import this.
+ */
+
+export type { Disposition as Disposition, Policy as Policy } from "@inhuman.tools/policy/floor";

package/src/policy-processor/license.ts

@@ -0,0 +1,45 @@
+/**
+ * Monadic license. Admits the leaf onto the session intern, waits until
+ * LICENSE WHEN is a boolean, returns process-or-not. Floor and residual
+ * kicks live on `LicenseScope`. Does not write `approved`,
+ * `orchestrationResult`, or `regenerateable`. Nothing is remembered from a
+ * human allow here: a stored grant is a separate, explicit answer
+ * (`ask/answer` with `store`), and a soft-deny is licensed per call.
+ * Scope close mid-wait is not-process (false), not a throw. A boolean
+ * LICENSE WHEN still wins — Allow is a durable vote and must not lose to dispose.
+ */
+import { JOB_STOP_TOOL_NAME, type SessionRoot, type SessionTurn, type ToolCallJob } from "@inhuman.tools/harness-model";
+import { when } from "mobx";
+
+import { scopes } from "./scope.js";
+import { noteLicense } from "./unattended-guard.js";
+
+/**
+ * A denial the host decided before the license wait (an already-stamped block or deny). It still
+ * counts toward the unattended run's ledger.
+ */
+export async function noteDenied(job: ToolCallJob, root: SessionRoot): Promise<void> {
+  await noteLicense(scopes.get(root), job, false);
+}
+
+/**
+ * A tool's `isSideChannel` skips the floor. `triggersReactLoop: false` is
+ * loop control its author chose, not a license. `job_stop` skips too: the
+ * body only cancels jobs this session already spawned.
+ */
+export async function license(job: ToolCallJob, _turn: SessionTurn | null, root: SessionRoot): Promise<boolean> {
+  if (job.commFirst || job.isSideChannel || job.name === JOB_STOP_TOOL_NAME) return true;
+  const scope = scopes.get(root);
+  scope.admit(job);
+  try {
+    await when(() => scope.closed || job.cancelled || job.completed || job.licenseDecision !== null);
+    if (job.cancelled || job.completed) return false;
+    const decision = job.licenseDecision;
+    if (decision === null) return false;
+    // The unattended watch counts the call; a denial may be the one that trips bypass detection.
+    await noteLicense(scope, job, decision);
+    return decision;
+  } finally {
+    scope.release(job);
+  }
+}

package/src/policy-processor/peel-cwd.ts

@@ -0,0 +1 @@
+export { peelShellCwd } from "@inhuman.tools/policy-bash-disassembler";

package/src/policy-processor/real-path.ts

@@ -0,0 +1,41 @@
+/**
+ * Host half of file-path policy. The floor is pure and lexical; the tool opens whatever the
+ * filesystem says. A link inside the root that points at `.env` is named `notes.txt` to the floor
+ * and opens `.env` for the tool. This resolves symlinks (the deepest existing ancestor, so a
+ * write to a not-yet-created file under a linked directory resolves too) and re-expresses the
+ * result against the real root, so both spellings can be judged and the stricter verdict kept.
+ */
+import { realpath } from "node:fs/promises";
+import nodePath from "node:path";
+
+import { workspacePath } from "@inhuman.tools/harness-model";
+
+export async function realpathDeepest(absolute: string): Promise<string> {
+  const rest: string[] = [];
+  let current = absolute;
+  for (;;) {
+    try {
+      const real = await realpath(current);
+      return rest.length === 0 ? real : nodePath.join(real, ...rest.toReversed());
+    } catch {
+      const parent = nodePath.dirname(current);
+      if (parent === current) return absolute;
+      rest.push(nodePath.basename(current));
+      current = parent;
+    }
+  }
+}
+
+/**
+ * Workspace-relative spelling of the file the OS would open for `raw`, or undefined when it
+ * is the same as the lexical spelling (nothing to add).
+ */
+export async function resolvedWorkspacePath(rootPath: string, raw: string): Promise<string | undefined> {
+  if (rootPath.trim() === "" || !nodePath.isAbsolute(rootPath)) return undefined;
+  const lexical = workspacePath(rootPath, raw);
+  const absolute = nodePath.resolve(rootPath, raw.trim() === "" ? "." : raw);
+  const realRoot = await realpathDeepest(rootPath);
+  const realFile = await realpathDeepest(absolute);
+  const resolved = workspacePath(realRoot, realFile);
+  return resolved === lexical ? undefined : resolved;
+}