harnery 0.40.0 → 0.42.0

package/src/core/hooks/effects/image-capture.ts

@@ -22,6 +22,7 @@ import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { buildEventV3 } from "../../events/v3/builder.ts";
 import type { EventV3 } from "../../events/v3/contract.ts";
 import { writeEventV3 } from "../../events/v3/writer.ts";
+import { stateFileMode } from "../../storage/modes.ts";
 import type { ParsedPayload } from "../adapter/parse.ts";
 
 const IMAGE_EXTS = new Set(["png", "jpg", "jpeg", "gif", "webp", "bmp", "svg"]);
@@ -258,7 +259,7 @@ function captureOne(
     if (!existsSync(destination)) {
       mkdirSync(imagesDir, { recursive: true });
       const temporary = `${destination}.tmp.${process.pid}.${randomUUID().slice(0, 8)}`;
-      writeFileSync(temporary, bytes, { mode: 0o600 });
+      writeFileSync(temporary, bytes, { mode: stateFileMode() });
       renameSync(temporary, destination);
     }
     return { hash, ext, bytes: stat.size };

package/src/core/hooks/prompt-context/contract.ts

@@ -71,6 +71,7 @@ const DELIVERY_BY_ADAPTER: Readonly<Record<Adapter, PromptContextDelivery>> = {
   "claude-code": "direct",
   codex: "direct",
   cursor: "direct",
+  opencode: "direct",
 };
 
 export function promptContextDelivery(adapter: Adapter): PromptContextDelivery {

package/src/core/hooks/resolve/transcript.ts

@@ -132,7 +132,10 @@ export function scanSessionNameDisplayedImmediately(
 export type SessionNameDisplayInspection =
   | { state: "present" }
   | { state: "absent" }
-  | { state: "unavailable"; reason: "missing_transcript" | "transcript_not_ready" };
+  | {
+      state: "unavailable";
+      reason: "missing_transcript" | "transcript_not_ready" | "transcript_parse_error";
+    };
 
 /**
  * Inspect the ordered post-mint reply without conflating a malformed display
@@ -152,17 +155,34 @@ export function inspectSessionNameDisplayImmediately(
   if (!text) return { state: "unavailable", reason: "transcript_not_ready" };
   let sawMintResult = false;
   let awaitingReply = false;
+  let sawParseError = false;
+  let missedReplyAtToolBoundary = false;
   for (const line of text.split("\n")) {
     const row = parseTranscriptRow(line);
-    if (!row) continue;
+    if (!row) {
+      if (line.trim()) {
+        sawParseError = true;
+        // A corrupt row inside the evidence window could be the display.
+        // Never turn lost evidence into a negative observation.
+        if (awaitingReply) return { state: "unavailable", reason: "transcript_parse_error" };
+      }
+      continue;
+    }
     if (toolResponseMintedSessionName(row, name)) {
       sawMintResult = true;
       awaitingReply = true;
+      missedReplyAtToolBoundary = false;
       continue;
     }
     if (!awaitingReply) continue;
     const assistantText = assistantTextFromRow(row);
-    if (assistantText !== null) {
+    if (!assistantText?.trim() && rowContainsAssistantToolCall(row)) {
+      missedReplyAtToolBoundary = true;
+    }
+    // Claude Code streams thinking, text, and tool_use as separate rows with
+    // the same message id. Only visible text can satisfy or violate the
+    // display contract; an empty extraction is not a mismatching reply.
+    if (assistantText !== null && assistantText.trim().length > 0) {
       if (startsWithBlock(assistantText, name)) return { state: "present" };
       awaitingReply = false;
     }
@@ -173,12 +193,29 @@ export function inspectSessionNameDisplayImmediately(
   // rather than proof that the agent displayed the title incorrectly. Only a
   // transcript that contains the mint followed by a non-matching assistant
   // reply can safely deny the next tool.
-  if (!sawMintResult || awaitingReply) {
-    return { state: "unavailable", reason: "transcript_not_ready" };
+  if (!sawMintResult || awaitingReply || missedReplyAtToolBoundary) {
+    return {
+      state: "unavailable",
+      reason: !sawMintResult && sawParseError ? "transcript_parse_error" : "transcript_not_ready",
+    };
   }
   return { state: "absent" };
 }
 
+function rowContainsAssistantToolCall(row: Record<string, unknown>): boolean {
+  if (row.type === "assistant") {
+    const content = objectValue(row.message)?.content;
+    return (
+      Array.isArray(content) && content.some((block) => objectValue(block)?.type === "tool_use")
+    );
+  }
+  if (row.type === "response_item") {
+    const type = objectValue(row.payload)?.type;
+    return type === "function_call" || type === "custom_tool_call";
+  }
+  return false;
+}
+
 /**
  * Resolve a transcript path at the adapter boundary. Windows-native Codex can
  * send `C:\...` while the managed hook executes inside WSL, where the same

package/src/core/hooks/run-markers.ts

@@ -0,0 +1,132 @@
+/**
+ * Start markers for hook runs on adapters that kill a hook at its `timeout`
+ * (ADR 0197). A Codex hook that times out has its process tree killed and the
+ * tool proceeds without that hook's checks, and the killed process never
+ * reaches the completion receipt in `health.ts`. A small marker written at
+ * start and removed at completion leaves evidence of that case for doctor.
+ *
+ * Observer-only: every write, read, and removal swallows its own errors so a
+ * marker can never change hook behavior.
+ */
+
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Markers older than this are pruned when a new one is written. */
+const MARKER_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/** A run is unfinished once its marker outlives the timeout by this much. */
+const UNFINISHED_GRACE_MS = 30_000;
+
+export interface HookRunMarker {
+  event: string;
+  adapter: string;
+  pid: number;
+  started_at: string;
+  timeout_sec: number;
+}
+
+export function hookRunMarkerDir(coordRoot: string): string {
+  return join(coordRoot, ".harnery", "active", "hook-runs");
+}
+
+/** Write this run's marker; returns its path, or null when it could not be written. */
+export function writeHookRunMarker(
+  coordRoot: string,
+  marker: Omit<HookRunMarker, "started_at">,
+  now = new Date(),
+): string | null {
+  try {
+    const dir = hookRunMarkerDir(coordRoot);
+    mkdirSync(dir, { recursive: true });
+    pruneHookRunMarkers(dir, now.getTime());
+    const path = join(dir, `${marker.pid}-${safeName(marker.event)}.json`);
+    const body: HookRunMarker = { ...marker, started_at: now.toISOString() };
+    writeFileSync(path, `${JSON.stringify(body)}\n`);
+    return path;
+  } catch {
+    return null;
+  }
+}
+
+export function clearHookRunMarker(path: string | null): void {
+  if (!path) return;
+  try {
+    rmSync(path, { force: true });
+  } catch {
+    // Observer-only.
+  }
+}
+
+export interface UnfinishedHookRuns {
+  count: number;
+  /** Count per event name, most frequent first. */
+  events: Array<{ event: string; count: number }>;
+  latest: string | null;
+}
+
+/**
+ * Markers whose run outlived its timeout plus a grace period and whose
+ * process is gone, within the window. A live process past its timeout is
+ * still running and is not counted.
+ */
+export function findUnfinishedHookRuns(
+  coordRoot: string,
+  nowMs = Date.now(),
+  windowMs = 24 * 60 * 60 * 1000,
+  isAlive: (pid: number) => boolean = processAlive,
+): UnfinishedHookRuns {
+  const counts = new Map<string, number>();
+  let latest: string | null = null;
+  let count = 0;
+  let names: string[] = [];
+  try {
+    names = readdirSync(hookRunMarkerDir(coordRoot)).filter((n) => n.endsWith(".json"));
+  } catch {
+    return { count: 0, events: [], latest: null };
+  }
+  for (const name of names) {
+    let marker: HookRunMarker;
+    try {
+      marker = JSON.parse(
+        readFileSync(join(hookRunMarkerDir(coordRoot), name), "utf8"),
+      ) as HookRunMarker;
+    } catch {
+      continue;
+    }
+    const started = Date.parse(marker.started_at);
+    if (!Number.isFinite(started) || nowMs - started > windowMs) continue;
+    if (nowMs - started < marker.timeout_sec * 1000 + UNFINISHED_GRACE_MS) continue;
+    if (isAlive(marker.pid)) continue;
+    count++;
+    counts.set(marker.event, (counts.get(marker.event) ?? 0) + 1);
+    if (!latest || marker.started_at > latest) latest = marker.started_at;
+  }
+  const events = [...counts.entries()]
+    .map(([event, n]) => ({ event, count: n }))
+    .sort((a, b) => b.count - a.count || a.event.localeCompare(b.event));
+  return { count, events, latest };
+}
+
+function pruneHookRunMarkers(dir: string, nowMs: number): void {
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    try {
+      if (nowMs - statSync(path).mtimeMs > MARKER_RETENTION_MS) rmSync(path, { force: true });
+    } catch {
+      // Observer-only.
+    }
+  }
+}
+
+function processAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function safeName(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 64) || "unknown";
+}

package/src/core/hooks/session-name-presence.ts

@@ -25,16 +25,18 @@
 import { sessionNameDisplayAcceptedNames } from "../agents/session-name-display.ts";
 import { stampSessionNameSeen } from "../agents/state/heartbeat-writer.ts";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
+import type { SessionNameDisplayInspection } from "./resolve/transcript.ts";
 
 export interface SessionNamePresence {
   session_name_present?: boolean;
   session_name_present_for?: string;
+  session_name_unavailable_reason?: string;
 }
 
 export function sessionNamePresence(
   coordRoot: string,
   instanceId: string,
-  scanAssistantText: (name: string) => boolean,
+  scanAssistantText: (name: string) => SessionNameDisplayInspection,
 ): SessionNamePresence {
   try {
     const row = readLiveCoordinationRow(coordRoot, instanceId);
@@ -45,12 +47,17 @@ export function sessionNamePresence(
     }
     // A display of the title Harnery last asked for counts here too, so Stop
     // and the PreToolUse gate cannot disagree about the same reply.
-    const present = sessionNameDisplayAcceptedNames(row).some((candidate) =>
+    const inspections = sessionNameDisplayAcceptedNames(row).map((candidate) =>
       scanAssistantText(candidate),
     );
+    const present = inspections.some((inspection) => inspection.state === "present");
+    const unavailable = inspections.find((inspection) => inspection.state === "unavailable");
+    if (!present && unavailable?.state === "unavailable") {
+      return { session_name_unavailable_reason: unavailable.reason };
+    }
     if (present) stampSessionNameSeen(coordRoot, instanceId, name);
     return { session_name_present: present, session_name_present_for: name };
   } catch {
-    return {};
+    return { session_name_unavailable_reason: "observation_error" };
   }
 }

package/src/core/hooks/shell-waiter.ts

@@ -0,0 +1,166 @@
+/** Recognize inline waiters; this is not a proof of arbitrary shell termination. */
+const REASON =
+  "Inline shell waiter blocked: polling loops and delayed log-only checks can outlive the job " +
+  "and accumulate as background tasks. Read the existing task output now, or wait on its " +
+  "existing task handle. If polling is necessary, use a reviewed script with a hard deadline, " +
+  "nonzero timeout exit, and producer-exit/failure detection. Do not create another waiter " +
+  "to check progress or infer completion from a broad pgrep -f pattern.";
+
+interface Token {
+  value: string;
+  quoted: boolean;
+  operator?: boolean;
+}
+
+/** Keep quoted arguments opaque, including examples and heredoc bodies. */
+function tokenize(source: string): Token[] {
+  const out: Token[] = [];
+  const heredocs: { end: string; tabs: boolean }[] = [];
+  for (let i = 0; i < source.length; ) {
+    const ch = source[i]!;
+    if (ch === "\\" && source[i + 1] === "\n") {
+      i += 2;
+      continue;
+    }
+    if (ch === "\n") {
+      out.push({ value: ";", quoted: false, operator: true });
+      i++;
+      for (const doc of heredocs.splice(0)) {
+        while (i < source.length) {
+          const end = source.indexOf("\n", i);
+          const stop = end === -1 ? source.length : end;
+          const line = source.slice(i, stop);
+          i = end === -1 ? source.length : end + 1;
+          if ((doc.tabs ? line.replace(/^\t+/, "") : line) === doc.end) break;
+        }
+      }
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      i++;
+      continue;
+    }
+    if (ch === "#") {
+      const end = source.indexOf("\n", i);
+      i = end === -1 ? source.length : end;
+      continue;
+    }
+    if (";|&(){}<>".includes(ch)) {
+      const op = source.slice(i).match(/^(?:<<-?|>>|&&|\|\||[;|&(){}<>])/)![0];
+      out.push({ value: op, quoted: false, operator: true });
+      i += op.length;
+      continue;
+    }
+    let value = "";
+    let quoted = false;
+    while (i < source.length && !/[\s;|&(){}<>]/.test(source[i]!)) {
+      const next = source[i++]!;
+      if (next === "'" || next === '"' || next === "`") {
+        quoted = true;
+        while (i < source.length && source[i] !== next) {
+          if (source[i] === "\\" && next !== "'" && i + 1 < source.length) i++;
+          value += source[i++]!;
+        }
+        if (source[i] === next) i++;
+      } else if (next === "\\" && i < source.length) {
+        const escaped = source[i++]!;
+        if (escaped !== "\n") value += escaped;
+      } else {
+        value += next;
+      }
+    }
+    const previous = out.at(-1)?.value;
+    if (previous === "<<" || previous === "<<-") {
+      heredocs.push({ end: value, tabs: previous === "<<-" });
+    }
+    out.push({ value, quoted });
+  }
+  return out;
+}
+
+function basename(value: string): string {
+  return value.split(/[\\/]/).at(-1) ?? value;
+}
+
+function isWaiter(source: string, depth = 0): boolean {
+  if (depth > 8) return false;
+  const tokens = tokenize(source);
+  let loops = 0;
+  const commands: string[] = [];
+  let start = true;
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i]!;
+    if (token.operator) {
+      if ([";", "|", "||", "&", "&&", "(", ")", "{", "}"].includes(token.value)) start = true;
+      continue;
+    }
+    if (!start) continue;
+    if (!token.quoted) {
+      if (["while", "until", "for", "select"].includes(token.value)) {
+        loops++;
+        continue;
+      }
+      if (token.value === "done") {
+        loops = Math.max(0, loops - 1);
+        continue;
+      }
+      if (["do", "if", "then", "elif", "else", "!"].includes(token.value)) continue;
+      if (/^[A-Za-z_][A-Za-z_0-9]*=/.test(token.value)) continue;
+    }
+    const name = basename(token.value);
+    if (name === "timeout") {
+      // Skip timeout options and its duration; inspect the wrapped executable.
+      let j = i + 1;
+      for (; j < tokens.length && !tokens[j]!.operator; j++) {
+        if (/^(?:\d+(?:\.\d*)?|\.\d+)[smhd]?$/.test(tokens[j]!.value)) {
+          // -k/--kill-after takes its own duration before the main duration.
+          const previous = tokens[j - 1]?.value;
+          if (previous === "-k" || previous === "--kill-after") continue;
+          i = j;
+          break;
+        }
+      }
+      if (i === j) continue;
+    }
+    if (["command", "exec", "builtin", "nohup"].includes(name)) continue;
+    start = false;
+    commands.push(name);
+    if (loops && ["sleep", "pgrep"].includes(name)) return true;
+    if (["bash", "sh", "dash", "zsh", "ksh"].includes(name)) {
+      for (let j = i + 1; j < tokens.length && !tokens[j]!.operator; j++) {
+        if (/^-[a-z]*c[a-z]*$/.test(tokens[j]!.value)) {
+          const script = tokens[j + 1];
+          if (script && !script.operator && isWaiter(script.value, depth + 1)) return true;
+          break;
+        }
+      }
+    }
+  }
+  const sleep = commands.indexOf("sleep");
+  // sed can edit files or execute commands; its name alone does not prove a log read.
+  const readers = new Set(["tail", "cat", "head", "grep", "rg", "wc"]);
+  const harmless = new Set(["sleep", "cd", "pwd", "echo", "printf", "date", ...readers]);
+  return (
+    sleep !== -1 &&
+    commands.slice(sleep + 1).some((name) => readers.has(name)) &&
+    commands.every((name) => harmless.has(name))
+  );
+}
+
+export function shellWaiterReason(toolName: unknown, toolInput: unknown): string | null {
+  if (typeof toolName !== "string") return null;
+  const name = toolName.toLowerCase().replace(/^functions\./, "");
+  if (!["bash", "shell", "shell_command", "exec_command"].includes(name)) return null;
+  let input = toolInput;
+  if (typeof input === "string") {
+    try {
+      input = JSON.parse(input);
+    } catch {
+      return null;
+    }
+  }
+  if (!input || typeof input !== "object") return null;
+  const args = input as Record<string, unknown>;
+  const command = args.command ?? args.cmd;
+  return typeof command === "string" && isWaiter(command) ? REASON : null;
+}

package/src/core/resources/service.ts

@@ -14,6 +14,7 @@ import { hostname, platform } from "node:os";
 import { resolve } from "node:path";
 import { checkPidToken, processStartToken } from "../agents/state/proc-start.ts";
 import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/logger.ts";
+import { stateDirMode, stateFileMode } from "../storage/modes.ts";
 import {
   RESOURCE_SERVICE_STATUS_SCHEMA_VERSION,
   type ResourceSamplerState,
@@ -60,7 +61,7 @@ export async function spawnResourceService(
   }
   const intervalMs = normalizeInterval(options.intervalMs);
   const paths = resourcePaths(coordRoot);
-  mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+  mkdirSync(paths.root, { recursive: true, mode: stateDirMode() });
   rmSync(paths.stop, { force: true });
   const harnBin = new URL("../../../bin/harn", import.meta.url).pathname;
   if (!existsSync(harnBin)) throw new Error(`cannot find harn executable at ${harnBin}`);
@@ -122,7 +123,7 @@ export function requestResourceServiceStop(coordRootRaw: string): ResourceServic
   const coordRoot = resolve(coordRootRaw);
   const paths = resourcePaths(coordRoot);
   const status = readResourceServiceStatus(coordRoot);
-  mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+  mkdirSync(paths.root, { recursive: true, mode: stateDirMode() });
   writePrivateJsonAtomic(paths.stop, {
     requested_at: new Date().toISOString(),
     requested_by_pid: process.pid,
@@ -231,7 +232,7 @@ export async function runResourceService(
 
 function acquireLease(coordRoot: string, now: Date): ResourceServiceLease {
   const paths = resourcePaths(coordRoot);
-  mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+  mkdirSync(paths.root, { recursive: true, mode: stateDirMode() });
   for (let attempt = 0; attempt < 2; attempt++) {
     const daemonStartToken = processStartToken(process.pid);
     const lease: ResourceServiceLease = {
@@ -242,7 +243,7 @@ function acquireLease(coordRoot: string, now: Date): ResourceServiceLease {
       created_at: now.toISOString(),
     };
     try {
-      const fd = openSync(paths.lease, "wx", 0o600);
+      const fd = openSync(paths.lease, "wx", stateFileMode());
       try {
         writeFileSync(fd, `${JSON.stringify(lease)}\n`, "utf8");
       } finally {

package/src/core/semantic/review.ts

@@ -11,6 +11,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { stateDirMode, stateFileMode } from "../storage/modes.ts";
 import type {
   SemanticAcceptedReadModelV2,
   SemanticConfiguredModel,
@@ -630,12 +631,12 @@ function writePrivateJsonAtomic(path: string, value: unknown): void {
   const body = `${JSON.stringify(value, null, 2)}\n`;
   if (Buffer.byteLength(body) > MAX_JSON_BYTES)
     throw new Error("semantic review file is too large");
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  chmodSync(dirname(path), 0o700);
+  mkdirSync(dirname(path), { recursive: true, mode: stateDirMode() });
+  chmodSync(dirname(path), stateDirMode());
   const temporary = `${path}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
-  writeFileSync(temporary, body, { encoding: "utf8", flag: "wx", mode: 0o600 });
+  writeFileSync(temporary, body, { encoding: "utf8", flag: "wx", mode: stateFileMode() });
   renameSync(temporary, path);
-  chmodSync(path, 0o600);
+  chmodSync(path, stateFileMode());
 }
 
 function isSemanticReviewCandidate(value: unknown): value is SemanticReviewCandidateV1 {

package/src/core/semantic/service.ts

@@ -30,6 +30,7 @@ import {
   legacyLogFields,
   processLogger,
 } from "../storage/logger.ts";
+import { stateDirMode, stateFileMode } from "../storage/modes.ts";
 import type { SemanticHarness } from "./contract.ts";
 import { runSemanticOnce, type SemanticOnceReport } from "./once.ts";
 import { semanticPendingPassDue } from "./scheduler.ts";
@@ -145,10 +146,10 @@ export async function spawnSemanticService(
     throw new Error(`semantic service is already running under pid ${current.record?.pid}`);
   }
   const paths = semanticPaths(coordRoot);
-  mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+  mkdirSync(paths.root, { recursive: true, mode: stateDirMode() });
   const sharedLogs = coordEnv("SHARED_LOGS") !== "0";
-  const logFd = sharedLogs ? undefined : openSync(paths.log, "a", 0o600);
-  if (logFd !== undefined) chmodSync(paths.log, 0o600);
+  const logFd = sharedLogs ? undefined : openSync(paths.log, "a", stateFileMode());
+  if (logFd !== undefined) chmodSync(paths.log, stateFileMode());
   const harnBin = new URL("../../../bin/harn", import.meta.url).pathname;
   if (!existsSync(harnBin)) {
     if (logFd !== undefined) closeSync(logFd);
@@ -225,7 +226,7 @@ export async function ensureSemanticServiceRunning(
 export function requestSemanticServiceStop(coordRootRaw: string): SemanticServiceStatus {
   const coordRoot = resolve(coordRootRaw);
   const status = readSemanticServiceStatus(coordRoot);
-  mkdirSync(semanticPaths(coordRoot).root, { recursive: true, mode: 0o700 });
+  mkdirSync(semanticPaths(coordRoot).root, { recursive: true, mode: stateDirMode() });
   writePrivateJsonAtomic(semanticPaths(coordRoot).stop, {
     requested_at: new Date().toISOString(),
     requested_by_pid: process.pid,
@@ -452,7 +453,7 @@ export async function runSemanticServiceDaemon(
 
 export function acquireSemanticServiceLease(coordRootRaw: string): () => void {
   const path = semanticPaths(coordRootRaw).lease;
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  mkdirSync(dirname(path), { recursive: true, mode: stateDirMode() });
   const owner: SemanticServiceLease = {
     pid: process.pid,
     host: hostname(),
@@ -461,7 +462,7 @@ export function acquireSemanticServiceLease(coordRootRaw: string): () => void {
   };
   const acquire = (): boolean => {
     try {
-      const fd = openSync(path, "wx", 0o600);
+      const fd = openSync(path, "wx", stateFileMode());
       try {
         writeFileSync(fd, `${JSON.stringify(owner)}\n`, "utf8");
       } finally {
@@ -671,20 +672,20 @@ function prepareSemanticServiceDiagnostic(entry: Record<string, unknown>): {
 
 function appendSemanticServiceLegacyLog(coordRoot: string, entry: Record<string, unknown>): void {
   const path = semanticPaths(coordRoot).log;
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  mkdirSync(dirname(path), { recursive: true, mode: stateDirMode() });
   appendFileSync(
     path,
     `${JSON.stringify({ schema_version: 1, ts: new Date().toISOString(), ...entry })}\n`,
-    { encoding: "utf8", mode: 0o600 },
+    { encoding: "utf8", mode: stateFileMode() },
   );
-  chmodSync(path, 0o600);
+  chmodSync(path, stateFileMode());
   if (statSync(path).size <= MAX_LOG_BYTES) return;
   const buffer = readFileSync(path);
   const tail = buffer.subarray(Math.max(0, buffer.length - Math.floor(MAX_LOG_BYTES / 2)));
   const newline = tail.indexOf(10);
   const body = newline >= 0 ? tail.subarray(newline + 1) : tail;
   const temporary = `${path}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
-  writeFileSync(temporary, body, { flag: "wx", mode: 0o600 });
+  writeFileSync(temporary, body, { flag: "wx", mode: stateFileMode() });
   renameSync(temporary, path);
 }
 
@@ -693,12 +694,12 @@ function writePrivateJsonAtomic(path: string, value: unknown): void {
   if (Buffer.byteLength(body) > MAX_FILE_BYTES) {
     throw new Error(`semantic service file exceeds ${MAX_FILE_BYTES} bytes`);
   }
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  chmodSync(dirname(path), 0o700);
+  mkdirSync(dirname(path), { recursive: true, mode: stateDirMode() });
+  chmodSync(dirname(path), stateDirMode());
   const temporary = `${path}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
-  writeFileSync(temporary, body, { encoding: "utf8", flag: "wx", mode: 0o600 });
+  writeFileSync(temporary, body, { encoding: "utf8", flag: "wx", mode: stateFileMode() });
   renameSync(temporary, path);
-  chmodSync(path, 0o600);
+  chmodSync(path, stateFileMode());
 }
 
 function validTimestamp(value: unknown): value is string {

package/src/core/semantic/storage.ts

@@ -13,6 +13,7 @@ import {
 import { dirname, join, resolve } from "node:path";
 import { canonicalJsonV3, sha256V3 } from "../events/v3/canonical.ts";
 import type { LedgerCursorV3 } from "../events/v3/reader.ts";
+import { stateDirMode, stateFileMode } from "../storage/modes.ts";
 import type {
   SEMANTIC_EVIDENCE_CONTRACT_VERSION,
   SEMANTIC_PROMPT_CONTRACT_VERSION,
@@ -291,10 +292,10 @@ function writePrivateJsonAtomic(path: string, value: unknown): void {
   if (Buffer.byteLength(body) > MAX_JSON_BYTES) {
     throw new Error(`semantic file exceeds ${MAX_JSON_BYTES} bytes`);
   }
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  chmodSync(dirname(path), 0o700);
+  mkdirSync(dirname(path), { recursive: true, mode: stateDirMode() });
+  chmodSync(dirname(path), stateDirMode());
   const temporary = `${path}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
-  writeFileSync(temporary, body, { encoding: "utf8", flag: "wx", mode: 0o600 });
+  writeFileSync(temporary, body, { encoding: "utf8", flag: "wx", mode: stateFileMode() });
   renameSync(temporary, path);
-  chmodSync(path, 0o600);
+  chmodSync(path, stateFileMode());
 }