harnery 0.40.0 → 0.41.0

package/src/core/agents/session-events.ts

@@ -4,7 +4,7 @@
  * `writeSessionEvent` records command spans in the canonical V3 ledger.
  */
 
-import { randomBytes } from "node:crypto";
+import { createHash, type Hash, randomBytes } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 // Kept dependency-light: vendored verbatim into a downstream consumer, so no coordEnv import.
@@ -64,18 +64,52 @@ export function readLastIntent(instanceId?: string): string | null {
   }
 }
 
-const outputSequence = new Map<string, number>();
+type OutputStream = "stdout" | "stderr" | "combined";
+
+interface OutputSummary {
+  stream: OutputStream;
+  bytes: number;
+  lines: number;
+  chunks: number;
+  hash: Hash;
+}
+
+interface PendingCommand {
+  coordRoot: string;
+  fields: Record<string, unknown>;
+  streams: Map<OutputStream, OutputSummary>;
+}
+
+const pendingCommands = new Map<string, PendingCommand>();
+let exitFlushInstalled = false;
+
+function commandKey(fields: Record<string, unknown>): string | undefined {
+  return typeof fields.instance_id === "string" && typeof fields.cmd_id === "string"
+    ? JSON.stringify([fields.instance_id, fields.cmd_id])
+    : undefined;
+}
+
+function flushCommandOutput(command: PendingCommand): void {
+  for (const summary of command.streams.values()) {
+    recordCommandObservation("command.output_observed", command.fields, command.coordRoot, summary);
+  }
+  command.streams.clear();
+}
 
 /** Emit a command/narration event to the canonical stream. Swallows every
  * error and skips when identity can't be resolved: telemetry must never break
  * or slow down a command. */
-function recordCommandObservation(type: SessionEventType, fields: Record<string, unknown>): void {
+function recordCommandObservation(
+  type: SessionEventType,
+  fields: Record<string, unknown>,
+  coordRoot: string,
+  summary?: OutputSummary,
+): boolean {
   const instanceId = typeof fields.instance_id === "string" ? fields.instance_id : undefined;
-  if (!instanceId) return;
+  if (!instanceId) return false;
   try {
-    const coordRoot = coordinationRootPath();
     const route = resolveLiveEventLedgerRouteV3(coordRoot);
-    if (route.state === "blocked") return;
+    if (route.state === "blocked") return false;
     const liveInstanceId = liveInstanceIdV3(instanceId);
     const hook = readHookProducerStateByInstanceV3(coordRoot, liveInstanceId);
     if (!hook) {
@@ -84,10 +118,10 @@ function recordCommandObservation(type: SessionEventType, fields: Record<string,
         instance_id: instanceId,
         reason: "hook_generation_not_found",
       });
-      return;
+      return false;
     }
-    const command = commandSignalAndObservation(type, fields);
-    if (!command) return;
+    const command = commandSignalAndObservation(type, fields, summary);
+    if (!command) return false;
     const result = recordCommandSignalV3({
       coordRoot,
       mode: route.mode,
@@ -105,7 +139,7 @@ function recordCommandObservation(type: SessionEventType, fields: Record<string,
       const expectedLifecycleReopenGap =
         result.reason === "turn_not_started" &&
         hook.session_start_derivation === "approved_lifecycle_reopen";
-      if (expectedLifecycleReopenGap) return;
+      if (expectedLifecycleReopenGap) return false;
       writeProducerDiagnosticV3(coordRoot, "command_emit_unjoinable", {
         type,
         instance_id: instanceId,
@@ -120,10 +154,10 @@ function recordCommandObservation(type: SessionEventType, fields: Record<string,
         result_state: result.state,
       });
     }
+    return result.state === "recorded" || result.state === "already_recorded";
   } catch (error) {
     // Telemetry must never break the command, but the loss is preserved.
     try {
-      const coordRoot = coordinationRootPath();
       writeProducerDiagnosticV3(coordRoot, "command_emit_failed", {
         type,
         instance_id: instanceId,
@@ -132,17 +166,26 @@ function recordCommandObservation(type: SessionEventType, fields: Record<string,
     } catch {
       /* diagnostics are best-effort */
     }
+    return false;
   }
 }
 
+/** Count the non-empty lines in one output chunk; a single event may carry many. */
+export function countOutputLines(text: string): number {
+  if (!text) return 0;
+  let count = 0;
+  for (const line of text.split("\n")) if (line.length > 0) count += 1;
+  return count;
+}
+
 function commandSignalAndObservation(
   type: SessionEventType,
   fields: Record<string, unknown>,
+  summary?: OutputSummary,
 ): { signal: CommandSignalV3; observation: CommandObservationV3 } | undefined {
   const commandId = typeof fields.cmd_id === "string" ? fields.cmd_id : undefined;
   if (!commandId) return undefined;
   if (type === "command.started") {
-    outputSequence.set(commandId, 0);
     const command = typeof fields.cmd === "string" ? fields.cmd : "";
     const executable = command.trim().split(/\s+/, 1)[0] || "unknown";
     return {
@@ -161,24 +204,25 @@ function commandSignalAndObservation(
     };
   }
   if (type === "command.output_observed") {
-    const sequence = (outputSequence.get(commandId) ?? 0) + 1;
-    outputSequence.set(commandId, sequence);
-    const line = typeof fields.line === "string" ? fields.line : "";
-    const stream =
-      fields.stream === "stdout" || fields.stream === "stderr" ? fields.stream : "combined";
+    if (!summary) return undefined;
     return {
       signal: "command.output_observed",
       observation: {
         native_command_id: commandId,
-        native_observation_id: `${commandId}:output:${sequence}`,
-        stream,
-        output: line,
-        output_bytes: Buffer.byteLength(line, "utf8"),
-        output_lines: line ? 1 : 0,
+        native_observation_id: `${commandId}:output-summary:${summary.stream}`,
+        stream: summary.stream,
+        // The normalizer HMACs this bounded descriptor with the generation key.
+        // Neither raw output nor its unkeyed digest is written to the ledger.
+        output: {
+          format: "harnery-output-chunks-v1",
+          chunks: summary.chunks,
+          sha256: summary.hash.digest("hex"),
+        },
+        output_bytes: summary.bytes,
+        output_lines: summary.lines,
       },
     };
   }
-  outputSequence.delete(commandId);
   const exitCode =
     typeof fields.exit === "number" && Number.isSafeInteger(fields.exit) ? fields.exit : undefined;
   return {
@@ -197,14 +241,64 @@ function commandSignalAndObservation(
 }
 
 /**
- * Record a command event in V3. Best-effort, never throws into the caller;
- * telemetry must not break or slow a command.
+ * Start/completion use the durable V3 recorder. Output only updates bounded
+ * per-stream counters and hashes; summaries flush before completion or at
+ * process exit. A forced kill can lose unflushed summaries (ADR 0188).
+ * Best-effort: telemetry never throws into the caller.
  */
 export function writeSessionEvent(
   type: SessionEventType,
   fields: Record<string, unknown> = {},
 ): void {
-  recordCommandObservation(type, fields);
+  try {
+    const key = commandKey(fields);
+    if (!key) return;
+    if (type === "command.output_observed") {
+      const command = pendingCommands.get(key);
+      if (!command) return;
+      const stream =
+        fields.stream === "stdout" || fields.stream === "stderr" ? fields.stream : "combined";
+      let summary = command.streams.get(stream);
+      if (!summary) {
+        summary = { stream, bytes: 0, lines: 0, chunks: 0, hash: createHash("sha256") };
+        command.streams.set(stream, summary);
+      }
+      const line = typeof fields.line === "string" ? fields.line : "";
+      const normalized = line.normalize("NFC");
+      // Length framing preserves chunk boundaries, including empty chunks.
+      summary.hash.update(`${Buffer.byteLength(normalized, "utf8")}:`).update(normalized);
+      summary.bytes += Buffer.byteLength(line, "utf8");
+      summary.lines += countOutputLines(line);
+      summary.chunks += 1;
+      return;
+    }
+    const command = pendingCommands.get(key);
+    const coordRoot = command?.coordRoot ?? coordinationRootPath();
+    if (type === "command.completed") {
+      pendingCommands.delete(key);
+      if (command) flushCommandOutput(command);
+      recordCommandObservation(type, fields, coordRoot);
+    } else if (recordCommandObservation(type, fields, coordRoot) && !command) {
+      pendingCommands.set(key, {
+        coordRoot,
+        fields: {
+          instance_id: fields.instance_id,
+          cmd_id: fields.cmd_id,
+          bridge: fields.bridge,
+        },
+        streams: new Map(),
+      });
+      if (!exitFlushInstalled) {
+        exitFlushInstalled = true;
+        process.once("exit", () => {
+          for (const pending of pendingCommands.values()) flushCommandOutput(pending);
+          pendingCommands.clear();
+        });
+      }
+    }
+  } catch {
+    // Root resolution and in-memory bookkeeping must not break the command.
+  }
 }
 
 /** Trim long values to keep individual events small. */

package/src/core/agents/session-finalization-state-v3.ts

@@ -2,6 +2,7 @@ import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import type { ApprovedSessionEndReasonV3 } from "../events/v3/producers/recorder.ts";
 import { EVENT_V3_LEDGER_RELATIVE_ROOT } from "../events/v3/reader.ts";
+import { stateModeTooOpen } from "../storage/modes.ts";
 
 export const SESSION_FINALIZATION_REQUEST_FORMAT_V3 =
   "harnery-v3-session-finalization-request" as const;
@@ -72,7 +73,7 @@ export function listSessionFinalizationRequestsV3(
 
 export function readSessionFinalizationRequestV3(filePath: string): SessionFinalizationRequestV3 {
   const metadata = lstatSync(filePath);
-  if (!metadata.isFile() || metadata.isSymbolicLink() || (metadata.mode & 0o077) !== 0) {
+  if (!metadata.isFile() || metadata.isSymbolicLink() || stateModeTooOpen(metadata.mode)) {
     throw new Error("V3 session finalization request is unsafe");
   }
   const request = JSON.parse(readFileSync(filePath, "utf8")) as SessionFinalizationRequestV3;

package/src/core/agents/session-finalizer-v3.ts

@@ -32,6 +32,7 @@ import {
 import { readLedgerV3 } from "../events/v3/reader.ts";
 import { assertEventV3 } from "../events/v3/validate.ts";
 import { EVENT_V3_LEDGER_RELATIVE_ROOT, writeEventV3 } from "../events/v3/writer.ts";
+import { stateDirMode, stateFileMode } from "../storage/modes.ts";
 import { fsyncParentDirectory } from "../workflow/durable-record.ts";
 import { acquireNoClobberLease } from "../workflow/workspaces/leases.ts";
 import { readCodexArchiveObservationsV3 } from "./codex-archive-v3.ts";
@@ -901,20 +902,20 @@ function writeRequest(
   create = false,
 ): void {
   const directory = sessionFinalizationRequestDirectoryV3(coordRoot);
-  mkdirSync(directory, { recursive: true, mode: 0o700 });
-  chmodSync(directory, 0o700);
+  mkdirSync(directory, { recursive: true, mode: stateDirMode() });
+  chmodSync(directory, stateDirMode());
   const path = sessionFinalizationRequestPathV3(coordRoot, request.request_id);
   if (create && existsSync(path)) throw new Error("V3 finalization request already exists");
   const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
   let fd: number | undefined;
   try {
-    fd = openSync(temporary, "wx", 0o600);
+    fd = openSync(temporary, "wx", stateFileMode());
     writeFileSync(fd, `${JSON.stringify(request)}\n`, "utf8");
     fsyncSync(fd);
     closeSync(fd);
     fd = undefined;
     renameSync(temporary, path);
-    chmodSync(path, 0o600);
+    chmodSync(path, stateFileMode());
     fsyncParentDirectory(path);
   } finally {
     if (fd !== undefined) closeSync(fd);

package/src/core/agents/session-name-display.ts

@@ -9,8 +9,17 @@ export interface SessionNameDisplayState {
   suggested_session_name?: string;
   session_name_seen_for?: string;
   session_name_display_requested_for?: string;
+  session_name_display_reminders?: number;
 }
 
+/**
+ * How many times PostToolUse may re-attach the display instruction after the
+ * mint-time one, per requested title. Two covers the observed miss (the model
+ * narrates, calls a tool, and forgets) without turning an unreadable
+ * transcript into a reminder on every tool for the rest of the session.
+ */
+export const SESSION_NAME_DISPLAY_REMINDER_LIMIT = 2;
+
 export const SESSION_NAME_DISPLAY_NOTE =
   "Next, before any prose or another tool call, send suggested_session_name verbatim by itself in a fenced code block.";
 
@@ -76,6 +85,45 @@ export function sessionNameDisplayInstruction(name: string): string {
   ].join("\n");
 }
 
+/**
+ * Whether an ordinary tool result should carry a bounded reminder.
+ *
+ * Only after the mint-time instruction has gone out (`requested_for` is set
+ * for the pending title), and only while the counter is under the cap. The
+ * transcript is deliberately not consulted: PreToolUse already stamped a
+ * readable sighting, and an unreadable one is exactly the case the reminder
+ * exists for.
+ */
+export function sessionNameDisplayReminderDue(
+  row: SessionNameDisplayState | null | undefined,
+): string | null {
+  const pending = sessionNameDisplayPending(row);
+  if (!pending || row?.session_name_display_requested_for !== pending) return null;
+  return (row.session_name_display_reminders ?? 0) < SESSION_NAME_DISPLAY_REMINDER_LIMIT
+    ? pending
+    : null;
+}
+
+/**
+ * The follow-up nudge for a title still pending after an ordinary tool.
+ *
+ * Worded so the model can answer it from its own memory: the desktop transcript
+ * sometimes drops a text row that the operator did see, so Harnery cannot tell
+ * a skipped block from an unrecorded one. A model that already showed the block
+ * is told to do nothing, which is what keeps the reminder from producing
+ * duplicate blocks in the chat.
+ */
+export function sessionNameDisplayReminder(name: string): string {
+  return [
+    "Session name still pending.",
+    "If you have not already shown it this turn, send this exact fenced block as your next assistant text, before any prose or another tool call:",
+    "",
+    sessionNameDisplayBlock(name),
+    "",
+    "If you already showed that block, do nothing; Harnery could not read the transcript row and is asking once more.",
+  ].join("\n");
+}
+
 export function sessionNameDisplayRecoveryInstruction(name: string, binName: string): string {
   return [
     sessionNameDisplayInstruction(name),

package/src/core/agents/state/heartbeat-reader.ts

@@ -40,6 +40,13 @@ export interface Heartbeat {
    * counts so that drift cannot strand the latch.
    */
   session_name_display_requested_for?: string;
+  /**
+   * How many bounded PostToolUse reminders have gone out for
+   * `session_name_display_requested_for`. Reset whenever a different title is
+   * requested. Caps the nudge so an unreadable transcript never turns into an
+   * endless stream of "show the block" context.
+   */
+  session_name_display_reminders?: number;
   last_status_at?: string;
   current_turn_id?: string;
   parent_instance_id?: string;

package/src/core/agents/state/heartbeat-writer.ts

@@ -194,12 +194,34 @@ export function stampSessionNameRequested(
   coordRoot: string,
   instanceId: string,
   name: string,
+): Heartbeat | null {
+  if (!name) return null;
+  return mutate(coordRoot, instanceId, (hb) => {
+    if (hb.session_name_display_requested_for === name) return hb;
+    const { session_name_display_reminders: _reset, ...rest } = hb;
+    return { ...rest, session_name_display_requested_for: name };
+  });
+}
+
+/**
+ * Count one bounded PostToolUse reminder for the title currently requested.
+ *
+ * The mint-time instruction is the only thing that used to make the block
+ * appear; a model that went straight to another tool was never asked again,
+ * because the fail-open gate writes its reason to stderr, which the model
+ * cannot read. The counter lets the hook re-attach the instruction a fixed
+ * number of times and then stop, whatever the transcript can or cannot prove.
+ */
+export function stampSessionNameReminded(
+  coordRoot: string,
+  instanceId: string,
+  name: string,
 ): Heartbeat | null {
   if (!name) return null;
   return mutate(coordRoot, instanceId, (hb) =>
     hb.session_name_display_requested_for === name
-      ? hb
-      : { ...hb, session_name_display_requested_for: name },
+      ? { ...hb, session_name_display_reminders: (hb.session_name_display_reminders ?? 0) + 1 }
+      : hb,
   );
 }
 

package/src/core/agents/state/live-coordination-view.ts

@@ -198,6 +198,7 @@ export function projectHeartbeatV3(
     session_name_seen_at: cache?.session_name_seen_at,
     session_name_seen_for: cache?.session_name_seen_for,
     session_name_display_requested_for: cache?.session_name_display_requested_for,
+    session_name_display_reminders: cache?.session_name_display_reminders,
     workflow_run_id: generation.run_id,
     workflow_agent_id: generation.workflow_agent_id,
     parent_instance_id: parent ? nativeInstanceIdV3(parent.instance_id) : undefined,

package/src/core/agents/state/live-coordination-writer.ts

@@ -112,6 +112,9 @@ function materializeLiveCoordinationHeartbeat(
                 session_name_display_requested_for: current.session_name_display_requested_for,
               }
             : {}),
+          ...(typeof current.session_name_display_reminders === "number"
+            ? { session_name_display_reminders: current.session_name_display_reminders }
+            : {}),
         }
       : {};
   const materialized: V3HeartbeatMaterialization = {

package/src/core/agents/state/stale-sweep.ts

@@ -13,18 +13,11 @@
 import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { coordFreshnessSeconds } from "../../config.ts";
-import type { EventAdapterIdV3 } from "../../events/v3/adapter-id.ts";
+import { type EventAdapterIdV3, eventAdapterIdV3FromPlatform } from "../../events/v3/adapter-id.ts";
 import { writeProducerDiagnosticV3 } from "../../events/v3/producers/intake.ts";
 import { recordLiveSweepObservationV3 } from "../live-lifecycle-v3.ts";
 
 /** platform → adapter, for the swept-event envelope (mirrors heartbeat-writer's adapterOf). */
-function adapterFromPlatform(platform: unknown): EventAdapterIdV3 {
-  if (platform === "cursor") return "cursor";
-  if (platform === "codex") return "codex";
-  if (platform === "openclaw") return "openclaw";
-  return "claude-code";
-}
-
 /**
  * Record the sweep before deleting disposable cache state.
  *
@@ -150,7 +143,7 @@ export function staleSweep(coordRoot: string): {
       }
 
       const instanceId = parsed.instance_id ?? idFromFile;
-      const adapter = adapterFromPlatform(parsed.platform);
+      const adapter = eventAdapterIdV3FromPlatform(parsed.platform, { context: "stale-sweep" });
       const sessionId = parsed.session_id ?? instanceId;
       const ts = parsed.last_heartbeat
         ? Math.floor(Date.parse(parsed.last_heartbeat) / 1000)

package/src/core/agents/turn-changes.ts

@@ -0,0 +1,97 @@
+import type { EventV3 } from "../events/v3/contract.ts";
+import { liveInstanceIdV3 } from "../events/v3/live-routing.ts";
+import { readLedgerV3 } from "../events/v3/reader.ts";
+import type { LineChanges } from "../events/v3/tool-line-changes.ts";
+
+export interface TurnChanges extends LineChanges {
+  measured_tools: number;
+  unmeasured_tools: number;
+}
+
+/** Sum edit activity, not a net workspace diff. Commits cannot erase it. */
+export function resolveTurnChanges(
+  events: readonly EventV3[],
+  instanceId: string,
+  now = Date.now(),
+): TurnChanges | null {
+  const owner = liveInstanceIdV3(instanceId);
+  const own = events.filter(
+    (event) => event.scope.instance_id === owner && Date.parse(event.time.observed_at) <= now,
+  );
+  const starts = own.filter((event) => event.event_type === "turn.started");
+  const newest = starts.at(-1);
+  if (!newest || !("generation_id" in newest.scope)) return null;
+  const generation = newest.scope.generation_id;
+  let index = starts.length - 1;
+  let restarts = 0;
+  while (
+    index > 0 &&
+    restarts < 8 &&
+    starts[index]?.event_type === "turn.started" &&
+    starts[index]?.payload.stop_remediation === true
+  ) {
+    const previous = starts[index - 1]!;
+    if (!("generation_id" in previous.scope) || previous.scope.generation_id !== generation) break;
+    index--;
+    restarts++;
+  }
+  const selected = starts.slice(index);
+  const ids = new Set(
+    selected.map((event) => ("turn_id" in event.scope ? event.scope.turn_id : undefined)),
+  );
+  const from = Date.parse(selected[0]!.time.observed_at);
+  const tools = own.filter(
+    (event) =>
+      "generation_id" in event.scope &&
+      event.scope.generation_id === generation &&
+      "turn_id" in event.scope &&
+      ids.has(event.scope.turn_id) &&
+      Date.parse(event.time.observed_at) >= from,
+  );
+  const result: TurnChanges = { added: 0, removed: 0, measured_tools: 0, unmeasured_tools: 0 };
+  const completed = new Set<string>();
+  for (const event of tools) {
+    if (event.event_type !== "tool.completed") continue;
+    const span = event.payload.span.span_id;
+    if (completed.has(span)) continue;
+    completed.add(span);
+    const changes = event.payload.line_changes;
+    if (event.payload.outcome === "succeeded" && changes?.state === "observed") {
+      result.added += changes.value.added;
+      result.removed += changes.value.removed;
+      result.measured_tools++;
+    } else result.unmeasured_tools++;
+  }
+  for (const event of tools) {
+    const span = (event.links as { span_id?: string }).span_id;
+    if (event.event_type === "tool.requested" && span && !completed.has(span)) {
+      completed.add(span);
+      result.unmeasured_tools++;
+    }
+  }
+  // No delivered tool evidence cannot prove no file changes occurred.
+  return result.measured_tools + result.unmeasured_tools > 0 ? result : null;
+}
+
+export function formatTurnChanges(changes: TurnChanges | null): string {
+  if (!changes || changes.measured_tools === 0) return "unavailable (no measured edits)";
+  return `+${changes.added} / -${changes.removed} lines${changes.unmeasured_tools > 0 ? " (partial; unmeasured tools)" : " (recorded edits)"}`;
+}
+
+export function turnChangesStatusRow(target: { coordRoot: string; instanceId: string }): {
+  value: string;
+  changes: TurnChanges | null;
+} {
+  let changes: TurnChanges | null = null;
+  try {
+    const ledger = readLedgerV3(target.coordRoot);
+    if (ledger.complete)
+      changes = resolveTurnChanges(
+        ledger.events.map((item) => item.event),
+        target.instanceId,
+      );
+  } catch {
+    /* Status remains available when evidence is missing. */
+  }
+  return { value: formatTurnChanges(changes), changes };
+}

package/src/core/artifacts/delivery-card.ts

@@ -14,6 +14,7 @@ import { isAbsolute, relative, resolve, sep } from "node:path";
 import { encodeLinkSafeComponent } from "../../lib/local-file-url.ts";
 import { findLiveTunnelForOrigin } from "../../lib/tunnel/state.ts";
 import { resolveWebPort } from "../config.ts";
+import { stateFileMode } from "../storage/modes.ts";
 import { ARTIFACT_MANIFEST } from "./constants.ts";
 import { resolveArtifactRef, showArtifact } from "./index.ts";
 
@@ -71,7 +72,7 @@ export function writeArtifactDeliveryManifest(
   try {
     writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`, {
       encoding: "utf8",
-      mode: 0o600,
+      mode: stateFileMode(),
       flag: "wx",
     });
     renameSync(tmp, target);

package/src/core/artifacts/index.ts

@@ -33,6 +33,7 @@ import {
   coordFreshnessSeconds,
   resolveBinName,
 } from "../config.ts";
+import { stateFileMode } from "../storage/modes.ts";
 import {
   type ArtifactActivity,
   artifactRootEntries,
@@ -1068,7 +1069,7 @@ function atomicWriteManifest(path: string, manifest: ArtifactManifestV2, now = n
   try {
     writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`, {
       encoding: "utf8",
-      mode: 0o600,
+      mode: stateFileMode(),
       flag: "wx",
     });
     renameSync(tmp, target);
@@ -1143,7 +1144,7 @@ export function migrateArtifacts(
             };
           mkdirSync(dirname(preimagePath), { recursive: true });
           try {
-            writeFileSync(preimagePath, preimage, { flag: "wx", mode: 0o600 });
+            writeFileSync(preimagePath, preimage, { flag: "wx", mode: stateFileMode() });
           } catch (error) {
             if (
               (error as NodeJS.ErrnoException).code !== "EEXIST" ||
@@ -1287,7 +1288,7 @@ export function repairArtifactActivity(
               null,
               2,
             )}\n`,
-            { flag: "wx", mode: 0o600 },
+            { flag: "wx", mode: stateFileMode() },
           );
           const current = lstatSync(path);
           if (

package/src/core/config.ts

@@ -152,6 +152,16 @@ interface HarneryConfig {
     archive_keep_min?: number;
     archive_auto_clean?: boolean;
   };
+  /**
+   * Who can use this project's `.harnery/` state. `private` (the default) keeps every state
+   * directory 0700 and every state file 0600, owned by whoever wrote it. `group` makes them 0770 and
+   * 0660 so several Unix users who share the project directory's group can coordinate in one
+   * project. It never grants access to other users. The project directory must be setgid to that
+   * group so new state inherits it. Read via `storageSharing()`.
+   */
+  storage?: {
+    sharing?: "private" | "group";
+  };
   /**
    * Managed working-artifact defaults. `default_retention_days` is the
    * create-time TTL when the caller does not pass `artifacts create --days`.
@@ -591,6 +601,19 @@ export function workflowSubscriptionOnly(coordRoot?: string | null): boolean {
   return readConfig(root).workflow?.subscriptionOnly === true;
 }
 
+/**
+ * How this project's `.harnery/` state is shared: `private` or `group`. `HARNERY_STORAGE_SHARING`
+ * overrides per process; an unrecognized value falls back to `private`, the safer reading.
+ */
+export function storageSharing(coordRoot?: string | null): "private" | "group" {
+  const env = coordEnv("STORAGE_SHARING");
+  if (env === "group" || env === "private") return env;
+  const root = coordRoot ?? findCoordRoot();
+  if (!root) return "private";
+  // Project file only: a user-global "group" would loosen every project that user touches.
+  return readProjectConfig(root).storage?.sharing === "group" ? "group" : "private";
+}
+
 /**
  * Whether cross-machine presence (ADR 0016) is enabled for this repo.
  * Default ON — the transport itself additionally gates on an origin remote

package/src/core/context/index.ts

@@ -11,6 +11,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "
 import { dirname, join } from "node:path";
 import type { Adapter } from "../adapter.ts";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
+import { stateFileMode } from "../storage/modes.ts";
 
 export const CONTEXT_SCHEMA_VERSION = 1 as const;
 export const MAX_CAPSULE_BYTES = 32 * 1024;
@@ -499,7 +500,7 @@ function writeBoundedJson(path: string, value: unknown, maxBytes: number): void
   }
   mkdirSync(dirname(path), { recursive: true });
   const temp = `${path}.tmp.${process.pid}.${randomUUID()}`;
-  writeFileSync(temp, text, { encoding: "utf8", mode: 0o600 });
+  writeFileSync(temp, text, { encoding: "utf8", mode: stateFileMode() });
   renameSync(temp, path);
 }