@dna113p/machines 0.3.3 → 0.3.4

package/README.md

@@ -176,10 +176,10 @@ npm ci
 npm pack
 ```
 
-Then install the generated `dna113p-machines-0.3.3.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.3.tgz
+npm install /absolute/path/to/machines/dna113p-machines-0.3.4.tgz
 npx machine list
 ```
 
@@ -201,6 +201,7 @@ 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
@@ -215,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

@@ -4,8 +4,9 @@
 // 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.
+// 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";

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"));
     }
 }
@@ -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.");
     }

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

@@ -129,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

@@ -228,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) {

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

@@ -52,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) {

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 |
@@ -120,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

@@ -209,8 +209,11 @@ directory is created by the first write, as `0700`, and each file is `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
@@ -326,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
@@ -445,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
@@ -455,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
@@ -468,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
@@ -486,7 +495,122 @@ session id that is not safe as a file name is refused. Removing the last entry
 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dna113p/machines",
-  "version": "0.3.3",
+  "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": {