@dna113p/machines 0.3.2 → 0.3.4

package/README.md

@@ -176,10 +176,10 @@ npm ci
 npm pack
 ```
 
-Then install the generated `dna113p-machines-0.3.2.tgz` into a project:
+Then install the generated `dna113p-machines-0.3.4.tgz` into a project:
 
 ```bash
-npm install /absolute/path/to/machines/dna113p-machines-0.3.2.tgz
+npm install /absolute/path/to/machines/dna113p-machines-0.3.4.tgz
 npx machine list
 ```
 
@@ -193,12 +193,15 @@ 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
+machine runs --for [<session>] [--project <dir>] [--json] [--all]   # the runs one viewer shows
 machine respond <run-id> <request-id> <response>   # answer a waiting run
 machine watch [<run-id-or-label-start> | --dir <path>]     # show other runs on this session's status line
 machine unwatch <run-id-or-label-start> | --dir <path> | --all
@@ -213,6 +216,10 @@ Runs hosted through `startMachineHost` publish too and are answered through thei
 host. A session shows the runs it started; `machine watch` adds runs it did not,
 such as a ticket a daemon runs. See
 [watching other runs](docs/integrations.md#watching-other-runs).
+`machine runs --for` and the `@dna113p/machines/run-status` export answer which
+runs one session shows, so any application can
+[draw its own widgets](docs/integrations.md#drawing-your-own-widgets); `watch`
+and `unwatch` take `--for <session>` first to manage that session's list.
 
 ## Execution model and limitations
 

package/claude/statusline.mjs

@@ -1,12 +1,15 @@
 #!/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, the watch list and its matching mirror src/run-watch.ts,
+// and which runs a session sees, and in what order, mirrors runsForViewer in
+// src/run-viewer.ts, which tests/run-viewer.test.ts checks.
 
 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 +23,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 +263,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"));
@@ -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

@@ -12,11 +12,15 @@ import { listAgentPresets, listMachines, prepareMachineRun, } from "./launcher.j
 import { inboxHuman, respondToRun } from "./run-inbox.js";
 import { createRunStatusPublisher, isProcessAlive, readRunStatuses, runSessionId, runStatusDirectory, runStatusObserver, } from "./run-status.js";
 import { readRunWatches, runWatch, runWatchMatches, runWatchPath, sameRunWatch, writeRunWatches, } from "./run-watch.js";
+import { runsForViewer } from "./run-viewer.js";
 const [command, selector, ...argumentsAfterSelector] = process.argv.slice(2);
 const runsOptions = selector === undefined ? [] : [selector, ...argumentsAfterSelector];
 const watchUsage = "machine watch [<run-id-or-label-start> | --dir <path>]";
 const unwatchUsage = "machine unwatch <run-id-or-label-start> | --dir <path> | --all";
+const watchForUsage = "machine watch --for <session> [<run-id-or-label-start> | --dir <path>]";
+const unwatchForUsage = "machine unwatch --for <session> <run-id-or-label-start> | --dir <path> | --all";
 try {
+    const listing = command === "runs" ? parseRunsOptions(runsOptions) : undefined;
     if (command === "list" && selector === undefined) {
         const machines = await listMachines({ cwd: process.cwd() });
         if (machines.length === 0)
@@ -43,9 +47,11 @@ try {
     else if (command === "run" && selector !== undefined) {
         await runMachine(await resolveMachine(selector), argumentsAfterSelector);
     }
-    else if (command === "runs"
-        && runsOptions.every((option, index) => (option === "--json" || option === "--all") && runsOptions.indexOf(option) === index)) {
-        listRuns(runsOptions.includes("--json"), runsOptions.includes("--all"));
+    else if (listing !== undefined) {
+        if (listing.viewer === undefined)
+            listRuns(listing.json, listing.all);
+        else
+            listViewerRuns(listing.json, listing.all, listing.viewer);
     }
     else if (command === "respond" && selector !== undefined) {
         await respond([selector, ...argumentsAfterSelector]);
@@ -64,9 +70,12 @@ try {
             "  machine show <name-or-file>",
             "  machine run <name-or-file> [--agent role=preset]... [--input-file <file|->] [--] [input]",
             "  machine runs [--json] [--all]",
+            "  machine runs --for [<session>] [--project <dir>] [--json] [--all]",
             "  machine respond [--question] <run-id> <request-id> [--] <response>",
             `  ${watchUsage}`,
             `  ${unwatchUsage}`,
+            `  ${watchForUsage}`,
+            `  ${unwatchForUsage}`,
         ].join("\n"));
     }
 }
@@ -97,7 +106,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));
@@ -164,56 +173,136 @@ function listRuns(json, all) {
         printRunListing(record, index > 0, watches.some((watched) => runWatchMatches(watched, record)));
     });
 }
+/** What `machine runs` was asked; undefined when the options are not ones it takes. */
+function parseRunsOptions(args) {
+    let json = false;
+    let all = false;
+    let forViewer = false;
+    let session;
+    let project;
+    for (let index = 0; index < args.length; index += 1) {
+        const option = args[index];
+        const next = args[index + 1];
+        // What follows an option is its value unless it is another option.
+        const value = next === undefined || next.startsWith("--") ? undefined : next;
+        if (option === "--json" && !json)
+            json = true;
+        else if (option === "--all" && !all)
+            all = true;
+        else if (option === "--for" && !forViewer) {
+            forViewer = true;
+            // Without a session id the viewer is this process's own session.
+            session = value;
+            if (value !== undefined)
+                index += 1;
+        }
+        else if (option === "--project" && project === undefined && value !== undefined) {
+            project = value;
+            index += 1;
+        }
+        else
+            return undefined;
+    }
+    // A project is a viewer's: without --for the listing is of every session and project.
+    if (!forViewer)
+        return project === undefined ? { json, all } : undefined;
+    const viewer = { ...(session === undefined ? {} : { session }), ...(project === undefined ? {} : { project }) };
+    return { json, all, viewer };
+}
+/** The runs one viewer shows, by the rule its status line applies. */
+function listViewerRuns(json, all, viewer) {
+    if (viewer.project === "")
+        throw new Error("Expected a directory after --project");
+    const { directory, session } = requireWatchList(viewer.session);
+    const watches = readRunWatches(directory, session);
+    // As they are read, not by start time: runs updated in the same millisecond
+    // keep that order, here as in the library and on the status line.
+    const runs = runsForViewer(readRunStatuses(directory), {
+        sessionId: session,
+        // Compared absolute, wherever the command ran and however the path was written.
+        ...(viewer.project === undefined ? {} : { projectDir: resolve(viewer.project) }),
+        watches,
+    }, { all });
+    if (json) {
+        console.log(JSON.stringify(runs, null, 2));
+        return;
+    }
+    if (runs.length === 0)
+        console.log(`Session ${session} shows no Machine runs.`);
+    runs.forEach((run, index) => {
+        printRunListing(run, index > 0, watches.some((watched) => runWatchMatches(watched, run)));
+    });
+}
 /** Every record in the directory, including runs that finished or lost their process and are still recorded. */
 function publishedRuns(directory) {
     return readRunStatuses(directory).sort((left, right) => Date.parse(left.startedAt) - Date.parse(right.startedAt));
 }
 /** A run that stopped reporting without finishing has lost its process, as on the status line. */
 function runStatus(record) {
+    // A viewer's run already has the status its process leaves it.
+    if ("shown" in record)
+        return record.status;
     return record.status !== "completed" && record.status !== "failed" && !isProcessAlive(record.pid) ? "lost" : record.status;
 }
 function isActiveRun(record) {
     const status = runStatus(record);
     return status === "running" || status === "waiting";
 }
-function watch(args) {
-    const { directory, session } = requireWatchList();
+function watch(given) {
+    const { named, args, usage, who } = watchSession(given, watchUsage, watchForUsage);
+    const { directory, session } = requireWatchList(named);
     const watches = readRunWatches(directory, session);
     const runs = publishedRuns(directory);
     if (args.length === 0) {
         if (watches.length === 0)
-            console.log("This session watches no other runs.");
+            console.log(`${who} watches no other runs.`);
         for (const watched of watches) {
             console.log(describeWatch(watched));
             printWatchedRuns(watched, runs);
         }
         return;
     }
-    const added = parseWatch(args, watchUsage);
+    const added = parseWatch(args, usage);
     if (!watches.some((watched) => sameRunWatch(watched, added)))
         writeRunWatches(directory, session, [...watches, added]);
     console.log(`Watching ${describeWatch(added)}`);
     printWatchedRuns(added, runs);
 }
-function unwatch(args) {
-    const { directory, session } = requireWatchList();
+function unwatch(given) {
+    const { named, args, usage, who } = watchSession(given, unwatchUsage, unwatchForUsage);
+    if (args.length === 0)
+        throw new Error(`Usage: ${usage}`);
+    const { directory, session } = requireWatchList(named);
     if (args[0] === "--all") {
         if (args.length !== 1)
-            throw new Error(`Usage: ${unwatchUsage}`);
+            throw new Error(`Usage: ${usage}`);
         writeRunWatches(directory, session, []);
-        console.log("This session watches no other runs.");
+        console.log(`${who} watches no other runs.`);
         return;
     }
-    const removed = parseWatch(args, unwatchUsage);
+    const removed = parseWatch(args, usage);
     const watches = readRunWatches(directory, session);
     const kept = watches.filter((watched) => !sameRunWatch(watched, removed));
     if (kept.length === watches.length) {
-        console.log(`This session was not watching ${describeWatch(removed)}`);
+        console.log(`${who} was not watching ${describeWatch(removed)}`);
         return;
     }
     writeRunWatches(directory, session, kept);
     console.log(`No longer watching ${describeWatch(removed)}`);
 }
+/**
+ * Takes a leading `--for <session>` from what `machine watch` and
+ * `machine unwatch` were given: the list to change is then that session's and
+ * not this process's own.
+ */
+function watchSession(given, usage, forUsage) {
+    if (given[0] !== "--for")
+        return { named: undefined, args: given, usage, who: "This session" };
+    const named = given[1];
+    if (named === undefined || named.startsWith("--"))
+        throw new Error(`Usage: ${forUsage}`);
+    return { named, args: given.slice(2), usage: forUsage, who: `Session ${named}` };
+}
 function parseWatch(args, usage) {
     if (args[0] === "--dir") {
         if (args.length !== 2)
@@ -234,10 +323,10 @@ function printWatchedRuns(watched, runs) {
     for (const record of matched)
         console.log(`  ${runColumns(record).join("\t")}`);
 }
-/** The session whose watch list this process changes, and where the list is kept. */
-function requireWatchList() {
+/** The session whose watch list is read or changed, this process's own unless one is named, and where the list is kept. */
+function requireWatchList(named) {
     const directory = requireStatusDirectory();
-    const session = runSessionId();
+    const session = named ?? runSessionId();
     if (session === undefined) {
         throw new Error("No session to watch for: set MACHINES_RUN_OWNER to the id of the session whose status line shows the runs.");
     }
@@ -265,7 +354,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/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;
 /**
@@ -111,7 +129,9 @@ export declare function runStatusObserver(update: (change: RunStatusChange) => v
 };
 /**
  * The session a process belongs to: the owner of the runs it starts, and the
- * session whose watch list `machine watch` changes.
+ * session whose watch list `machine watch` changes. `MACHINES_RUN_OWNER` is how
+ * any host names it; the others are what Claude Code, Codex, and Pi give the
+ * commands they start.
  */
 export declare function runSessionId(environment?: NodeJS.ProcessEnv): string | undefined;
 /** Returns the valid records in a directory. Unreadable or malformed files are skipped. */

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;
@@ -187,10 +228,16 @@ export function runStatusObserver(update) {
 }
 /**
  * The session a process belongs to: the owner of the runs it starts, and the
- * session whose watch list `machine watch` changes.
+ * session whose watch list `machine watch` changes. `MACHINES_RUN_OWNER` is how
+ * any host names it; the others are what Claude Code, Codex, and Pi give the
+ * commands they start.
  */
 export function runSessionId(environment = process.env) {
-    return environment.MACHINES_RUN_OWNER || environment.CLAUDE_CODE_SESSION_ID || undefined;
+    return environment.MACHINES_RUN_OWNER
+        || environment.CLAUDE_CODE_SESSION_ID
+        || environment.CODEX_THREAD_ID
+        || environment.PI_SESSION_ID
+        || undefined;
 }
 /** Returns the valid records in a directory. Unreadable or malformed files are skipped. */
 export function readRunStatuses(directory) {
@@ -198,27 +245,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-viewer.d.ts

@@ -0,0 +1,55 @@
+import { type RunStatusRecord } from "./run-status.ts";
+import { type RunWatch } from "./run-watch.ts";
+export { readRunStatuses, runSessionId, runStatusDirectory } from "./run-status.ts";
+export type { RunStatusAgent, RunStatusHuman, RunStatusLimit, RunStatusRecord } from "./run-status.ts";
+export { readRunWatches } from "./run-watch.ts";
+export type { RunWatch } from "./run-watch.ts";
+/** How long a settled or lost run stays with its viewers before it drops out. */
+export declare const settledRunVisibleMilliseconds = 30000;
+/** One surface that shows runs: a coding-agent session, a status line, a browser tab. */
+export interface RunViewer {
+    /** Shows the runs this session owns. Its watch list is kept under the same id. */
+    readonly sessionId: string;
+    /** Absolute project directory; shows unowned runs working in it or below it. */
+    readonly projectDir?: string;
+    /** What the session asked to watch; shows the top-level runs an entry names, whoever owns them. */
+    readonly watches?: readonly RunWatch[];
+}
+export interface ViewerRunOptions {
+    readonly now?: number;
+    /** Keeps settled and lost runs however long ago they stopped. */
+    readonly all?: boolean;
+    readonly isAlive?: (pid: number) => boolean;
+}
+/**
+ * How a waiting run's Human request is answered: by `machine respond` with
+ * these two ids, or only through the program that hosts the run.
+ */
+export type RunAnswer = {
+    readonly via: "respond";
+    readonly runId: string;
+    readonly requestId: string;
+} | {
+    readonly via: "host";
+};
+/** A published record as one viewer shows it. */
+export interface ViewerRun extends Omit<RunStatusRecord, "status"> {
+    /** `lost` when the record says running or waiting and its process is gone. */
+    readonly status: RunStatusRecord["status"] | "lost";
+    /** Why the viewer shows it; the first that holds of owned, project, and watched. */
+    readonly shown: "owned" | "project" | "watched";
+    /** Present while the run waits on a request that something can answer. */
+    readonly answer?: RunAnswer;
+}
+/**
+ * The runs one viewer shows: the runs its session owns, unowned runs working
+ * inside its project, and runs it watches. Sub-runs are never shown, and a
+ * settled or lost run drops out after `settledRunVisibleMilliseconds`. Runs
+ * that can still change come first, then the most recently updated; records
+ * that tie keep the order they were given in.
+ *
+ * Pure apart from the default process-liveness probe. `claude/statusline.mjs`
+ * cannot load this module and carries a copy of the selection;
+ * tests/run-viewer.test.ts keeps the two in step.
+ */
+export declare function runsForViewer(records: readonly RunStatusRecord[], viewer: RunViewer, options?: ViewerRunOptions): ViewerRun[];

package/dist/src/run-viewer.js

@@ -0,0 +1,65 @@
+import { isProcessAlive } from "./run-status.js";
+import { isWithinDirectory, runWatchMatches } from "./run-watch.js";
+// The package exports this module as `@dna113p/machines/run-status`: what an
+// application needs to draw its own widgets for published runs. It only reads;
+// the publisher and the watch-list writer stay in the runtime.
+export { readRunStatuses, runSessionId, runStatusDirectory } from "./run-status.js";
+export { readRunWatches } from "./run-watch.js";
+/** How long a settled or lost run stays with its viewers before it drops out. */
+export const settledRunVisibleMilliseconds = 30_000;
+/**
+ * The runs one viewer shows: the runs its session owns, unowned runs working
+ * inside its project, and runs it watches. Sub-runs are never shown, and a
+ * settled or lost run drops out after `settledRunVisibleMilliseconds`. Runs
+ * that can still change come first, then the most recently updated; records
+ * that tie keep the order they were given in.
+ *
+ * Pure apart from the default process-liveness probe. `claude/statusline.mjs`
+ * cannot load this module and carries a copy of the selection;
+ * tests/run-viewer.test.ts keeps the two in step.
+ */
+export function runsForViewer(records, viewer, options = {}) {
+    const { now = Date.now(), all = false, isAlive = isProcessAlive } = options;
+    const visible = [];
+    for (const record of records) {
+        // Sub-runs belong to the run that started them, not to the session.
+        if (record.parent !== undefined)
+            continue;
+        const shown = shownBecause(record, viewer);
+        if (shown === undefined)
+            continue;
+        const updatedAt = Date.parse(record.updatedAt);
+        const recorded = record.status === "running" || record.status === "waiting";
+        // A run that stopped reporting without finishing has lost its process.
+        const lost = recorded && !isAlive(record.pid);
+        const active = recorded && !lost;
+        if (!active && !all && now - updatedAt > settledRunVisibleMilliseconds)
+            continue;
+        const status = lost ? "lost" : record.status;
+        const answer = status === "waiting" ? runAnswer(record) : undefined;
+        visible.push({ run: { ...record, status, shown, ...(answer === undefined ? {} : { answer }) }, active, updatedAt });
+    }
+    visible.sort((left, right) => Number(right.active) - Number(left.active) || right.updatedAt - left.updatedAt);
+    return visible.map(({ run }) => run);
+}
+function shownBecause(record, viewer) {
+    // An owned run is its owner's: the project it works in shows it to nobody else.
+    if (record.owner !== undefined) {
+        if (record.owner === viewer.sessionId)
+            return "owned";
+    }
+    else if (viewer.projectDir !== undefined && isWithinDirectory(record.cwd, viewer.projectDir)) {
+        return "project";
+    }
+    // A run the session asked to watch is shown whoever owns it and wherever it works.
+    return viewer.watches?.some((watch) => runWatchMatches(watch, record)) === true ? "watched" : undefined;
+}
+function runAnswer(record) {
+    if (record.human === undefined)
+        return undefined;
+    if (record.answeredBy === "host")
+        return { via: "host" };
+    // A record from before requests had ids says nothing about how it is answered.
+    const { requestId } = record.human;
+    return requestId === undefined ? undefined : { via: "respond", runId: record.id, requestId };
+}

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

@@ -18,7 +18,9 @@ export declare function readRunWatches(directory: string, sessionId: string): Ru
 /** Replaces a session's watch list; an empty one removes its file. */
 export declare function writeRunWatches(directory: string, sessionId: string, watches: readonly RunWatch[]): void;
 /** Whether a watch names a run. A sub-run is never watched: it is its parent's detail. */
-export declare function runWatchMatches(watch: RunWatch, record: RunStatusRecord): boolean;
+export declare function runWatchMatches(watch: RunWatch, record: Pick<RunStatusRecord, "id" | "label" | "cwd" | "parent">): boolean;
+/** Whether a path is a directory or inside it. Only absolute paths say where they are. */
+export declare function isWithinDirectory(path: string, directory: string): boolean;
 /** Checks and normalizes what `machine watch` was given. */
 export declare function runWatch(input: RunWatch): RunWatch;
 export declare function sameRunWatch(left: RunWatch, right: RunWatch): boolean;

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
@@ -54,18 +52,22 @@ export function writeRunWatches(directory, sessionId, watches) {
 export function runWatchMatches(watch, record) {
     if (record.parent !== undefined)
         return false;
-    if ("dir" in watch) {
-        if (!isAbsolute(record.cwd))
-            return false;
-        const cwd = resolve(record.cwd);
-        return cwd === watch.dir || cwd.startsWith(watch.dir.endsWith(sep) ? watch.dir : `${watch.dir}${sep}`);
-    }
+    if ("dir" in watch)
+        return isWithinDirectory(record.cwd, watch.dir);
     if (record.id.startsWith(watch.text))
         return true;
     // The label must start with the whole text, not with a longer word that begins like it.
     const next = record.label?.startsWith(watch.text) ? record.label.slice(watch.text.length) : undefined;
     return next !== undefined && !/^[\p{L}\p{N}_-]/u.test(next);
 }
+/** Whether a path is a directory or inside it. Only absolute paths say where they are. */
+export function isWithinDirectory(path, directory) {
+    if (!isAbsolute(path) || !isAbsolute(directory))
+        return false;
+    const outer = resolve(directory);
+    const inner = resolve(path);
+    return inner === outer || inner.startsWith(outer.endsWith(sep) ? outer : `${outer}${sep}`);
+}
 /** Checks and normalizes what `machine watch` was given. */
 export function runWatch(input) {
     if ("dir" in input) {
@@ -94,15 +96,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

@@ -61,6 +61,8 @@ MCP server ────┘       ↑
 | `src/discovery-worker.ts` | Fresh metadata imports in disposable workers |
 | `src/host.ts` | One child run, IPC, Human request identity, owned process termination, run-status publication for the run |
 | `src/session.ts` | Shared Pi/MCP run lifecycle, snapshots, response handling, retention, shutdown |
+| `src/run-status.ts`, `src/run-watch.ts` | The run-status directory rule, one record per published run, session identity, and each session's watch list |
+| `src/run-viewer.ts` | Which published runs one viewer shows; exported with the readers as `@dna113p/machines/run-status` |
 | `src/cli.ts` | Command parsing, terminal progress, source inspection |
 | `pi-extension/index.ts` | Pi tools, widgets, notifications, native input presentation |
 | `mcp/server.ts` | MCP schemas, tool results, and the optional HTML resource |
@@ -100,7 +102,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
@@ -115,6 +122,14 @@ only way to answer it, its record says so, and `machine respond` refuses it. See
 A session's watch list changes only which published runs its status line shows.
 It gives no ownership of a run and no way to answer one.
 
+Which runs a viewer shows is one rule, `runsForViewer` in `src/run-viewer.ts`:
+`machine runs --for` prints its answer, and `@dna113p/machines/run-status`
+exports it with the readers, so that an application draws its own widgets
+without a second copy. It selects and orders; presentation stays with whatever
+draws. The standalone status line cannot load it and carries a tested copy, as
+it does of the directory rule. See
+[Integrations](integrations.md#drawing-your-own-widgets).
+
 Closing a session terminates active and starting hosts. Host termination includes
 ordinary descendants in the host's owned process group on POSIX and process-tree
 termination on Windows. Deliberately detached processes can escape normal ownership;

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
 {
@@ -190,8 +209,11 @@ change (directory `0700`, file `0600`):
 `status` is `running`, `waiting`, `completed`, or `failed`. `state` is the current
 state as a string (JSON for a nested state). `agent` is present while an Agent
 state has reported its identity, and `error` after a failure. `owner` is
-`MACHINES_RUN_OWNER` when set, otherwise `CLAUDE_CODE_SESSION_ID`, otherwise
-absent. `stateSince` is when the current state was entered. `label` is the first
+`MACHINES_RUN_OWNER` when set, otherwise the session id the coding agent gives
+the commands it starts (`CLAUDE_CODE_SESSION_ID`, then `CODEX_THREAD_ID`, then
+`PI_SESSION_ID`), otherwise absent; see
+[how a host names its session](#drawing-your-own-widgets). `stateSince` is when
+the current state was entered. `label` is the first
 line of `MACHINES_RUN_LABEL` (at most 160 characters) when a launcher sets it to
 say what the run is for, such as a ticket id and title; it is the launcher's
 choice to publish that text. `machine run` exports its run id as
@@ -199,11 +221,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 its host asks with `publishRunStatus: true` and the
-variable is set in the hosting process, as a daemon that runs tickets does. A
+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 the variable. Two options replace the environment for that one run:
+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
@@ -262,17 +284,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
@@ -287,7 +329,8 @@ waiting run its prompt, request id, and choices (tab-separated when its
 output is not a terminal). A run's label follows as a fifth column when it has
 one, and a sixth says `watched` for a run this session
 [watches](#watching-other-runs). It lists the running and waiting runs of every
-session and project. `--all`, with or without `--json`, lists every published
+session and project; `--for` narrows it to
+[what one viewer shows](#drawing-your-own-widgets). `--all`, with or without `--json`, lists every published
 run: also the ones whose records remain after they finished, as `completed` or
 `failed`, or after their process disappeared, as `lost` (in JSON such a record
 keeps the status it last published). A run answered through its host shows
@@ -330,17 +373,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`
@@ -348,12 +399,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",
@@ -397,8 +449,8 @@ to change the 120-column truncation.
 A session can pull in runs it did not start: a ticket that a daemon runs, or a
 run started by another session or under another project. Nothing is configured.
 The session is identified as a run's `owner` is, by `MACHINES_RUN_OWNER` and
-otherwise `CLAUDE_CODE_SESSION_ID`, so an agent inside Claude Code only runs the
-command.
+otherwise by the session id its coding agent gives it, so an agent inside Claude
+Code, Codex, or Pi only runs the command.
 
 ```bash
 machine runs                   # running and waiting runs, with their labels
@@ -407,6 +459,7 @@ machine watch org-9            # runs whose id or label starts with org-9
 machine watch --dir ../other   # runs working in that directory or below it
 machine watch                  # what this session watches, and the published runs each entry matches now
 machine unwatch org-9          # also: unwatch --dir <path>, unwatch --all
+machine watch --for <session> org-9   # the same commands for another session's list
 ```
 
 - `machine watch <text>` names every top-level run whose id starts with the
@@ -420,6 +473,10 @@ machine unwatch org-9          # also: unwatch --dir <path>, unwatch --all
   before its run exists. `machine watch` lists a matched run for as long as its
   record remains, with the status `machine runs --all` gives it, so it also
   says how a watched run ended.
+- `--for <session>`, first, makes `machine watch` and `machine unwatch` read
+  and change the list of the session it names instead of this process's own.
+  A program that draws [its own widgets](#drawing-your-own-widgets) for a
+  viewer manages that viewer's list this way, without setting a variable.
 
 A watched run is shown even when another session owns it or it works outside
 the project. Everything else is as for any run: sub-runs stay hidden, a run is
@@ -435,10 +492,125 @@ 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.
+message when publication is off or when nothing names the session.
+
+### Drawing your own widgets
+
+Any application can show Machine runs in its own way from what is already
+published: an extension for Codex or Pi, a web app, an editor panel. The Claude
+Code status line above is one such consumer. Nothing is configured and nothing
+new runs; there are three ways to read the same directory:
+
+| Read with | You get |
+| --- | --- |
+| `machine runs --for <session> --json` | The runs one viewer shows, each ready to draw |
+| `@dna113p/machines/run-status` | The same rule and the readers, in your own process |
+| The files | The [records](#run-status-for-host-status-lines) and [watch lists](#watching-other-runs) themselves; the rule is then yours to apply |
+
+A viewer is one surface that shows runs: a session of a coding agent, a browser
+tab, a status line. It is named by a session id and may have a project
+directory. The rule that decides what it shows is the status line's:
+
+- only top-level runs: a run started from inside another Machine is never shown;
+- the runs its session owns, unowned runs working in its project directory or
+  below it, and the runs its session [watches](#watching-other-runs), whoever
+  owns them;
+- a run recorded as running or waiting whose process is gone is `lost`;
+- a finished or lost run stays for 30 seconds and then drops out;
+- each run once, the ones that can still change first, then the most recently
+  updated. Runs updated in the same millisecond keep the order they were read
+  in from the directory, for the command, the library, and the status line
+  alike.
+
+Both ways below take a snapshot. Read again to refresh, as the status line does
+every few seconds, and read where the runs' processes can be seen, or every run
+looks `lost`.
+
+```bash
+machine runs --for "$SESSION" --project "$PWD" --json   # what that viewer shows
+machine runs --for --json                               # for this process's own session
+machine runs --for "$SESSION" --all                     # as text, and with older finished and lost runs
+machine watch --for "$SESSION" org-9                    # change what that viewer watches
+```
+
+`--for` takes the viewer's session id; with no id after it, the viewer is this
+process's own session, and the command fails when nothing names one.
+`--project` is the viewer's project directory, compared as an absolute path;
+without it only owned and watched runs are selected. `--all` also keeps the
+finished and lost runs that the 30 seconds would have dropped, for as long as
+their records remain. Without `--json` the runs are printed in the columns of
+`machine runs`. Without `--for`, `machine runs` is unchanged: every session's
+running and waiting runs, as plain records.
+
+Each item is the published record with three additions:
+
+```json
+{
+  "schemaVersion": 2, "id": "1a2b3c4d-…", "pid": 4242, "owner": "<session id>",
+  "machine": "release", "path": "/work/.machines/release.ts", "cwd": "/work",
+  "status": "waiting", "state": "approve",
+  "human": { "prompt": "Publish version 0.4.0?", "requestId": "9f8e7d6c-…", "choices": ["publish", "hold"] },
+  "startedAt": "2026-03-04T05:06:07.000Z", "updatedAt": "2026-03-04T05:08:12.000Z",
+  "shown": "owned",
+  "answer": { "via": "respond", "runId": "1a2b3c4d-…", "requestId": "9f8e7d6c-…" }
+}
+```
+
+- `status` is the effective one: what the record says, or `lost`.
+- `shown` says why the viewer shows the run: `owned`, `project`, or `watched`,
+  the first of them that holds.
+- `answer` is present while the run waits on a Human request that something
+  can answer. `"via": "respond"` carries the two ids for
+  `machine respond <runId> <requestId> <response>`; `"via": "host"` means only
+  the program hosting the run can answer it, so a widget shows the prompt and
+  offers no input. `human` still has the prompt, choices, and suggestions.
+
+Nothing is added for presentation: no colour, layout, or shortening, and no
+limit on how many runs are returned. Recorded text is the run's own, so escape
+it for your surface as the status line strips control characters.
+
+The library gives the same answer without starting a process:
+
+```ts
+import {
+  readRunStatuses, readRunWatches, runStatusDirectory, runsForViewer,
+} from "@dna113p/machines/run-status";
+
+const directory = runStatusDirectory(); // undefined while publication is off
+const runs = directory === undefined ? [] : runsForViewer(readRunStatuses(directory), {
+  sessionId,
+  projectDir: "/work/project",
+  watches: readRunWatches(directory, sessionId),
+});
+for (const run of runs) draw(run.label ?? run.id, run.status, run.shown, run.answer);
+```
+
+`runsForViewer(records, viewer, options)` is pure apart from probing whether
+each process is alive; `options` takes `now`, `all`, and an `isAlive` of your
+own. The module also exports `runSessionId`, the types of a record, a watch, a
+viewer, and an item, and `settledRunVisibleMilliseconds`. It only reads:
+publishing stays with the runtime, and a viewer's watch list is changed with
+`machine watch --for`.
+
+**Naming the session.** A viewer shows the runs whose `owner` is its session
+id, so the host and the runs it starts must agree on that id. Any host can set
+`MACHINES_RUN_OWNER` in the environment of the commands it starts and pass the
+same value to `--for`; the id may use letters, digits, `.`, `_`, and `-`. Where
+it is not set, the id is the one the coding agent already gives its commands:
+
+| Host | Variable | Given to |
+| --- | --- | --- |
+| Any | `MACHINES_RUN_OWNER` | Whatever the host starts with it set; takes precedence |
+| Claude Code | `CLAUDE_CODE_SESSION_ID` | The commands a session runs; also the `session_id` its status line receives |
+| Codex | `CODEX_THREAD_ID` | The commands a thread runs |
+| Pi | `PI_SESSION_ID` | The commands its `bash` and `powershell` tools run, not `!` commands typed by the user |
+
+The first one that is set names the session, in that order. A run started from
+inside one of these agents is therefore owned by that session: it is shown
+there, and in another session only when that session watches it.
 
 ## Troubleshooting
 
@@ -446,6 +618,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.2",
+  "version": "0.3.4",
   "description": "Reusable workflows coordinating agents, local operations, and human decisions.",
   "license": "MIT",
   "repository": {
@@ -36,7 +36,8 @@
     "./host": { "types": "./dist/src/host.d.ts", "import": "./dist/src/host.js" },
     "./launcher": { "types": "./dist/src/launcher.d.ts", "import": "./dist/src/launcher.js" },
     "./mcp": { "types": "./dist/mcp/server.d.ts", "import": "./dist/mcp/server.js" },
-    "./pi-extension": { "types": "./dist/pi-extension/index.d.ts", "import": "./dist/pi-extension/index.js" }
+    "./pi-extension": { "types": "./dist/pi-extension/index.d.ts", "import": "./dist/pi-extension/index.js" },
+    "./run-status": { "types": "./dist/src/run-viewer.d.ts", "import": "./dist/src/run-viewer.js" }
   },
   "files": ["dist", "claude/statusline.mjs", "docs/architecture.md", "docs/authoring.md", "docs/integrations.md", "docs/local-decisions.md", "services/laya/server.py", "skills", "LICENSE", "README.md"],
   "scripts": {