@dna113p/machines 0.3.1 → 0.3.3

package/README.md

@@ -176,10 +176,10 @@ npm ci
 npm pack
 ```
 
-Then install the generated `dna113p-machines-0.3.1.tgz` into a project:
+Then install the generated `dna113p-machines-0.3.3.tgz` into a project:
 
 ```bash
-npm install /absolute/path/to/machines/dna113p-machines-0.3.1.tgz
+npm install /absolute/path/to/machines/dna113p-machines-0.3.3.tgz
 npx machine list
 ```
 
@@ -193,9 +193,11 @@ installation script is required for the direct MCP setup.
 Hosts that only run a status-line command, such as Claude Code, can show running
 Machines through [run status publication](docs/integrations.md#run-status-for-host-status-lines).
 
-Publication is opt-in: set `MACHINES_RUN_STATUS_DIR` to a directory only you can
-read. A published run that is waiting for a Human can then be answered from
-outside its own terminal:
+Publication is on by default, in a private per-user directory
+(`~/.local/state/machines/runs`, or under `XDG_STATE_HOME`), so nothing has to be
+configured. Set `MACHINES_RUN_STATUS_DIR` to `off` to turn it off, or to a
+directory to move it. A published run that is waiting for a Human can be
+answered from outside its own terminal:
 
 ```bash
 machine runs [--json] [--all]                      # running and waiting runs; --all adds finished and lost ones

package/claude/statusline.mjs

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 
-// Claude Code status line for Machine runs published through
-// MACHINES_RUN_STATUS_DIR (see docs/integrations.md). It runs on every status
-// refresh, so it imports only node: modules and never loads the runtime; the
-// record shape below mirrors RunStatusRecord in src/run-status.ts, and the
-// watch list and its matching mirror src/run-watch.ts.
+// Claude Code status line for published Machine runs (see
+// docs/integrations.md). It runs on every status refresh, so it imports only
+// node: modules and never loads the runtime; the directory rule and the record
+// shape below mirror runStatusDirectory and RunStatusRecord in
+// src/run-status.ts, and the watch list and its matching mirror
+// src/run-watch.ts.
 
 import { readdirSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
 import { isAbsolute, join, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 
@@ -20,6 +22,29 @@ const zeroWidth = /[\p{Mn}\p{Me}\p{Cf}\u1160-\u11ff]/u;
 // East Asian Wide and Fullwidth characters, and emoji drawn as pictures, take two columns.
 const wide = /[\u1100-\u115f\u2e80-\u303e\u3041-\ua4cf\ua960-\ua97f\uac00-\ud7a3\uf900-\ufaff\ufe10-\ufe19\ufe30-\ufe6f\uff00-\uff60\uffe0-\uffe6\u{20000}-\u{3fffd}\p{Emoji_Presentation}]/u;
 
+/**
+ * The directory runs publish to, or undefined while publication is off: the
+ * same answer as runStatusDirectory in src/run-status.ts for the same
+ * environment, which tests/run-status.test.ts checks.
+ */
+export function runStatusDirectory(environment = process.env) {
+  const configured = environment.MACHINES_RUN_STATUS_DIR;
+  if (configured === "" || configured === "off") return undefined;
+  if (configured !== undefined) return resolve(configured);
+  // XDG_STATE_HOME describes the real home. A process given another Machines
+  // home keeps its runs under that one, and out of the real one.
+  const state = environment.XDG_STATE_HOME;
+  const machinesHome = environment.MACHINES_USER_HOME;
+  if (machinesHome === undefined && state !== undefined && isAbsolute(state)) return join(state, "machines", "runs");
+  try {
+    const home = machinesHome ?? homedir();
+    return isAbsolute(home) ? join(home, ".local", "state", "machines", "runs") : undefined;
+  } catch {
+    // Without a usable home there is nowhere standard to publish.
+    return undefined;
+  }
+}
+
 /**
  * Builds the status lines for the runs one Claude Code session should see.
  * Pure apart from the default process-liveness probe, which callers may replace.
@@ -237,8 +262,8 @@ function readWatches(directory, sessionId) {
 }
 
 async function main() {
-  const directory = process.env.MACHINES_RUN_STATUS_DIR;
-  if (directory === undefined || directory === "" || process.stdin.isTTY) return;
+  const directory = runStatusDirectory();
+  if (directory === undefined || process.stdin.isTTY) return;
 
   let text = "";
   process.stdin.setEncoding("utf8");

package/dist/mcp/server.js

@@ -10,7 +10,7 @@ import { isJsonValue } from "../src/json.js";
 import { MachineSession as RunSession } from "../src/session.js";
 import { listAgentPresets, listMachines } from "../src/launcher.js";
 import { watchRunInbox } from "../src/run-inbox.js";
-import { createRunStatusPublisher, runStatusDirectory } from "../src/run-status.js";
+import { createRunStatusPublisher } from "../src/run-status.js";
 import { machineCoordinatorGuidelines, machineDiscoveryDescription, machineSupervisionGuidelines } from "../src/coordinator-guidance.js";
 const widgetUri = "ui://machines/run-v1.html";
 const cwd = v.pipe(v.string(), v.nonEmpty("cwd must be a non-empty absolute path"), v.check(isAbsolute, "cwd must be an absolute path"));
@@ -177,7 +177,7 @@ export class MachineSession {
     }
     async start(input) {
         // This server publishes its runs itself, so that they also take responses through their inbox.
-        const run = await this.#session.start({ ...parse(startInput, input), publishRunStatus: false });
+        const run = await this.#session.start({ ...parse(startInput, input), publishRunStatus: "caller" });
         return result(`Started ${run.machine}.\nRun id: ${run.id}\nStatus: ${run.status}`, { run });
     }
     status(input) {
@@ -212,7 +212,7 @@ export class MachineSession {
             this.#published.set(run.id, publisher);
         }
         const human = run.status === "waiting" ? run.human : undefined;
-        this.#watchInbox(run.id, human);
+        this.#watchInbox(run.id, human, publisher.directory);
         if (run.status === "running" || run.status === "waiting") {
             publisher.update({
                 status: run.status, state: run.state, agent: run.agent, limit: run.limit, human, delivery: this.#taking,
@@ -223,13 +223,12 @@ export class MachineSession {
         this.#published.delete(run.id);
     }
     /** A published request can also be answered, or asked about, through the run's inbox by `machine respond`. */
-    #watchInbox(runId, request) {
+    #watchInbox(runId, request, directory) {
         const watched = this.#inboxes.get(runId);
         if (watched?.requestId === request?.requestId)
             return;
         watched?.stop();
         this.#inboxes.delete(runId);
-        const directory = runStatusDirectory();
         if (request === undefined || directory === undefined)
             return;
         const stop = watchRunInbox(directory, runId, request, (response, delivery) => {

package/dist/src/cli.js

@@ -97,7 +97,7 @@ async function runMachine(machinePath, args) {
     const status = createRunStatus(machinePath);
     const runId = randomUUID();
     const published = createRunStatusPublisher({ id: runId, machine: prepared.name, path: prepared.path, cwd: process.cwd() });
-    const statusDirectory = runStatusDirectory();
+    const statusDirectory = published.directory;
     // Machines started by this run's Operations and Agents are its sub-runs.
     process.env.MACHINES_RUN_PARENT = runId;
     const observed = runStatusObserver((change) => published.update(change));
@@ -265,7 +265,10 @@ async function respond(args) {
 function requireStatusDirectory() {
     const directory = runStatusDirectory();
     if (directory === undefined) {
-        throw new Error("Run status publication is off: set MACHINES_RUN_STATUS_DIR to the directory the runs publish to.");
+        // Unset, the variable leaves publication on, so only a home that cannot hold the standard directory turns it off.
+        throw new Error(process.env.MACHINES_RUN_STATUS_DIR === undefined
+            ? "Run status publication is off: there is no absolute home directory to keep the standard directory in. Set MACHINES_RUN_STATUS_DIR to the directory the runs publish to."
+            : "Run status publication is off: unset MACHINES_RUN_STATUS_DIR to use the standard directory, or set it to the directory the runs publish to.");
     }
     return directory;
 }

package/dist/src/discovery.d.ts

@@ -1,5 +1,5 @@
 /** Select a separate global catalog without changing the process's real home. */
-export declare function machinesUserHome(): string;
+export declare function machinesUserHome(environment?: NodeJS.ProcessEnv): string;
 export interface DiscoveredMachine {
     readonly name: string;
     readonly path: string;

package/dist/src/discovery.js

@@ -2,8 +2,8 @@ import { readdir, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join } from "node:path";
 /** Select a separate global catalog without changing the process's real home. */
-export function machinesUserHome() {
-    const override = process.env.MACHINES_USER_HOME;
+export function machinesUserHome(environment = process.env) {
+    const override = environment.MACHINES_USER_HOME;
     if (override === undefined)
         return homedir();
     if (!isAbsolute(override))

package/dist/src/host.d.ts

@@ -11,8 +11,13 @@ export interface MachineHostOptions extends PrepareMachineRunOptions {
     readonly label?: string;
     /** The session that owns the run in its published run status. The environment's owner applies when absent. */
     readonly owner?: string;
-    /** Set to false by a caller that publishes the run's status itself, as the MCP server does. */
-    readonly publishRunStatus?: boolean;
+    /**
+     * Asks for the run's status to be published where run-status publication is on.
+     * `true`: this host publishes it. `"caller"`: the caller publishes it itself,
+     * under the run's id, as the MCP server does. Absent: nothing about the run is
+     * published or handed down, and the caller presents the run in its own way.
+     */
+    readonly publishRunStatus?: boolean | "caller";
     readonly onAgentUpdate?: (update: AgentUpdate) => void;
     readonly onHumanRequest?: (request: HostedHumanRequest) => void;
     readonly onState?: (state: StateValue) => void;

package/dist/src/host.js

@@ -118,7 +118,9 @@ export function startMachineHost(options) {
     // below), so a reader that finds the pid gone rightly shows the run as lost.
     const id = randomUUID();
     const publication = runStatusDirectory() !== undefined;
-    const publishes = publication && options.publishRunStatus !== false;
+    // An embedding program has to ask: its environment alone must not make its runs appear elsewhere.
+    const publishes = publication && options.publishRunStatus === true;
+    const recorded = publishes || (publication && options.publishRunStatus === "caller");
     let published;
     const child = fork(fileURLToPath(import.meta.url), [childArgument], {
         cwd,
@@ -322,7 +324,7 @@ export function startMachineHost(options) {
                 ...(options.agents === undefined ? {} : { agents: options.agents }),
                 ...(options.home === undefined ? {} : { home: options.home }),
                 // A caller that publishes the record itself still publishes it under this id.
-                ...(publication ? { runId: id } : {}),
+                ...(recorded ? { runId: id } : {}),
                 ...(publishes ? { reportStatus: true } : {}),
             };
             void sendChild(child, launch).catch((cause) => fail(asError(cause)));

package/dist/src/run-status.d.ts

@@ -1,6 +1,6 @@
 import type { StateValue } from "xstate";
 import type { AgentUpdate } from "./index.ts";
-/** One published run, stored as `<MACHINES_RUN_STATUS_DIR>/<id>.json`. */
+/** One published run, stored as `<id>.json` in the run-status directory. */
 export interface RunStatusRecord {
     /** Version 1 records carry only `human.prompt`. */
     readonly schemaVersion: 1 | 2;
@@ -81,12 +81,29 @@ export type RunStatusOutcome = {
     readonly error: string;
 };
 export interface RunStatusPublisher {
+    /**
+     * Where the run is published. Undefined when it is not: publication is off,
+     * or the directory could not take the run's first record.
+     */
+    readonly directory: string | undefined;
     update(change: RunStatusChange): void;
     finish(outcome: RunStatusOutcome): void;
 }
 /** How long a record goes on naming a response its run took: longer than a sender waits to hear of it. */
 export declare const deliveryRetentionMilliseconds = 60000;
-/** The directory runs publish to, or undefined while publication is off. */
+/** How long a session's watch list is kept after its last change: sessions end without saying so. */
+export declare const watchRetentionMilliseconds: number;
+/** The name of a session's watch list, which `src/run-watch.ts` keeps beside the records. */
+export declare const watchListName: RegExp;
+/**
+ * The directory runs publish to, or undefined while publication is off.
+ * `MACHINES_RUN_STATUS_DIR` moves it, and turns publication off when it is
+ * `off` or empty. Unset, it is the user's own state directory, so every
+ * process of one user agrees on it without being told.
+ *
+ * `claude/statusline.mjs` cannot load this module and carries a copy of the
+ * rule; tests/run-status.test.ts keeps the two in step.
+ */
 export declare function runStatusDirectory(environment?: NodeJS.ProcessEnv): string | undefined;
 /** The one pending outside response for a run, kept beside its record. */
 export declare function runInboxPath(directory: string, id: string): string;
@@ -96,9 +113,10 @@ export declare function runInboxPath(directory: string, id: string): string;
  */
 export declare function runDeliveryPath(directory: string, id: string, delivery: string): string;
 /**
- * Publishes one run for hosts that can only read files, such as a status line.
- * Opt-in through MACHINES_RUN_STATUS_DIR. Publication is presentation: it never
- * throws, and it records neither Machine input nor output.
+ * Publishes one run for hosts that can only read files, such as a status line,
+ * in `runStatusDirectory`. Publication is presentation: it never throws, and it
+ * records neither Machine input nor output. A run whose first record cannot be
+ * written, as in a read-only home, is not published at all.
  */
 export declare function createRunStatusPublisher(run: RunStatusRun, environment?: NodeJS.ProcessEnv): RunStatusPublisher;
 /**

package/dist/src/run-status.js

@@ -1,15 +1,49 @@
 import { randomUUID } from "node:crypto";
-import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, isAbsolute, join, resolve } from "node:path";
+import { machinesUserHome } from "./discovery.js";
 const staleAfterMilliseconds = 60 * 60 * 1_000;
 /** How long a record goes on naming a response its run took: longer than a sender waits to hear of it. */
 export const deliveryRetentionMilliseconds = 60_000;
-const disabled = { update() { }, finish() { } };
+/** How long a session's watch list is kept after its last change: sessions end without saying so. */
+export const watchRetentionMilliseconds = 30 * 24 * 60 * 60 * 1_000;
+/** The name of a session's watch list, which `src/run-watch.ts` keeps beside the records. */
+export const watchListName = /^\.watch\..+\.json$/u;
+// A record being written, and the second names of a response: each lasts moments unless its process was stopped.
+const leftoverName = /^\.[A-Za-z0-9._-]+\.(?:\d+\.\d+\.tmp|[A-Za-z0-9_-]+\.inbox\.(?:sent|taken))$/u;
+// A run's inbox, which goes with its record: one without a record belongs to a run that was pruned.
+const inboxName = /^[A-Za-z0-9_-][A-Za-z0-9._-]*\.inbox$/u;
+const disabled = { directory: undefined, update() { }, finish() { } };
 let temporaryFiles = 0;
-/** The directory runs publish to, or undefined while publication is off. */
+/**
+ * The directory runs publish to, or undefined while publication is off.
+ * `MACHINES_RUN_STATUS_DIR` moves it, and turns publication off when it is
+ * `off` or empty. Unset, it is the user's own state directory, so every
+ * process of one user agrees on it without being told.
+ *
+ * `claude/statusline.mjs` cannot load this module and carries a copy of the
+ * rule; tests/run-status.test.ts keeps the two in step.
+ */
 export function runStatusDirectory(environment = process.env) {
     const configured = environment.MACHINES_RUN_STATUS_DIR;
-    return configured === undefined || configured === "" ? undefined : resolve(configured);
+    if (configured === "" || configured === "off")
+        return undefined;
+    if (configured !== undefined)
+        return resolve(configured);
+    // XDG_STATE_HOME describes the real home. A process given another Machines
+    // home keeps its runs under that one, and out of the real one.
+    const state = environment.XDG_STATE_HOME;
+    if (environment.MACHINES_USER_HOME === undefined && state !== undefined && isAbsolute(state)) {
+        return join(state, "machines", "runs");
+    }
+    try {
+        const home = machinesUserHome(environment);
+        return isAbsolute(home) ? join(home, ".local", "state", "machines", "runs") : undefined;
+    }
+    catch {
+        // Without a usable home there is nowhere standard to publish.
+        return undefined;
+    }
 }
 /** The one pending outside response for a run, kept beside its record. */
 export function runInboxPath(directory, id) {
@@ -23,9 +57,10 @@ export function runDeliveryPath(directory, id, delivery) {
     return join(directory, `.${id}.${delivery}.inbox.sent`);
 }
 /**
- * Publishes one run for hosts that can only read files, such as a status line.
- * Opt-in through MACHINES_RUN_STATUS_DIR. Publication is presentation: it never
- * throws, and it records neither Machine input nor output.
+ * Publishes one run for hosts that can only read files, such as a status line,
+ * in `runStatusDirectory`. Publication is presentation: it never throws, and it
+ * records neither Machine input nor output. A run whose first record cannot be
+ * written, as in a read-only home, is not published at all.
  */
 export function createRunStatusPublisher(run, environment = process.env) {
     const directory = runStatusDirectory(environment);
@@ -79,9 +114,11 @@ export function createRunStatusPublisher(run, environment = process.env) {
                 rmSync(temporary, { force: true });
                 throw cause;
             }
+            return true;
         }
         catch {
             // A status line is never worth a run: an unwritable directory is ignored.
+            return false;
         }
     };
     try {
@@ -90,8 +127,12 @@ export function createRunStatusPublisher(run, environment = process.env) {
     catch {
         // Pruning is best effort for the same reason.
     }
-    publish();
+    // A directory that cannot take the first record is not tried again at every
+    // change, and the run goes on exactly as one that publication is off for.
+    if (!publish())
+        return disabled;
     return {
+        directory,
         update(change) {
             if (status === "completed" || status === "failed")
                 return;
@@ -198,27 +239,60 @@ export function readRunStatuses(directory) {
 }
 function pruneRunStatuses(directory) {
     const now = Date.now();
+    const remove = (file) => {
+        try {
+            rmSync(file, { force: true });
+        }
+        catch {
+            // Not a file, or not ours to remove: nothing else waits on it.
+        }
+    };
     for (const { file, record } of readRecordFiles(directory)) {
         const settled = record.status === "completed" || record.status === "failed" || !isProcessAlive(record.pid);
         if (!settled || now - Date.parse(record.updatedAt) <= staleAfterMilliseconds)
             continue;
+        // A response nobody collected goes with the run it was meant for, under each
+        // of its names. The record goes last: a publisher stopped part way leaves it
+        // for the next one to prune whole.
+        const id = basename(file, ".json");
+        remove(runInboxPath(directory, id));
+        for (const name of listNames(directory)) {
+            if (!name.startsWith(`.${id}.`))
+                continue;
+            if (/^[^.]+\.inbox\.(?:sent|taken)$/u.test(name.slice(id.length + 2)))
+                remove(join(directory, name));
+        }
+        remove(file);
+    }
+    // What a stopped process left half done has no record to go with, nor has an
+    // inbox whose run was pruned without it, and a session that ended never
+    // removes its watch list. Other files are not ours.
+    const names = new Set(listNames(directory));
+    for (const name of names) {
+        const orphaned = inboxName.test(name) && !names.has(`${basename(name, ".inbox")}.json`);
+        const kept = leftoverName.test(name) || orphaned
+            ? staleAfterMilliseconds
+            : watchListName.test(name) ? watchRetentionMilliseconds : undefined;
+        if (kept === undefined)
+            continue;
+        const file = join(directory, name);
         try {
-            rmSync(file, { force: true });
-            // A response nobody collected goes with the run it was meant for, under each of its names.
-            const id = basename(file, ".json");
-            rmSync(runInboxPath(directory, id), { force: true });
-            for (const name of readdirSync(directory)) {
-                if (!name.startsWith(`.${id}.`))
-                    continue;
-                if (/^[^.]+\.inbox\.(?:sent|taken)$/u.test(name.slice(id.length + 2)))
-                    rmSync(join(directory, name), { force: true });
-            }
+            if (now - statSync(file).mtimeMs > kept)
+                rmSync(file, { force: true });
         }
         catch {
             // Another publisher may have pruned it first.
         }
     }
 }
+function listNames(directory) {
+    try {
+        return readdirSync(directory);
+    }
+    catch {
+        return [];
+    }
+}
 function readRecordFiles(directory) {
     let names;
     try {

package/dist/src/run-watch.js

@@ -1,8 +1,6 @@
 import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, resolve, sep } from "node:path";
-import { isFileSafeId } from "./run-status.js";
-const forgottenAfterMilliseconds = 30 * 24 * 60 * 60 * 1_000;
-const watchFile = /^\.watch\..+\.json$/u;
+import { isFileSafeId, watchListName, watchRetentionMilliseconds } from "./run-status.js";
 let temporaryFiles = 0;
 /**
  * A session's watch list, kept beside the records under a name their readers
@@ -94,15 +92,18 @@ function pickWatch(value) {
         return { dir: resolve(dir) };
     return undefined;
 }
-/** Sessions end without saying so; a list nobody has changed for a month belongs to one that did. */
+/**
+ * Sessions end without saying so; a list nobody has changed for a month belongs
+ * to one that did. A run that starts prunes them by the same rule.
+ */
 function pruneRunWatches(directory, kept) {
     const now = Date.now();
     for (const name of readdirSync(directory)) {
         const file = join(directory, name);
-        if (!watchFile.test(name) || file === kept)
+        if (!watchListName.test(name) || file === kept)
             continue;
         try {
-            if (now - statSync(file).mtimeMs > forgottenAfterMilliseconds)
+            if (now - statSync(file).mtimeMs > watchRetentionMilliseconds)
                 rmSync(file, { force: true });
         }
         catch {

package/docs/architecture.md

@@ -100,7 +100,12 @@ and that request. Claiming a request before asynchronous delivery prevents two
 answers from being accepted, and the identity prevents a stale card or dialog from
 answering a later prompt. Restricted choices are validated for every interface.
 
-`machine run` asks on its own terminal. With run-status publication on it also
+`machine run` asks on its own terminal. Run-status publication is on unless
+`MACHINES_RUN_STATUS_DIR` turns it off, in a private per-user directory that
+every reader and writer finds by one rule (`runStatusDirectory`; the standalone
+status line carries a tested copy). It is presentation and never changes a run:
+a run that cannot write its first record is simply not published. With
+publication on, `machine run` also
 publishes the pending request and its request ID, and takes the first valid
 response from either the terminal or a private per-run inbox file written by
 `machine respond`; the MCP session takes inbox responses through the same
@@ -108,7 +113,7 @@ session `respond` path as its tool, and inbox questions through the session's
 `ask`. The inbox is a second way to deliver a response to the owning run, not a
 second owner: the run still validates the request ID and choices, and a response
 to any other request is discarded. A run hosted directly through
-`startMachineHost` publishes its status without an inbox: its host remains the
+`startMachineHost` publishes its status only when its host asks, and without an inbox: its host remains the
 only way to answer it, its record says so, and `machine respond` refuses it. See
 [Integrations](integrations.md#answering-a-waiting-run-from-outside).
 

package/docs/integrations.md

@@ -170,12 +170,31 @@ Pi exit, session replacement, and reload terminate its session-owned runs.
 
 Pi and MCP Apps clients render run snapshots in-process. A host that can only run
 a command, such as Claude Code's status line, reads published run status instead.
-Publication is opt-in: set `MACHINES_RUN_STATUS_DIR` to an absolute directory.
-When it is unset nothing is written.
+Publication is on by default and needs no setup: every process of one user
+publishes to and reads from the same private directory, so a run started
+anywhere, by a coding agent, a terminal, or a daemon, is on the status line, in
+`machine runs`, and within reach of `machine respond`.
 
-`machine run`, the MCP server, and every run hosted through `startMachineHost`
-then keep one file per run, `<dir>/<runId>.json`, replaced atomically on each
-change (directory `0700`, file `0600`):
+One variable refines it:
+
+| `MACHINES_RUN_STATUS_DIR` | Run status |
+| --- | --- |
+| unset | Published in `$XDG_STATE_HOME/machines/runs` when `XDG_STATE_HOME` is an absolute path, otherwise in `~/.local/state/machines/runs` |
+| `off`, or empty | Off: nothing is written, and the commands that read run status say so |
+| a directory | Published there instead; a relative path is resolved against the working directory |
+
+To move the directory, give the same absolute path to every process that starts
+runs or reads them: the coding agent, a daemon that hosts runs, and the status
+line. The same holds for `XDG_STATE_HOME`: a service that does not inherit the
+one your shell sets uses `~/.local/state`. A process given its own Machines home
+through `MACHINES_USER_HOME` publishes under that home, in
+`<home>/.local/state/machines/runs`, whatever `XDG_STATE_HOME` says, so an
+isolated catalog also keeps its runs out of your own directory. Where no
+absolute home can be found, publication is off.
+
+`machine run`, the MCP server, and a host that asks for it (below) keep one file
+per run, `<dir>/<runId>.json`, replaced atomically on each change. The
+directory is created by the first write, as `0700`, and each file is `0600`:
 
 ```json
 {
@@ -199,8 +218,11 @@ choice to publish that text. `machine run` exports its run id as
 records that id as `parent`; the status line shows only top-level runs.
 
 A run hosted through `startMachineHost` from `@dna113p/machines/host` publishes
-the same record when the variable is set in the hosting process, for example a
-daemon that runs tickets, or Pi with the extension loaded. Two options replace the environment for that one run:
+the same record when its host asks with `publishRunStatus: true` and
+publication is on in the hosting process, as a daemon that runs tickets does. A
+host that does not ask publishes nothing, whatever its environment says: a
+program that presents its runs itself, such as Pi with the extension loaded, is
+not changed by publication being on. Two options replace the environment for that one run:
 `label`, shortened as `MACHINES_RUN_LABEL` is, and `owner`. When an option is
 absent the environment rule above applies; an empty one publishes the run
 without that field. The run exports its id as `MACHINES_RUN_PARENT` to its
@@ -216,7 +238,8 @@ only through the host's own `respond` and `ask`: the run reads no inbox, its
 `human` has no `requestId`, and `machine respond` refuses it. The field is absent
 from every other record and did not exist in earlier version 2 records. A caller
 that publishes its own record for the run, as the MCP server does so that its
-runs keep their inbox, passes `publishRunStatus: false`.
+runs keep their inbox, passes `publishRunStatus: "caller"`: the host then writes
+nothing, and the run still hands its id down to the runs it starts.
 
 While an Agent state waits for a [usage limit](authoring.md#usage-limits) to
 reset, the record stays `running` and carries the wait in `limit`:
@@ -258,17 +281,37 @@ after it, and never contains the response.
 
 Machine input, Machine output, and Human responses are never recorded. A Human
 prompt and its choices are written to the `0600` file while the request is
-waiting, so choose a directory only you can read. Publication cannot change a
-run: a missing or unwritable directory is ignored. Starting a run prunes records
-that finished, or whose process is gone, more than an hour ago.
+waiting. The standard directory is private to you; one you name instead should
+be a directory only you can read and write.
+
+Publication cannot change a run. Where the directory cannot be created or
+written, as in a read-only home, a sandbox, or a container, a run goes on
+exactly as one with publication off: it is not published, nothing is reported,
+and the directory is not tried again at each state. Reading a directory that
+does not exist yet finds no runs; it is not an error.
+
+The directory does not grow without bound. Each run that starts removes:
+
+- the record of a run that finished, or whose process is gone, more than an hour
+  ago, with its inbox and any response left for it;
+- what an interrupted write or delivery left behind more than an hour ago;
+- an inbox with no record beside it, left when a run was pruned without it,
+  more than an hour after it was last written;
+- a [watch list](#watching-other-runs) that has not changed for 30 days.
+
+A running or waiting run keeps its record for as long as its process lives.
+Files Machines did not name are never removed, and nothing is removed while no
+run starts. A record whose process id now belongs to another process counts as
+running until that process ends.
 
 ### Answering a waiting run from outside
 
 With publication on, a waiting run can be seen and answered by any process
 running as the same user: a terminal, a coordinating agent, a script, or a
 presentation surface. They all read the same request, and the first valid
-response wins. Set the same `MACHINES_RUN_STATUS_DIR` for the run and for
-whatever answers it.
+response wins. With the standard directory there is nothing to set; if you move
+it, set the same `MACHINES_RUN_STATUS_DIR` for the run and for whatever answers
+it. With publication off these commands fail and say how to turn it on.
 
 ```bash
 machine runs                 # running and waiting runs
@@ -326,17 +369,25 @@ waits, it holds the same file under a second name of its own,
 response and the sender removes it to take the response back, so exactly one of
 them succeeds and neither can act on a response that arrived later. A response
 that was taken back stays in the inbox, emptied, until the run next reads its
-inbox or finishes, and a new response is refused until then. **Anything that can write to the directory as you can answer a waiting
-run**, including approvals, so do not point `MACHINES_RUN_STATUS_DIR` at a
-shared directory.
+inbox or finishes, and a new response is refused until then.
+
+**Anything that can write to the directory as you can answer a waiting run**,
+including approvals. That is why the standard directory is a private per-user
+one, created `0700`: no other user can read a request or leave a response. It
+is also all that protects a waiting run, so do not loosen its permissions and do
+not point `MACHINES_RUN_STATUS_DIR` at a shared directory. Set it to `off`
+where no process of yours should be able to answer a run from outside it.
 
 `machine run` still asks on its own terminal, and whichever of the terminal and
 the inbox gives the first valid response is used. Terminal input outside a
 request's `choices` is reported and asked for again instead of failing the run.
 A published run started without terminal input, for example by a coordinating
 agent or a script, waits for `machine respond` instead of failing, and prints
-the exact command to its standard error. With publication off it fails at its
-first Human state with "Terminal input closed before a response", as before.
+the exact command to its standard error. With publication on by default this is
+what a script or a CI job gets as well. With publication off, or where the run
+could not be published, it fails at its first Human state with "Terminal input
+closed before a response": set `MACHINES_RUN_STATUS_DIR=off` for a run that
+should fail there instead of waiting.
 Runs hosted in any other program through `startMachineHost` are answered only
 through that program.
 Runs hosted by the MCP server take a response from their own `machine_respond`
@@ -344,12 +395,13 @@ tool or from the inbox. That tool is answer-only, so a question to a hosted
 request that allows discussion goes through the inbox with
 `machine respond --question`.
 
-For Claude Code, set the variable in the `env` of its settings so the runs it
-launches publish there, and call the dependency-free renderer from `statusLine`:
+For Claude Code, call the dependency-free renderer from `statusLine`. That is
+the whole setup: the runs Claude Code launches, a daemon that hosts runs as the
+same user, and the status line all use the standard directory, so there is no
+`env` block to add and no path to repeat anywhere.
 
 ```json
 {
-  "env": { "MACHINES_RUN_STATUS_DIR": "/home/you/.cache/machines/run-status" },
   "statusLine": {
     "type": "command",
     "command": "node /path/to/machines/claude/statusline.mjs",
@@ -431,8 +483,8 @@ status line reads itself with the `session_id` Claude Code gives it:
 
 Record readers skip it, as they skip every name that starts with a dot. A
 session id that is not safe as a file name is refused. Removing the last entry
-removes the file, and writing a list removes other sessions' lists that have
-not changed for 30 days. A missing, unreadable, or malformed list watches
+removes the file, and writing a list or starting a run removes other sessions'
+lists that have not changed for 30 days. A missing, unreadable, or malformed list watches
 nothing; it is never an error on the status line. The commands fail with a
 message when publication is off or when no variable names the session.
 
@@ -442,6 +494,8 @@ For an isolated global catalog, set `MACHINES_USER_HOME` to an absolute director
 Machines reads global definitions and presets from that directory's `.machines/`.
 Explicit programmatic `home` options take precedence. This is useful for tests or
 separate workflow collections without changing the operating-system home directory.
+A process with that variable also publishes its
+[run status](#run-status-for-host-status-lines) under that directory.
 
 - **Node cannot load TypeScript from a dependency:** install the built tarball;
   source exports are for checkout development. Keep workflow definitions outside

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dna113p/machines",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Reusable workflows coordinating agents, local operations, and human decisions.",
   "license": "MIT",
   "repository": {