fix(tools): a read-only workspace is a condition, not a defect (BRO-2227)

`chmod 555 <workspace>` then `propose` returned UNEXPECTED with a raw EACCES,
and exit 1. The CLI's own contract says exit 1 means a defect and UNEXPECTED is
"the backstop that should never fire" -- so an operator was told Parallax is
broken when the accurate answer was that their directory is not writable. The
two have completely different remedies, and the wrong one sends someone reading
our source instead of their mount options.

It is also not a rare case: a read-only bind mount is the confinement posture
this design assumes, so a tenant hits it on the first call.

Every write in src/tools/state.ts now goes through one guard that maps EACCES,
EROFS, EPERM and ENOSPC to a distinct WorkspaceNotWritableError. A distinct
class rather than a generic wrap, so every OTHER throw still reaches the
backstop, which is where an actual defect belongs.

Both adapters map it identically -- WORKSPACE_NOT_WRITABLE, and the CLI returns
2 (a typed refusal) rather than 1. A condition that is a typed refusal on one
surface and a crash on the other is precisely the divergence the "agent is a
user" claim rules out, so the two backstops carry the same mapping rather than
one delegating politeness to the other.

Verified on both surfaces with the control: read-only refuses with the code on
CLI and tools alike, writable still returns ok on both.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: broomva

src/cli.ts

@@ -1,6 +1,7 @@
 import { DEFAULT_DOMAIN, DOMAIN_KEYS } from "./tools/domains";
 import { type AnyErrorCode, fail, ok, type ParallaxError, type Result } from "./tools/errors";
 import * as handlers from "./tools/handlers";
+import { WorkspaceNotWritableError } from "./tools/state";
 
 /**
  * Parallax at a terminal.
@@ -482,6 +483,23 @@ export async function runCli(argv: readonly string[], io: Io = stdio): Promise<n
   try {
     return await main(argv, io);
   } catch (e) {
+    // A workspace that cannot be written to is an expectable condition, not a
+    // defect in this program -- and it is the confinement posture the design
+    // assumes, so it is the FIRST thing a tenant on a read-only mount hits.
+    // Reporting it as UNEXPECTED told the operator Parallax is broken when the
+    // accurate answer was that their directory is not writable; the two have
+    // completely different remedies. Exit 2 (a typed refusal), not 1 (a defect).
+    if (e instanceof WorkspaceNotWritableError) {
+      io.err(
+        `${JSON.stringify({
+          code: "WORKSPACE_NOT_WRITABLE",
+          reason:
+            "Parallax needs to write its thread state to .parallax/ in this directory, and the directory is not writable",
+          detail: { root: e.root, cause: e.cause },
+        })}\n`,
+      );
+      return 2;
+    }
     io.err(
       `${JSON.stringify({
         code: "UNEXPECTED",

src/tools/errors.ts

@@ -24,6 +24,7 @@ export type ToolErrorCode =
   | "WORKSPACE_UNREADABLE"
   | "ROOT_NOT_ALLOWED"
   | "WORKSPACE_DENIED"
+  | "WORKSPACE_NOT_WRITABLE"
   | "TABLES_REQUIRED"
   // pending-proposal addressing
   | "NO_PENDING_PROPOSAL"

src/tools/index.ts

@@ -10,6 +10,7 @@ import {
   type ZodLike,
   type ZodTypeLike,
 } from "./schemas";
+import { WorkspaceNotWritableError } from "./state";
 
 /**
  * Parallax as a set of tools an agent calls.
@@ -399,6 +400,22 @@ async function runTool(
     if (!checked.ok) return checked;
     return await handler(checked.value);
   } catch (e) {
+    // Same mapping as the CLI backstop, for the same reason: a workspace that
+    // cannot be written to is an expectable condition, not a defect in this
+    // program. Both surfaces must name it identically -- a condition that is a
+    // typed refusal on one surface and a crash on the other is exactly the
+    // divergence the "agent is a user" claim rules out.
+    if (e instanceof WorkspaceNotWritableError) {
+      return {
+        ok: false,
+        error: {
+          code: "WORKSPACE_NOT_WRITABLE",
+          reason:
+            "Parallax needs to write its thread state to .parallax/ in this directory, and the directory is not writable",
+          detail: { root: e.root, cause: e.cause },
+        },
+      };
+    }
     return {
       ok: false,
       error: {

src/tools/state.ts

@@ -37,8 +37,49 @@ export function stateRoot(cwd: string = process.cwd()): string {
 
 /** Reads never create directories. Only writes do -- so a failed lookup leaves no trace. */
 function ensureDirs(root: string): void {
-  for (const d of ["pending", "accepted", "rejected", "runs"]) {
-    mkdirSync(join(root, d), { recursive: true });
+  guardWrite(root, () => {
+    for (const d of ["pending", "accepted", "rejected", "runs"]) {
+      mkdirSync(join(root, d), { recursive: true });
+    }
+  });
+}
+
+/**
+ * Raised when the workspace cannot be written to.
+ *
+ * A read-only workspace is a legitimate, expectable condition -- it is the
+ * confinement posture this whole design assumes, and a tenant on a read-only
+ * bind mount hits it on the first call. It was surfacing as UNEXPECTED, which
+ * the CLI's own contract defines as "a defect, the backstop that should never
+ * fire". So the operator was told Parallax is broken when the accurate answer
+ * was that their directory is not writable, and the two have completely
+ * different remedies.
+ *
+ * Carried as a distinct class rather than a raw fs error so the adapter layer
+ * can map exactly this to a typed code and let every other throw keep going to
+ * the backstop, where it belongs.
+ */
+export class WorkspaceNotWritableError extends Error {
+  readonly root: string;
+  readonly cause?: string;
+  constructor(root: string, cause: string) {
+    super(`the workspace is not writable: ${cause}`);
+    this.name = "WorkspaceNotWritableError";
+    this.root = root;
+    this.cause = cause;
+  }
+}
+
+/** Every write in this module goes through here, so the mapping cannot be bypassed. */
+function guardWrite<T>(root: string, f: () => T): T {
+  try {
+    return f();
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException)?.code;
+    if (code === "EACCES" || code === "EROFS" || code === "EPERM" || code === "ENOSPC") {
+      throw new WorkspaceNotWritableError(root, e instanceof Error ? e.message : String(e));
+    }
+    throw e;
   }
 }
 
@@ -47,9 +88,11 @@ function ensureDirs(root: string): void {
  * reader silently accepts as a smaller version of the truth.
  */
 function writeJson(path: string, value: unknown): void {
-  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
-  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
-  renameSync(tmp, path);
+  guardWrite(path, () => {
+    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+    renameSync(tmp, path);
+  });
 }
 
 function readJson<T>(path: string): T | null {
@@ -130,8 +173,10 @@ export function writeHead(root: string, proposalId: string | null): void {
     return;
   }
   const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
-  writeFileSync(tmp, `${proposalId}\n`);
-  renameSync(tmp, path);
+  guardWrite(path, () => {
+    writeFileSync(tmp, `${proposalId}\n`);
+    renameSync(tmp, path);
+  });
 }
 
 export interface RejectionRecord {
@@ -257,8 +302,10 @@ export function writeRun(root: string, rec: RunRecord, html: string): void {
   writeJson(join(root, "runs", `${rec.runId}.json`), rec);
   const path = join(root, "runs", `${rec.runId}.html`);
   const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
-  writeFileSync(tmp, html);
-  renameSync(tmp, path);
+  guardWrite(path, () => {
+    writeFileSync(tmp, html);
+    renameSync(tmp, path);
+  });
 }
 
 export function readRun(root: string, runId: string): RunRecord | null {