@dna113p/machines 0.3.0 → 0.3.2

package/README.md

@@ -176,10 +176,10 @@ npm ci
 npm pack
 ```
 
-Then install the generated `dna113p-machines-0.3.0.tgz` into a project:
+Then install the generated `dna113p-machines-0.3.2.tgz` into a project:
 
 ```bash
-npm install /absolute/path/to/machines/dna113p-machines-0.3.0.tgz
+npm install /absolute/path/to/machines/dna113p-machines-0.3.2.tgz
 npx machine list
 ```
 
@@ -198,8 +198,10 @@ read. A published run that is waiting for a Human can then be answered from
 outside its own terminal:
 
 ```bash
-machine runs [--json]                              # running and waiting runs
+machine runs [--json] [--all]                      # running and waiting runs; --all adds finished and lost ones
 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
 ```
 
 `machine runs` shows each waiting run's prompt, request id, and choices. A run
@@ -207,6 +209,10 @@ started without a terminal, for example by a coordinating agent or a script,
 waits for `machine respond` instead of failing. Anything running as the same user
 can answer a waiting run, including an approval; see
 [answering a waiting run from outside](docs/integrations.md#answering-a-waiting-run-from-outside).
+Runs hosted through `startMachineHost` publish too and are answered through their
+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).
 
 ## Execution model and limitations
 
@@ -280,18 +286,23 @@ npm run smoke:plugin   # exercise a relocated standalone plugin
 
 The [publishing workflow](.github/workflows/publish.yml) uses a standard GitHub
 runner and npm trusted publishing, without an npm token stored in GitHub.
-Pushing a `vX.Y.Z` tag runs the checks above and publishes to npm if they pass.
-The tag must match the stable version in `package.json`.
+A release is a change to the version in `package.json`. When `main` receives a
+stable version that npm does not have yet, the workflow runs the checks above,
+publishes to npm if they pass, and tags the commit `vX.Y.Z`. Every other push to
+`main` publishes nothing.
 
-For example, to release the next minor version from an up-to-date, clean `main`:
+For example, to release the next minor version, bump it on a branch and merge
+that branch:
 
 ```bash
-npm version minor
-git push origin main --follow-tags
+npm version minor --no-git-tag-version
+git commit -am "Release X.Y.0"
 ```
 
-Running **Publish to npm** manually in GitHub Actions performs the checks and a
-publishing dry run; it does not publish a package.
+Pushing a `vX.Y.Z` tag yourself still publishes that version if npm lacks it;
+the tag must match the stable version in `package.json`. Running **Publish to
+npm** manually in GitHub Actions performs the checks and a publishing dry run;
+it does not publish a package.
 
 Licensed under the [MIT License](LICENSE).
 

package/claude/statusline.mjs

@@ -3,7 +3,8 @@
 // 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.
+// record shape below mirrors RunStatusRecord in src/run-status.ts, and the
+// watch list and its matching mirror src/run-watch.ts.
 
 import { readdirSync, readFileSync, realpathSync } from "node:fs";
 import { isAbsolute, join, resolve, sep } from "node:path";
@@ -27,6 +28,7 @@ export function runStatusLines(records, options = {}) {
   const {
     sessionId,
     projectDir,
+    watches = [],
     now = Date.now(),
     columns = defaultColumns,
     color = true,
@@ -38,7 +40,9 @@ export function runStatusLines(records, options = {}) {
   const visible = [];
   for (const record of records) {
     // Sub-runs belong to the run that started them, not to the session.
-    if (!isRecord(record) || record.parent !== undefined || !isVisibleTo(record, sessionId, projectDir)) continue;
+    if (!isRecord(record) || record.parent !== undefined) continue;
+    // A run the session asked to watch is shown whoever owns it and wherever it works.
+    if (!isVisibleTo(record, sessionId, projectDir) && !watches.some((watch) => isWatched(record, watch))) 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.
@@ -91,9 +95,25 @@ export function runStatusLines(records, options = {}) {
 function isVisibleTo(record, sessionId, projectDir) {
   if (record.owner !== undefined) return typeof sessionId === "string" && record.owner === sessionId;
   if (typeof projectDir !== "string" || !isAbsolute(projectDir) || !isAbsolute(record.cwd)) return false;
-  const project = resolve(projectDir);
-  const cwd = resolve(record.cwd);
-  return cwd === project || cwd.startsWith(project.endsWith(sep) ? project : `${project}${sep}`);
+  return isInside(record.cwd, projectDir);
+}
+
+function isInside(path, directory) {
+  const outer = resolve(directory);
+  const inner = resolve(path);
+  return inner === outer || inner.startsWith(outer.endsWith(sep) ? outer : `${outer}${sep}`);
+}
+
+function isWatched(record, watch) {
+  if (watch === null || typeof watch !== "object") return false;
+  const { text, dir } = watch;
+  if (typeof dir === "string" && text === undefined) {
+    return isAbsolute(dir) && isAbsolute(record.cwd) && isInside(record.cwd, dir);
+  }
+  if (typeof text !== "string" || text === "" || dir !== undefined) return false;
+  if (record.id.startsWith(text)) return true;
+  // The label must start with the whole text, not with a longer word that begins like it.
+  return record.label?.startsWith(text) === true && !/^[\p{L}\p{N}_-]/u.test(record.label.slice(text.length));
 }
 
 function isRecord(value) {
@@ -204,6 +224,18 @@ function readRecords(directory) {
   return records;
 }
 
+/** What the session asked to watch with `machine watch`; nothing when it has no readable list. */
+function readWatches(directory, sessionId) {
+  // The id is part of the file name, so it must not be able to leave the directory.
+  if (typeof sessionId !== "string" || !/^[A-Za-z0-9_-][A-Za-z0-9._-]*$/u.test(sessionId)) return [];
+  try {
+    const { watches } = JSON.parse(readFileSync(join(directory, `.watch.${sessionId}.json`), "utf8"));
+    return Array.isArray(watches) ? watches : [];
+  } catch {
+    return [];
+  }
+}
+
 async function main() {
   const directory = process.env.MACHINES_RUN_STATUS_DIR;
   if (directory === undefined || directory === "" || process.stdin.isTTY) return;
@@ -217,6 +249,7 @@ async function main() {
   const columns = /^[0-9]+$/u.test(process.env.COLUMNS ?? "") ? Number(process.env.COLUMNS) : defaultColumns;
   const lines = runStatusLines(readRecords(directory), {
     sessionId: input.session_id,
+    watches: readWatches(directory, input.session_id),
     projectDir: [input.workspace?.project_dir, input.workspace?.current_dir, input.cwd]
       .find((path) => typeof path === "string" && path !== ""),
     columns,

package/dist/mcp/server.js

@@ -176,7 +176,8 @@ export class MachineSession {
         return result(text, { agents });
     }
     async start(input) {
-        const run = await this.#session.start(parse(startInput, input));
+        // This server publishes its runs itself, so that they also take responses through their inbox.
+        const run = await this.#session.start({ ...parse(startInput, input), publishRunStatus: "caller" });
         return result(`Started ${run.machine}.\nRun id: ${run.id}\nStatus: ${run.status}`, { run });
     }
     status(input) {

package/dist/src/cli.js

@@ -10,8 +10,12 @@ import { assertJsonValue, isJsonValue } from "./json.js";
 import { discoverMachines, machinesUserHome } from "./discovery.js";
 import { listAgentPresets, listMachines, prepareMachineRun, } from "./launcher.js";
 import { inboxHuman, respondToRun } from "./run-inbox.js";
-import { createRunStatusPublisher, isProcessAlive, readRunStatuses, runStatusDirectory, } from "./run-status.js";
+import { createRunStatusPublisher, isProcessAlive, readRunStatuses, runSessionId, runStatusDirectory, runStatusObserver, } from "./run-status.js";
+import { readRunWatches, runWatch, runWatchMatches, runWatchPath, sameRunWatch, writeRunWatches, } from "./run-watch.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";
 try {
     if (command === "list" && selector === undefined) {
         const machines = await listMachines({ cwd: process.cwd() });
@@ -39,12 +43,19 @@ try {
     else if (command === "run" && selector !== undefined) {
         await runMachine(await resolveMachine(selector), argumentsAfterSelector);
     }
-    else if (command === "runs" && (selector === undefined || selector === "--json") && argumentsAfterSelector.length === 0) {
-        listRuns(selector === "--json");
+    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 (command === "respond" && selector !== undefined) {
         await respond([selector, ...argumentsAfterSelector]);
     }
+    else if (command === "watch") {
+        watch(selector === undefined ? [] : [selector, ...argumentsAfterSelector]);
+    }
+    else if (command === "unwatch" && selector !== undefined) {
+        unwatch([selector, ...argumentsAfterSelector]);
+    }
     else {
         throw new Error([
             "Usage:",
@@ -52,8 +63,10 @@ try {
             "  machine agents",
             "  machine show <name-or-file>",
             "  machine run <name-or-file> [--agent role=preset]... [--input-file <file|->] [--] [input]",
-            "  machine runs [--json]",
+            "  machine runs [--json] [--all]",
             "  machine respond [--question] <run-id> <request-id> [--] <response>",
+            `  ${watchUsage}`,
+            `  ${unwatchUsage}`,
         ].join("\n"));
     }
 }
@@ -87,31 +100,11 @@ async function runMachine(machinePath, args) {
     const statusDirectory = runStatusDirectory();
     // Machines started by this run's Operations and Agents are its sub-runs.
     process.env.MACHINES_RUN_PARENT = runId;
-    let publishedState;
-    // A runner reports its identity as it starts. For a state entered by a
-    // transition that is before the state is announced, so an identity is held
-    // for the rest of the tick and published with the state it belongs to.
-    let arriving;
+    const observed = runStatusObserver((change) => published.update(change));
     try {
         const result = await prepared.start({
             onAgentUpdate(update) {
-                if (update.type === "identity") {
-                    arriving = update;
-                    queueMicrotask(() => {
-                        if (arriving !== update)
-                            return;
-                        arriving = undefined;
-                        published.update({ agent: update });
-                    });
-                }
-                else if (update.type === "limit" && update.status !== "swapped") {
-                    // A swap while every preset is being tried again leaves the wait as it is published.
-                    published.update({
-                        limit: update.status === "resumed"
-                            ? undefined
-                            : { text: update.text, ...(update.until === undefined ? {} : { until: update.until }) },
-                    });
-                }
+                observed.onAgentUpdate(update);
                 status.onAgentUpdate(update);
             },
             // A published run can also be answered through its inbox by `machine respond`.
@@ -134,14 +127,7 @@ async function runMachine(machinePath, args) {
                 status.onHumanInput(active);
             },
             onState(state) {
-                const entered = formatState(state);
-                if (entered === publishedState)
-                    published.update({ state });
-                else {
-                    published.update({ state, agent: arriving });
-                    arriving = undefined;
-                }
-                publishedState = entered;
+                observed.onState(state);
                 status.onState(state);
             },
         });
@@ -161,20 +147,104 @@ async function runMachine(machinePath, args) {
         status.close();
     }
 }
-function listRuns(json) {
-    const runs = readRunStatuses(requireStatusDirectory())
-        .filter((record) => (record.status === "running" || record.status === "waiting") && isProcessAlive(record.pid))
-        .sort((left, right) => Date.parse(left.startedAt) - Date.parse(right.startedAt));
+function listRuns(json, all) {
+    const directory = requireStatusDirectory();
+    const published = publishedRuns(directory);
+    // Without --all, only the runs that can still change or be answered.
+    const runs = all ? published : published.filter(isActiveRun);
     if (json) {
         console.log(JSON.stringify(runs, null, 2));
         return;
     }
     if (runs.length === 0)
-        console.log("No Machine runs are running or waiting.");
+        console.log(all ? "No Machine runs are published." : "No Machine runs are running or waiting.");
+    const session = runSessionId();
+    const watches = session === undefined ? [] : readRunWatches(directory, session);
     runs.forEach((record, index) => {
-        printRunListing(record, index > 0);
+        printRunListing(record, index > 0, watches.some((watched) => runWatchMatches(watched, record)));
     });
 }
+/** 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) {
+    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();
+    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.");
+        for (const watched of watches) {
+            console.log(describeWatch(watched));
+            printWatchedRuns(watched, runs);
+        }
+        return;
+    }
+    const added = parseWatch(args, watchUsage);
+    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();
+    if (args[0] === "--all") {
+        if (args.length !== 1)
+            throw new Error(`Usage: ${unwatchUsage}`);
+        writeRunWatches(directory, session, []);
+        console.log("This session watches no other runs.");
+        return;
+    }
+    const removed = parseWatch(args, unwatchUsage);
+    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)}`);
+        return;
+    }
+    writeRunWatches(directory, session, kept);
+    console.log(`No longer watching ${describeWatch(removed)}`);
+}
+function parseWatch(args, usage) {
+    if (args[0] === "--dir") {
+        if (args.length !== 2)
+            throw new Error(`Usage: ${usage}`);
+        return runWatch({ dir: args[1] });
+    }
+    if (args[0] !== "--" && args[0]?.startsWith("--") === true)
+        throw new Error(`Usage: ${usage}`);
+    return runWatch({ text: (args[0] === "--" ? args.slice(1) : args).join(" ") });
+}
+function describeWatch(watched) {
+    return "dir" in watched ? `--dir ${watched.dir}` : watched.text;
+}
+function printWatchedRuns(watched, runs) {
+    const matched = runs.filter((record) => runWatchMatches(watched, record));
+    if (matched.length === 0)
+        console.log("  no published run matches yet");
+    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() {
+    const directory = requireStatusDirectory();
+    const session = 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.");
+    }
+    // Refuses a session id that cannot name a file.
+    runWatchPath(directory, session);
+    return { directory, session };
+}
 async function respond(args) {
     const question = args[0] === "--question";
     const [runId, requestId, ...words] = question ? args.slice(1) : args;
@@ -301,30 +371,48 @@ function printAgentListing(preset, separate) {
         console.log(`  fallback: ${preset.fallback.join(", ") || "none"}`);
     console.log(`  ${dim(preset.source)}`);
 }
-function printRunListing(record, separate) {
+/** Recorded text must not be able to move the cursor or restyle the terminal. */
+function plain(text) {
+    return text.replace(/[\u0000-\u001f\u007f-\u009f]+/gu, " ").trim();
+}
+/** A run as tab-separated columns: its label follows the four that were always there. */
+function runColumns(record) {
+    const label = record.label === undefined ? "" : plain(record.label);
+    return [record.id, record.machine, runStatus(record), record.state ?? "starting"].map(plain).concat(label === "" ? [] : [label]);
+}
+function printRunListing(record, separate, watched) {
     const state = record.state ?? "starting";
-    const human = record.status === "waiting" ? record.human : undefined;
-    // Recorded text must not be able to move the cursor or restyle the terminal.
-    const plain = (text) => text.replace(/[\u0000-\u001f\u007f-\u009f]+/gu, " ").trim();
-    const details = human === undefined ? (record.limit === undefined ? [] : [plain(record.limit.text)]) : [
+    const recorded = runStatus(record);
+    const human = recorded === "waiting" ? record.human : undefined;
+    // A run that finished or lost its process is no longer waiting for anything.
+    const limit = recorded === "running" || recorded === "waiting" ? record.limit : undefined;
+    const details = human === undefined ? (limit === undefined ? [] : [plain(limit.text)]) : [
         ...human.prompt.split("\n").map(plain).filter((line) => line !== ""),
         ...(human.requestId === undefined ? [] : [`request: ${plain(human.requestId)}`]),
+        ...(record.answeredBy === "host" ? ["answered through its host"] : []),
         ...(human.choices === undefined ? [] : [`choices: ${human.choices.map(plain).join(", ")}`]),
         ...(human.suggestions === undefined ? [] : [`suggestions: ${human.suggestions.map(plain).join(", ")}`]),
         ...(human.discussion === true ? ["discussion: questions allowed"] : []),
     ];
     if (!process.stdout.isTTY) {
-        console.log([record.id, record.machine, record.status, state].map(plain).join("\t"));
+        const columns = runColumns(record);
+        // The mark has its own column, after the label's, whether or not the run has a label.
+        console.log((watched ? [...columns, ...(columns.length === 4 ? [""] : []), "watched"] : columns).join("\t"));
         for (const line of details)
             console.log(`  ${line}`);
         return;
     }
     if (separate)
         console.log();
-    const status = record.status === "waiting" ? yellow("waiting") : cyan("running");
-    console.log(`${bold(plain(record.id))}  ${bold(cyan(plain(record.machine)))} › ${status} · ${plain(state)}`);
-    for (const line of details)
-        console.log(`  ${line.startsWith("request: ") ? dim(line) : line}`);
+    const status = recorded === "waiting"
+        ? yellow(recorded)
+        : recorded === "running" ? cyan(recorded) : recorded === "completed" ? green(recorded) : red(recorded);
+    console.log(`${bold(plain(record.id))}  ${bold(cyan(plain(record.machine)))} › ${status} · ${plain(state)}${watched ? ` · ${dim("watched")}` : ""}`);
+    if (record.label !== undefined && plain(record.label) !== "")
+        console.log(`  ${plain(record.label)}`);
+    for (const line of details) {
+        console.log(`  ${line.startsWith("request: ") || line === "answered through its host" ? dim(line) : line}`);
+    }
 }
 function printMachineHeader(machinePath) {
     if (!process.stdout.isTTY) {

package/dist/src/host.d.ts

@@ -7,6 +7,17 @@ export interface HostedHumanRequest extends HumanRequest {
 }
 export interface MachineHostOptions extends PrepareMachineRunOptions {
     readonly signal?: AbortSignal;
+    /** What the run is for, in its published run status. `MACHINES_RUN_LABEL` applies when absent. */
+    readonly label?: string;
+    /** The session that owns the run in its published run status. The environment's owner applies when absent. */
+    readonly owner?: string;
+    /**
+     * Asks for the run's status to be published where run-status publication is on.
+     * `true`: this host publishes it. `"caller"`: the caller publishes it itself,
+     * under the run's id, as the MCP server does. Absent: nothing about the run is
+     * published or handed down, and the caller presents the run in its own way.
+     */
+    readonly publishRunStatus?: boolean | "caller";
     readonly onAgentUpdate?: (update: AgentUpdate) => void;
     readonly onHumanRequest?: (request: HostedHumanRequest) => void;
     readonly onState?: (state: StateValue) => void;
@@ -16,6 +27,8 @@ export interface MachineHostResult {
     readonly output?: JsonValue;
 }
 export interface MachineHostRun {
+    /** Names the run. Its published run status, when there is one, is recorded under this id. */
+    readonly id: string;
     readonly name: string;
     readonly description: string;
     readonly path: string;

package/dist/src/host.js

@@ -1,8 +1,11 @@
 import { execFileSync, fork } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import * as v from "valibot";
 import { assertJsonValue, isJsonValue } from "./json.js";
 import { prepareMachineRun, } from "./launcher.js";
+import { createRunStatusPublisher, runStatusDirectory, runStatusObserver, } from "./run-status.js";
 const childArgument = "--machines-child-host";
 const humanRequestSchema = v.strictObject({
     discussion: v.optional(v.boolean()),
@@ -10,13 +13,13 @@ const humanRequestSchema = v.strictObject({
     choices: v.optional(v.array(v.string())),
     suggestions: v.optional(v.array(v.string())),
 });
+const agentIdentity = {
+    harness: v.string(),
+    model: v.optional(v.string()),
+    thinking: v.optional(v.string()),
+};
 const agentUpdateSchema = v.variant("type", [
-    v.strictObject({
-        type: v.literal("identity"),
-        harness: v.string(),
-        model: v.optional(v.string()),
-        thinking: v.optional(v.string()),
-    }),
+    v.strictObject({ type: v.literal("identity"), ...agentIdentity }),
     v.strictObject({
         type: v.literal("output"),
         text: v.string(),
@@ -48,6 +51,10 @@ const parentMessageSchema = v.variant("type", [
         agents: v.optional(v.record(v.string(), v.string())),
         cwd: v.string(),
         home: v.optional(v.string()),
+        // Present while run status is published, by the host or by its caller, under this id.
+        runId: v.optional(v.string()),
+        // The host publishes the record itself and needs each change to it.
+        reportStatus: v.optional(v.boolean()),
     }),
     v.strictObject({
         type: v.literal("ask"),
@@ -70,6 +77,15 @@ const childMessageSchema = v.variant("type", [
     }),
     v.strictObject({ type: v.literal("state"), state: stateValueSchema }),
     v.strictObject({ type: v.literal("agentUpdate"), update: agentUpdateSchema }),
+    v.strictObject({
+        type: v.literal("status"),
+        // A change to the published record. Null clears a field: IPC drops a key that holds undefined.
+        change: v.strictObject({
+            state: v.optional(stateValueSchema),
+            agent: v.optional(v.nullable(v.object(agentIdentity))),
+            limit: v.optional(v.nullable(v.strictObject({ text: v.string(), until: v.optional(v.string()) }))),
+        }),
+    }),
     v.strictObject({
         type: v.literal("humanRequest"),
         requestId: v.string(),
@@ -94,6 +110,18 @@ export function startMachineHost(options) {
         }
     }
     const cwd = options.cwd ?? process.cwd();
+    // Run status is published here, by the host, and not by the hosted child.
+    // Only the host sees every ending: it stops the child with SIGKILL, and a
+    // child that crashed cannot record its own death. The record therefore
+    // carries this process's pid. While the host lives it settles the record
+    // itself; when the host dies the child stops with it (see "disconnect"
+    // below), so a reader that finds the pid gone rightly shows the run as lost.
+    const id = randomUUID();
+    const publication = runStatusDirectory() !== undefined;
+    // An embedding program has to ask: its environment alone must not make its runs appear elsewhere.
+    const publishes = publication && options.publishRunStatus === true;
+    const recorded = publishes || (publication && options.publishRunStatus === "caller");
+    let published;
     const child = fork(fileURLToPath(import.meta.url), [childArgument], {
         cwd,
         execArgv: [],
@@ -135,6 +163,7 @@ export function startMachineHost(options) {
             const wasStarting = phase === "starting";
             phase = "failed";
             pendingHuman = undefined;
+            published?.finish({ error: error.message });
             rejectResult(error);
             if (wasStarting)
                 rejectStarted(error);
@@ -158,7 +187,20 @@ export function startMachineHost(options) {
                     return;
                 }
                 phase = "running";
+                if (publishes) {
+                    published = createRunStatusPublisher({
+                        id,
+                        machine: message.name,
+                        path: message.path,
+                        cwd: resolvePath(cwd),
+                        ...(options.label === undefined ? {} : { label: options.label }),
+                        ...(options.owner === undefined ? {} : { owner: options.owner }),
+                        // Responses reach this run through `respond` and `ask` below, never through an inbox.
+                        answeredBy: "host",
+                    });
+                }
                 resolveStarted({
+                    id,
                     name: message.name,
                     description: message.description,
                     path: message.path,
@@ -177,6 +219,7 @@ export function startMachineHost(options) {
                         }
                         // Claim before yielding: no second caller can send this request again.
                         pendingHuman = undefined;
+                        published?.update({ status: "running", human: undefined });
                         try {
                             await sendChild(child, { type: "respond", requestId, response });
                         }
@@ -195,6 +238,7 @@ export function startMachineHost(options) {
                             throw new Error("Question must contain 1–8000 characters");
                         }
                         pendingHuman = undefined;
+                        published?.update({ status: "running", human: undefined });
                         try {
                             await sendChild(child, { type: "ask", requestId, question });
                         }
@@ -218,6 +262,14 @@ export function startMachineHost(options) {
             else if (message.type === "agentUpdate") {
                 observe(() => options.onAgentUpdate?.(message.update));
             }
+            else if (message.type === "status") {
+                const { state, agent, limit } = message.change;
+                published?.update({
+                    ...(state === undefined ? {} : { state: state }),
+                    ...(agent === undefined ? {} : { agent: agent ?? undefined }),
+                    ...(limit === undefined ? {} : { limit: limit ?? undefined }),
+                });
+            }
             else if (message.type === "humanRequest") {
                 if (phase !== "running" || pendingHuman !== undefined) {
                     fail(new Error("Machine host sent an unexpected Human request"));
@@ -227,6 +279,8 @@ export function startMachineHost(options) {
                     requestId: message.requestId,
                     request: message.request,
                 };
+                // Published without its request id, which only this host can use.
+                published?.update({ status: "waiting", human: message.request });
                 observe(() => options.onHumanRequest?.({ ...message.request, requestId: message.requestId }));
             }
             else if (message.type === "completed") {
@@ -236,6 +290,7 @@ export function startMachineHost(options) {
                 }
                 phase = "completed";
                 pendingHuman = undefined;
+                published?.finish({ state: message.state });
                 dispose();
                 resolveResult({
                     state: message.state,
@@ -268,6 +323,9 @@ export function startMachineHost(options) {
                 ...(options.input === undefined ? {} : { input: options.input }),
                 ...(options.agents === undefined ? {} : { agents: options.agents }),
                 ...(options.home === undefined ? {} : { home: options.home }),
+                // A caller that publishes the record itself still publishes it under this id.
+                ...(recorded ? { runId: id } : {}),
+                ...(publishes ? { reportStatus: true } : {}),
             };
             void sendChild(child, launch).catch((cause) => fail(asError(cause)));
         });
@@ -335,7 +393,8 @@ function runChildHost() {
     });
     async function launch(message) {
         try {
-            const prepared = await prepareMachineRun(message);
+            const { runId, reportStatus, ...launched } = message;
+            const prepared = await prepareMachineRun(launched);
             send({
                 type: "started",
                 name: prepared.name,
@@ -343,9 +402,28 @@ function runChildHost() {
                 path: prepared.path,
                 agentRoles: prepared.agentRoles,
             });
+            // Machines started by this run's Operations and Agents are its sub-runs.
+            if (runId !== undefined)
+                process.env.MACHINES_RUN_PARENT = runId;
+            // Only this process can tell which state an Agent identity belongs to, so
+            // it works out each change to the record and the host publishes it.
+            const observed = reportStatus !== true ? undefined : runStatusObserver((change) => send({
+                type: "status",
+                change: {
+                    ...(change.state === undefined ? {} : { state: change.state }),
+                    ...("agent" in change ? { agent: change.agent ?? null } : {}),
+                    ...("limit" in change ? { limit: change.limit ?? null } : {}),
+                },
+            }));
             const result = await prepared.start({
-                onAgentUpdate: (update) => send({ type: "agentUpdate", update }),
-                onState: (state) => send({ type: "state", state }),
+                onAgentUpdate(update) {
+                    send({ type: "agentUpdate", update });
+                    observed?.onAgentUpdate(update);
+                },
+                onState(state) {
+                    send({ type: "state", state });
+                    observed?.onState(state);
+                },
                 human: (request) => new Promise((resolve) => {
                     if (pendingHuman !== undefined) {
                         throw new Error("Machine host cannot wait for two Human responses at once");

package/dist/src/run-inbox.js

@@ -20,6 +20,10 @@ export async function respondToRun(options) {
     const record = published();
     if (record === undefined)
         throw new Error(`Machine run "${runId}" is not published in ${directory}`);
+    // Such a run reads no inbox: a response left there would only look delivered.
+    if (record.answeredBy === "host") {
+        throw new Error(`Machine run "${runId}" is answered through the program hosting it, not by machine respond: answer it there`);
+    }
     const request = pendingRequest(record);
     if (request === undefined)
         throw new Error(`Machine run "${runId}" is not waiting for Human input`);

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

@@ -1,4 +1,5 @@
 import type { StateValue } from "xstate";
+import type { AgentUpdate } from "./index.ts";
 /** One published run, stored as `<MACHINES_RUN_STATUS_DIR>/<id>.json`. */
 export interface RunStatusRecord {
     /** Version 1 records carry only `human.prompt`. */
@@ -21,6 +22,11 @@ export interface RunStatusRecord {
     /** Present while the current Agent state waits for a usage limit to reset; `status` stays `running`. */
     readonly limit?: RunStatusLimit;
     readonly human?: RunStatusHuman;
+    /**
+     * `host` when the program hosting the run answers its Human requests itself:
+     * the run has no inbox, and `machine respond` refuses it. Absent otherwise.
+     */
+    readonly answeredBy?: "host";
     /** Names the inbox responses the run took lately, so that each sender can tell; never a response. */
     readonly deliveries?: readonly string[];
     readonly error?: string;
@@ -52,6 +58,11 @@ export interface RunStatusRun {
     readonly path: string;
     readonly cwd: string;
     readonly startedAt?: string;
+    /** Replaces the owner the environment names; an empty one publishes the run unowned. */
+    readonly owner?: string;
+    /** Replaces `MACHINES_RUN_LABEL`, and is shortened as it is. */
+    readonly label?: string;
+    readonly answeredBy?: "host";
 }
 /** A present key replaces its field; a present key holding `undefined` clears it. */
 export interface RunStatusChange {
@@ -90,6 +101,19 @@ export declare function runDeliveryPath(directory: string, id: string, delivery:
  * throws, and it records neither Machine input nor output.
  */
 export declare function createRunStatusPublisher(run: RunStatusRun, environment?: NodeJS.ProcessEnv): RunStatusPublisher;
+/**
+ * Turns what a run reports as it executes into the changes to its record, for
+ * `machine run` and for a hosted run alike.
+ */
+export declare function runStatusObserver(update: (change: RunStatusChange) => void): {
+    onAgentUpdate(update: AgentUpdate): void;
+    onState(state: StateValue): void;
+};
+/**
+ * The session a process belongs to: the owner of the runs it starts, and the
+ * session whose watch list `machine watch` changes.
+ */
+export declare function runSessionId(environment?: NodeJS.ProcessEnv): string | undefined;
 /** Returns the valid records in a directory. Unreadable or malformed files are skipped. */
 export declare function readRunStatuses(directory: string): RunStatusRecord[];
 /** The id becomes a file name, so it must not be able to leave the directory. */

package/dist/src/run-status.js

@@ -32,9 +32,9 @@ export function createRunStatusPublisher(run, environment = process.env) {
     const id = run.id ?? randomUUID();
     if (directory === undefined || !isFileSafeId(id))
         return disabled;
-    const owner = environment.MACHINES_RUN_OWNER || environment.CLAUDE_CODE_SESSION_ID || undefined;
+    const owner = (run.owner ?? runSessionId(environment)) || undefined;
     const parent = environment.MACHINES_RUN_PARENT || undefined;
-    const label = formatLabel(environment.MACHINES_RUN_LABEL);
+    const label = formatLabel(run.label ?? environment.MACHINES_RUN_LABEL);
     const startedAt = run.startedAt ?? new Date().toISOString();
     let status = "running";
     let state;
@@ -61,6 +61,7 @@ export function createRunStatusPublisher(run, environment = process.env) {
             ...(agent === undefined ? {} : { agent }),
             ...(limit === undefined ? {} : { limit }),
             ...(human === undefined ? {} : { human }),
+            ...(run.answeredBy === undefined ? {} : { answeredBy: run.answeredBy }),
             ...(deliveries.length === 0 ? {} : { deliveries: deliveries.map((delivery) => delivery.id) }),
             ...(error === undefined ? {} : { error }),
             startedAt,
@@ -142,6 +143,55 @@ export function createRunStatusPublisher(run, environment = process.env) {
         },
     };
 }
+/**
+ * Turns what a run reports as it executes into the changes to its record, for
+ * `machine run` and for a hosted run alike.
+ */
+export function runStatusObserver(update) {
+    let publishedState;
+    // A runner reports its identity as it starts. For a state entered by a
+    // transition that is before the state is announced, so an identity is held
+    // for the rest of the tick and published with the state it belongs to.
+    let arriving;
+    return {
+        onAgentUpdate(agent) {
+            if (agent.type === "identity") {
+                arriving = agent;
+                queueMicrotask(() => {
+                    if (arriving !== agent)
+                        return;
+                    arriving = undefined;
+                    update({ agent });
+                });
+            }
+            else if (agent.type === "limit" && agent.status !== "swapped") {
+                // A swap while every preset is being tried again leaves the wait as it is published.
+                update({
+                    limit: agent.status === "resumed"
+                        ? undefined
+                        : { text: agent.text, ...(agent.until === undefined ? {} : { until: agent.until }) },
+                });
+            }
+        },
+        onState(state) {
+            const entered = formatState(state);
+            if (entered === publishedState)
+                update({ state });
+            else {
+                update({ state, agent: arriving });
+                arriving = undefined;
+            }
+            publishedState = entered;
+        },
+    };
+}
+/**
+ * The session a process belongs to: the owner of the runs it starts, and the
+ * session whose watch list `machine watch` changes.
+ */
+export function runSessionId(environment = process.env) {
+    return environment.MACHINES_RUN_OWNER || environment.CLAUDE_CODE_SESSION_ID || undefined;
+}
 /** Returns the valid records in a directory. Unreadable or malformed files are skipped. */
 export function readRunStatuses(directory) {
     return readRecordFiles(directory).map(({ record }) => record);
@@ -220,6 +270,7 @@ function isRunStatusRecord(value) {
             && (human.discussion === undefined || typeof human.discussion === "boolean")))
         && (limit === undefined || (limit !== null && typeof limit === "object" && typeof limit.text === "string"
             && isOptionalString(limit.until)))
+        && (record.answeredBy === undefined || record.answeredBy === "host")
         && isOptionalStrings(record.deliveries)
         && isOptionalString(record.error)
         && isTimestamp(record.startedAt)

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

@@ -0,0 +1,24 @@
+import { type RunStatusRecord } from "./run-status.ts";
+/**
+ * One thing a session asked to see on its status line besides its own runs:
+ * runs named by the start of their id or label, or runs working in a directory.
+ */
+export type RunWatch = {
+    readonly text: string;
+} | {
+    readonly dir: string;
+};
+/**
+ * A session's watch list, kept beside the records under a name their readers
+ * skip. `claude/statusline.mjs` reads the same file without loading this module.
+ */
+export declare function runWatchPath(directory: string, sessionId: string): string;
+/** What a session watches. A missing, unreadable, or malformed list watches nothing. */
+export declare function readRunWatches(directory: string, sessionId: string): RunWatch[];
+/** 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;
+/** 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

@@ -0,0 +1,112 @@
+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;
+let temporaryFiles = 0;
+/**
+ * A session's watch list, kept beside the records under a name their readers
+ * skip. `claude/statusline.mjs` reads the same file without loading this module.
+ */
+export function runWatchPath(directory, sessionId) {
+    if (!isFileSafeId(sessionId)) {
+        throw new Error(`Session id "${sessionId}" cannot name a watch list: use only letters, digits, ".", "_", and "-"`);
+    }
+    return join(directory, `.watch.${sessionId}.json`);
+}
+/** What a session watches. A missing, unreadable, or malformed list watches nothing. */
+export function readRunWatches(directory, sessionId) {
+    try {
+        const list = JSON.parse(readFileSync(runWatchPath(directory, sessionId), "utf8"));
+        const watches = list?.watches;
+        return Array.isArray(watches) ? watches.flatMap((watch) => pickWatch(watch) ?? []) : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Replaces a session's watch list; an empty one removes its file. */
+export function writeRunWatches(directory, sessionId, watches) {
+    const path = runWatchPath(directory, sessionId);
+    if (watches.length === 0) {
+        rmSync(path, { force: true });
+        return;
+    }
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    // Readers only ever see a whole list: write beside it, then rename over it.
+    const temporary = join(directory, `.watch.${sessionId}.${process.pid}.${temporaryFiles += 1}.tmp`);
+    try {
+        writeFileSync(temporary, `${JSON.stringify({ schemaVersion: 1, watches })}\n`, { mode: 0o600 });
+        renameSync(temporary, path);
+    }
+    catch (cause) {
+        rmSync(temporary, { force: true });
+        throw cause;
+    }
+    try {
+        pruneRunWatches(directory, path);
+    }
+    catch {
+        // Pruning is best effort.
+    }
+}
+/** Whether a watch names a run. A sub-run is never watched: it is its parent's detail. */
+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 (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);
+}
+/** Checks and normalizes what `machine watch` was given. */
+export function runWatch(input) {
+    if ("dir" in input) {
+        if (input.dir === "")
+            throw new Error("Expected a directory after --dir");
+        return { dir: resolve(input.dir) };
+    }
+    const text = input.text.trim();
+    if (text === "")
+        throw new Error("Expected the start of a run id or label to watch");
+    // Checked before the ends are trimmed: a line break there is still a second line.
+    if (/[\r\n]/u.test(input.text))
+        throw new Error("A watch is one line: the start of a run id or label");
+    return { text };
+}
+export function sameRunWatch(left, right) {
+    return "dir" in left ? "dir" in right && left.dir === right.dir : "text" in right && left.text === right.text;
+}
+function pickWatch(value) {
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const { text, dir } = value;
+    if (typeof text === "string" && text !== "" && dir === undefined)
+        return { text };
+    if (typeof dir === "string" && isAbsolute(dir) && text === undefined)
+        return { dir: resolve(dir) };
+    return undefined;
+}
+/** Sessions end without saying so; a list nobody has changed for a month belongs to one that did. */
+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)
+            continue;
+        try {
+            if (now - statSync(file).mtimeMs > forgottenAfterMilliseconds)
+                rmSync(file, { force: true });
+        }
+        catch {
+            // Another session may have pruned it first.
+        }
+    }
+}

package/dist/src/session.d.ts

@@ -1,6 +1,6 @@
 import type { StateValue } from "xstate";
 import type { JsonValue } from "./json.ts";
-import { type HostedHumanRequest } from "./host.ts";
+import { type HostedHumanRequest, type MachineHostOptions } from "./host.ts";
 import type { AgentUpdate } from "./index.ts";
 import type { PrepareMachineRunOptions } from "./launcher.ts";
 export type RunStatus = "running" | "waiting" | "completed" | "failed";
@@ -35,7 +35,7 @@ export interface SessionEvent {
 export declare class MachineSession {
     #private;
     subscribe(listener: (event: SessionEvent) => void): () => void;
-    start(options: PrepareMachineRunOptions): Promise<RunSnapshot>;
+    start(options: PrepareMachineRunOptions & Pick<MachineHostOptions, "label" | "owner" | "publishRunStatus">): Promise<RunSnapshot>;
     status(runId?: string): RunSnapshot[];
     respond(input: {
         readonly runId: string;

package/dist/src/session.js

@@ -1,4 +1,3 @@
-import { randomUUID } from "node:crypto";
 import { startMachineHost } from "./host.js";
 /** Owns runs from startup to disposal. Presentation belongs to its subscribers. */
 export class MachineSession {
@@ -15,10 +14,11 @@ export class MachineSession {
             throw new Error("Machine session is closed");
         const cancellation = new AbortController();
         this.#starting.add(cancellation);
-        const id = randomUUID();
         const startedAt = Date.now();
+        // The run is known by its host's id, which is also the id of its published run status.
+        let started;
         const update = (type, change) => {
-            const run = this.#runs.get(id);
+            const run = started === undefined ? undefined : this.#runs.get(started.id);
             if (run === undefined || !isActive(run.status))
                 return;
             change(run);
@@ -63,14 +63,15 @@ export class MachineSession {
             throw new Error("Machine session is closed");
         }
         const run = {
-            id,
+            id: host.id,
             cwd: options.cwd ?? process.cwd(),
             host,
             startedAt,
             updatedAt: Date.now(),
             status: "running",
         };
-        this.#runs.set(id, run);
+        started = run;
+        this.#runs.set(run.id, run);
         void host.result.then((result) => this.#finish(run, result), (cause) => this.#finish(run, { error: errorMessage(cause) }));
         this.#emit("updated", run);
         return snapshot(run);

package/docs/architecture.md

@@ -59,7 +59,7 @@ MCP server ────┘       ↑
 | `src/discovery.ts` | Project/global definition locations and precedence |
 | `src/launcher.ts` | Definition metadata, Agent bindings, preflight, single-use launch preparation |
 | `src/discovery-worker.ts` | Fresh metadata imports in disposable workers |
-| `src/host.ts` | One child run, IPC, Human request identity, owned process termination |
+| `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/cli.ts` | Command parsing, terminal progress, source inspection |
 | `pi-extension/index.ts` | Pi tools, widgets, notifications, native input presentation |
@@ -107,9 +107,14 @@ response from either the terminal or a private per-run inbox file written by
 session `respond` path as its tool, and inbox questions through the session's
 `ask`. The inbox is a second way to deliver a response to the owning run, not a
 second owner: the run still validates the request ID and choices, and a response
-to any other request is discarded. See
+to any other request is discarded. A run hosted directly through
+`startMachineHost` publishes its status only when its host asks, and without an inbox: its host remains the
+only way to answer it, its record says so, and `machine respond` refuses it. See
 [Integrations](integrations.md#answering-a-waiting-run-from-outside).
 
+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.
+
 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;
@@ -167,8 +172,9 @@ Their phase ordering and manual proof gates describe past work.
 
 ## External execution owners
 
-The supported `@dna113p/machines/host` export exposes `startMachineHost`, its
-observations, correlated Human responses, termination, and final state/output.
+The supported `@dna113p/machines/host` export exposes `startMachineHost`, the
+run's id, its observations, correlated Human responses, termination, and final
+state/output.
 External applications can own hosted runs without importing private modules or
 parsing terminal output. Hosted input and optional output are JSON values.
 

package/docs/integrations.md

@@ -173,9 +173,9 @@ 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.
 
-`machine run` and the MCP server then keep one file per run,
-`<dir>/<runId>.json`, replaced atomically on each change (directory `0700`, file
-`0600`):
+`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`):
 
 ```json
 {
@@ -198,6 +198,30 @@ choice to publish that text. `machine run` exports its run id as
 `MACHINES_RUN_PARENT`, so a Machine started by one of its Operations or Agents
 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
+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:
+`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
+Operations and Agents, as `machine run` does. The host publishes, not the hosted
+process, so `pid` is the host's: a hosted process that is terminated or exits is
+recorded as `failed` with the reason, and a run whose host is gone shows as
+`lost`. The value `startMachineHost` resolves to carries the run's `id`, which
+is the id of its record; a session built on it, such as Pi's, reports that same
+id for the run, so it is the id to give `machine watch`.
+
+Such a record carries `"answeredBy": "host"`. Its Human requests are answered
+only through the host's own `respond` and `ask`: the run reads no inbox, its
+`human` has no `requestId`, and `machine respond` refuses it. The field is absent
+from every other record and did not exist in earlier version 2 records. A caller
+that publishes its own record for the run, as the MCP server does so that its
+runs keep their inbox, passes `publishRunStatus: "caller"`: the host then writes
+nothing, and the run still hands its id down to the runs it starts.
+
 While an Agent state waits for a [usage limit](authoring.md#usage-limits) to
 reset, the record stays `running` and carries the wait in `limit`:
 
@@ -253,13 +277,21 @@ whatever answers it.
 ```bash
 machine runs                 # running and waiting runs
 machine runs --json          # the same runs as their records
+machine runs --all           # every published run, also finished and lost ones still recorded
 machine respond <run-id> <request-id> <response>
 machine respond --question <run-id> <request-id> <text>
 ```
 
 `machine runs` prints each run's id, Machine, status, and state, and for a
-waiting run its prompt, request id, and choices (tab-separated when its output
-is not a terminal):
+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
+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
+`answered through its host` in place of a request id:
 
 ```text
 1a2b3c4d-…	release	waiting	approve
@@ -269,9 +301,9 @@ is not a terminal):
 ```
 
 `machine respond` checks the response against the current record before it
-delivers anything. It fails with a nonzero exit when the run is unknown, is not
-waiting, is waiting on a different request id, or restricts `choices` to values
-that do not include the response. `--question` sends a discussion question
+delivers anything. It fails with a nonzero exit when the run is unknown, is
+answered through its host, is not waiting, is waiting on a different request id,
+or restricts `choices` to values that do not include the response. `--question` sends a discussion question
 instead of an answer and is refused unless the request has `discussion: true`.
 Words after the request id are joined into one response; put `--` before a
 response that starts with a dash.
@@ -309,6 +341,8 @@ 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.
+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`
 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
@@ -350,13 +384,62 @@ prints one to three lines per run and nothing when there is nothing to show:
   Publish version 0.4.0?
 ```
 
-A session sees the runs it owns; runs without an owner appear in sessions whose
-project directory contains the run's working directory. Finished runs stay for
+A session sees the runs it owns and the runs it
+[watches](#watching-other-runs); runs without an owner also appear in sessions
+whose project directory contains the run's working directory. Finished runs stay for
 30 seconds. A run whose process disappeared without finishing is shown as `lost`
 for the same time, so the status line must run where it can see that process.
 Set `NO_COLOR` (to any value, even an empty one) for plain text and `COLUMNS`
 to change the 120-column truncation.
 
+### Watching other runs
+
+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.
+
+```bash
+machine runs                   # running and waiting runs, with their labels
+machine runs --all             # every published run, also finished and lost ones
+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 <text>` names every top-level run whose id starts with the
+  text, or whose label starts with it as a whole leading part: the label ends
+  there or goes on with something other than a letter, a digit, `-`, or `_`.
+  `org-9` matches the labels `org-9 → machines: …` and `org-9: …`, not
+  `org-90 …`. Matching is case-sensitive, and the text is one non-empty line.
+- `machine watch --dir <path>` names every top-level run whose working
+  directory is that path or inside it. The path is kept absolute.
+- An entry keeps matching runs that start later, so a ticket can be watched
+  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.
+
+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
+listed once however many entries name it, and at most five runs are shown.
+
+The list is one file per session beside the records,
+`<dir>/.watch.<session id>.json` (`0600`, replaced atomically), which the
+status line reads itself with the `session_id` Claude Code gives it:
+
+```json
+{ "schemaVersion": 1, "watches": [{ "text": "org-9" }, { "dir": "/work/other" }] }
+```
+
+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
+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.
+
 ## Troubleshooting
 
 For an isolated global catalog, set `MACHINES_USER_HOME` to an absolute directory;

package/package.json

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

package/skills/machine-delegation/SKILL.md

@@ -103,6 +103,11 @@ polling continuously. Interpret the current snapshot:
 Preserve existing user authorization when answering Human requests, and surface a
 new decision when the request requires one. A desire to finish is not an answer.
 
+To follow a run this session did not start, such as a ticket a daemon runs, use
+`machine watch <ticket-or-run-id>` where run status is published (`machine runs`
+lists what can be watched; `--all` adds runs that already ended). Watching only
+shows the run on this session's status line: it neither owns nor answers it.
+
 The CLI fallback is `machine run <name> [--agent role=preset] -- <input>` in the
 target workspace. It waits for completion and uses terminal Human input; retain
 the shell session if running it asynchronously. It does not return an MCP run ID.