@yaag/extension 0.6.1 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/extension",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "publishConfig": {
     "access": "public"
   },
@@ -24,9 +24,9 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/cli": "0.6.1",
-    "@yaag/runtime": "0.6.1",
-    "@yaag/tui": "0.6.1",
+    "@yaag/cli": "0.6.2",
+    "@yaag/runtime": "0.6.2",
+    "@yaag/tui": "0.6.2",
     "nanoid": "^6.0.1"
   },
   "peerDependencies": {

package/src/record/run-registry.ts

@@ -1,8 +1,9 @@
-import type { EndedRunSummary, RunSummary } from "@yaag/runtime";
+import type { RunSummary, RunOutcome as SummaryOutcome } from "@yaag/runtime";
 import type { ProcessIdentity, RunOutcome } from "../process/index.ts";
 import { pickInlineResumeSource } from "./resume-source.ts";
 import { type RunLaunch, type RunRecord, startedRecord } from "./run-record.ts";
 import { restoreRecords } from "./run-restore.ts";
+import { failedSummary, settledRecord } from "./run-settle-record.ts";
 import type { RunStore } from "./run-store.ts";
 
 export type { RunLaunch } from "./run-record.ts";
@@ -148,8 +149,30 @@ export class RunRegistry {
   }
 
   /**
-   * `restoreRecords` already settled every stale `live` record, so this check
-   * can never adopt a Run as live (ADR-0036).
+   * Persists the settled form of a Run read back from disk, and refreshes the
+   * retained entry so the next snapshot of this session shows the verdict.
+   *
+   * Only a `restored` Run settles here: a live Run settles through its own
+   * outcome, and a finished Run is history (ADR-0036), so either is refused
+   * rather than written over. A Run this session never listed stays unlisted —
+   * it is written, but not adopted.
+   */
+  async settleRestored(record: RunRecord, outcome: SummaryOutcome): Promise<RestoredRun> {
+    const known = this.#runs.get(record.id);
+    if (known !== undefined && known.state !== "restored")
+      throw new Error(`RunRegistry: Run ${record.id} is ${known.state}, not a restored Run`);
+    const settled = settledRecord({ record, outcome, now: this.#now() });
+    this.#records.set(settled.id, settled);
+    if (known !== undefined)
+      this.#runs.set(settled.id, { state: "restored", run: restored(settled) });
+    await this.#store?.save(settled);
+    return restored(settled);
+  }
+
+  /**
+   * `restoreRecords` already settled every stale `live` record, and every
+   * `orphaned` record whose process is gone, so this check can never adopt a
+   * Run as live (ADR-0036).
    */
   #adoptable(record: RunRecord): boolean {
     if (record.state === "orphaned" || record.state === "interrupted") return true;
@@ -228,7 +251,10 @@ export class RunRegistry {
   reject(id: string, reason: unknown): void {
     const record = this.#runs.get(id);
     if (record === undefined || record.state !== "live") return;
-    this.#settle(id, failedSummary(record.run.summary), { kind: "rejected", reason });
+    this.#settle(id, failedSummary(record.run.summary, this.#now().getTime()), {
+      kind: "rejected",
+      reason,
+    });
   }
 
   /**
@@ -310,9 +336,3 @@ function persistedOutcome(outcome: RunSettlement): RunRecord["outcome"] {
 function errorMessage(reason: unknown): string {
   return reason instanceof Error ? reason.message : String(reason);
 }
-
-function failedSummary(summary: RunSummary): EndedRunSummary {
-  if (summary.runState === "ended")
-    return summary.ok ? { ...summary, outcome: "failed", ok: false } : summary;
-  return { ...summary, runState: "ended", outcome: "failed", ok: false, endedAt: null };
-}

package/src/record/run-restore.ts

@@ -1,5 +1,6 @@
 import { isProcessAlive, type ProcessIdentity } from "../process/index.ts";
 import type { RunRecord } from "./run-record.ts";
+import { settledRecord } from "./run-settle-record.ts";
 import type { RunStore } from "./run-store.ts";
 
 /** Decides whether the process a record names is still running. */
@@ -19,6 +20,11 @@ export interface RestoreOptions {
  * gone: its child is dead and the Run is `interrupted`, or its child still runs
  * without an owner and the Run is `orphaned`. Both re-writes are persisted, so
  * the verdict survives this session too (ticket 02).
+ *
+ * An `orphaned` record is probed again: its child can have ended since the
+ * session that orphaned it, and a dead one settles to `interrupted` with an end
+ * instant and an ended Summary. An orphan that still runs is left as it is, so
+ * a session start does not rewrite every record.
  */
 export async function restoreRecords(options: RestoreOptions): Promise<readonly RunRecord[]> {
   const isAlive = options.isAlive ?? isProcessAlive;
@@ -33,11 +39,12 @@ async function settleStale(
   now: () => Date,
   store: RunStore,
 ): Promise<RunRecord> {
-  if (record.state !== "live") return record;
+  if (record.state !== "live" && record.state !== "orphaned") return record;
   const alive = record.process !== null && isAlive(record.process);
+  if (alive && record.state === "orphaned") return record;
   const settled: RunRecord = alive
     ? { ...record, state: "orphaned" }
-    : { ...record, state: "interrupted", endedAt: now().toISOString() };
+    : settledRecord({ record, outcome: "interrupted", now: now() });
   await store.save(settled);
   return settled;
 }

package/src/record/run-settle-record.ts

@@ -0,0 +1,67 @@
+import type { EndedRunSummary, RunOutcome, RunSummary } from "@yaag/runtime";
+import type { RunRecord } from "./run-record.ts";
+
+/**
+ * Marks a folded Summary ended, keeping every accounting fact it holds.
+ *
+ * An already-ended fold is history and is returned unchanged: a Run keeps the
+ * first outcome observed for it, the invariant the registry keeps when it
+ * retains a settlement. `endedAt` stays null because it is the `run_end.at`
+ * event fact and no such event was seen.
+ */
+export function endedSummary(
+  summary: RunSummary,
+  outcome: RunOutcome,
+  endedAtMs: number,
+): EndedRunSummary {
+  if (summary.runState === "ended") return summary;
+  return {
+    ...summary,
+    runState: "ended",
+    outcome,
+    ok: outcome === "completed",
+    endedAt: null,
+    durationMs: durationOf(summary, endedAtMs),
+  };
+}
+
+/**
+ * The fold never synthesizes a duration from a clock (architecture §8), so the
+ * wall-clock value is supplied here, once, by the caller that settles the Run.
+ * Without it a settled Run reads `0s` instead of how long it really ran.
+ */
+function durationOf(summary: RunSummary, endedAtMs: number): number {
+  if (summary.durationMs !== 0) return summary.durationMs;
+  if (summary.startedAt === null) return 0;
+  return Math.max(0, endedAtMs - summary.startedAt);
+}
+
+/** Marks a fold ended as failed, for a Run whose child rejected. */
+export function failedSummary(summary: RunSummary, endedAtMs: number): EndedRunSummary {
+  if (summary.runState === "ended")
+    return summary.ok ? { ...summary, outcome: "failed", ok: false } : summary;
+  return endedSummary(summary, "failed", endedAtMs);
+}
+
+/**
+ * The settled form of a record no process is attached to any more.
+ *
+ * The persisted state is `interrupted`: no new state member is added, so an
+ * older yaag still reads the record. The verdict lives in the Summary fold —
+ * `stopped` when yaag_stop killed the group, `interrupted` when the process was
+ * already gone. The persisted outcome stays null, because the Run gave no exit
+ * code and no rejection reason.
+ */
+export function settledRecord(options: {
+  readonly record: RunRecord;
+  readonly outcome: RunOutcome;
+  readonly now: Date;
+}): RunRecord {
+  const { record, outcome, now } = options;
+  return {
+    ...record,
+    state: "interrupted",
+    endedAt: now.toISOString(),
+    summary: endedSummary(record.summary, outcome, now.getTime()),
+  };
+}

package/src/tool/stop-tool.ts

@@ -1,7 +1,7 @@
 import type { AgentToolResult, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { RunSummary } from "@yaag/runtime";
 import { Type } from "typebox";
-import { isProcessAlive } from "../process/index.ts";
+import { isProcessAlive, type ProcessIdentity } from "../process/index.ts";
 import type { RestoredRun, RunRegistry } from "../record/index.ts";
 import { toUsage } from "../view/index.ts";
 
@@ -21,9 +21,22 @@ const DESCRIPTION = [
   "it spent before it stopped.",
   "",
   "An orphaned Run left behind by an earlier Host Session is stopped too: its",
-  "process group is killed, and the report holds its last persisted Summary.",
+  "process group is killed, its record is settled, and the report holds its last",
+  "persisted Summary. If its process already ended, the record is settled too and",
+  "the report says the Run was no longer running.",
 ].join("\n");
 
+/** Seams the tests replace, so no test kills a real process group. */
+export interface StopToolOptions {
+  readonly isAlive?: (identity: ProcessIdentity) => boolean;
+  readonly kill?: (pid: number) => void;
+}
+
+interface StopDeps {
+  readonly isAlive: (identity: ProcessIdentity) => boolean;
+  readonly kill: (pid: number) => void;
+}
+
 /** What a stopped Run got through and what it cost, from the fold (ADR-0006). */
 export function stopReport(id: string, summary: RunSummary): string {
   const agents = Object.keys(summary.agents).length;
@@ -71,18 +84,28 @@ function agentStateReport(agent: RunSummary["agents"][string]): string {
  * pipes belong to a dead Host Session — so the process group is killed outright
  * (ADR-0008). The pid is re-probed first, because a record can name a pid that
  * a different process has since inherited (ticket 02).
+ *
+ * The record is settled either way: a process that already ended is not an
+ * error, it only means the verdict is `interrupted` instead of `stopped`.
  */
-function stopOrphan(run: RestoredRun): AgentToolResult<StopDetails> {
+async function stopOrphan(
+  run: RestoredRun,
+  registry: RunRegistry,
+  deps: StopDeps,
+): Promise<AgentToolResult<StopDetails>> {
   const { record } = run;
   if (record.state !== "orphaned" || record.process === null)
     throw new Error(`yaag_stop: Run ${record.id} has already finished`);
-  if (!isProcessAlive(record.process))
-    throw new Error(`yaag_stop: Run ${record.id} is no longer running`);
-  killGroup(record.process.pid);
+  const alive = deps.isAlive(record.process);
+  if (alive) deps.kill(record.process.pid);
+  const settled = await registry.settleRestored(record, alive ? "stopped" : "interrupted");
+  const note = alive
+    ? ""
+    : `Run ${record.id} was no longer running; its record is settled as interrupted.\n`;
   return {
-    content: [{ type: "text", text: stopReport(record.id, record.summary) }],
-    details: { summary: record.summary },
-    usage: toUsage(record.summary),
+    content: [{ type: "text", text: `${note}${stopReport(record.id, settled.summary)}` }],
+    details: { summary: settled.summary },
+    usage: toUsage(settled.summary),
   };
 }
 
@@ -111,7 +134,12 @@ function toError(reason: unknown): Error {
  */
 export function createStopTool(
   registry: RunRegistry,
+  options: StopToolOptions = {},
 ): ToolDefinition<typeof parameters, StopDetails> {
+  const deps: StopDeps = {
+    isAlive: options.isAlive ?? isProcessAlive,
+    kill: options.kill ?? killGroup,
+  };
   return {
     name: "yaag_stop",
     label: "Stop Run",
@@ -123,7 +151,7 @@ export function createStopTool(
         case "unknown":
           throw new Error(`yaag_stop: no Run with id ${params.id}`);
         case "restored":
-          return stopOrphan(status.run);
+          return await stopOrphan(status.run, registry, deps);
         case "finished":
           throw new Error(`yaag_stop: Run ${params.id} has already finished`);
         case "live": {