@gavin-hu/my-pi-agent 0.20.0 → 0.22.0

package/extensions/job/clock.ts

@@ -0,0 +1,142 @@
+/**
+ * The job runtime's periodic work: the repaint clock, and the sweep that polls
+ * the jobs this session reattached.
+ *
+ * The clock is the only periodic hook the runtime arms. While a job runs it
+ * re-asserts the footer chip, touches this session's liveness marker, and lets
+ * the runtime poll the jobs it reattached; without it, anything that clears
+ * extension statuses (a session reload, another UI path) would hide a
+ * still-running job's chip until the next transition.
+ *
+ * Every fact it acts on is the caller's and arrives as a function: whether a job
+ * is running, whether the runtime was disposed, what a tick does, and what a
+ * repaint does. Nothing here holds state across calls — the armed timer lives in
+ * the returned closure, never at module scope, because Pi loads each extension
+ * with its own module cache.
+ *
+ * The sweep is here because it is the tick's work: a reattached job has no
+ * `close` event, so only a periodic pass can notice that its pid is gone.
+ */
+
+import { defaultInterval, type RepeatTimer } from "../../lib/timer.ts";
+import type { Job, JobRecord, JobStatus } from "./types.ts";
+
+export interface RepaintClockDeps {
+	/** The repaint interval, read when the clock is armed. */
+	repaintMs: () => number;
+	/** Whether any record is running, which is the only thing that keeps the clock armed. */
+	running: () => boolean;
+	/** Whether the runtime was shut down; a disposed runtime arms nothing. */
+	disposed: () => boolean;
+	/** Refresh this session's liveness marker. */
+	touchMarker: () => void;
+	/** One tick: the external poll and the chip re-assert. */
+	tick: () => void;
+	/** One repaint of the surface. */
+	repaint: () => void;
+	/** The repeating timer, injectable so a test ticks by hand instead of waiting. */
+	interval?: RepeatTimer;
+}
+
+export interface RepaintClock {
+	/** Arm the clock when a job is running and none is armed, and stop it when nothing is. */
+	ensure(): void;
+	/** Cancel a pending tick. */
+	stop(): void;
+	/** Ensure the clock, touch the marker, then repaint — unless the runtime is disposed. */
+	paint(): void;
+}
+
+export function createRepaintClock(deps: RepaintClockDeps): RepaintClock {
+	const interval = deps.interval ?? defaultInterval;
+	let cancel: (() => void) | undefined;
+
+	const stop = (): void => {
+		cancel?.();
+		cancel = undefined;
+	};
+
+	const ensure = (): void => {
+		if (deps.disposed() || !deps.running()) {
+			stop();
+			return;
+		}
+		if (cancel) return;
+		cancel = interval(deps.repaintMs(), () => deps.tick());
+	};
+
+	const paint = (): void => {
+		ensure();
+		deps.touchMarker();
+		if (deps.disposed()) return;
+		deps.repaint();
+	};
+
+	return { ensure, stop, paint };
+}
+
+/** What the sweep asks of the table; every decision it makes is answered there. */
+export interface ExternalSweepDeps {
+	/** Every record in the table. */
+	records: () => Iterable<Job>;
+	/** This session's id, so a peer's record is told from one's own. */
+	sessionId: () => string;
+	/**
+	 * Whether the session that owns a record is still here: `live` and `quiet` both count,
+	 * because a heartbeat only ticks while a job runs.
+	 */
+	ownerPresent: (sessionId: string) => boolean;
+	/** Whether a pid is still running. */
+	alive: (pid: number) => boolean;
+	/** Whether a persisted start-time token still matches the pid it names. */
+	owns: (job: JobRecord) => boolean;
+	/** Settle a record whose process is gone; false when it cannot be judged. */
+	settleGone: (job: Job) => boolean;
+	/** Move a record to a settled status, resolving its waiters. */
+	settle: (job: Job, patch: { status: JobStatus; signal?: string | null }) => void;
+	/** SIGTERM a pid. */
+	signal: (pid: number) => void;
+	/** Refresh this session's liveness marker. */
+	touchMarker: () => void;
+	/** Prune finished records, persist, and repaint, after something changed. */
+	changed: () => void;
+}
+
+/**
+ * Poll the reattached (unowned) jobs once: settle any whose pid is gone, and reap
+ * an abandoned non-detached process whose owner session is gone.
+ */
+export function createExternalSweep(deps: ExternalSweepDeps): () => void {
+	return () => {
+		deps.touchMarker();
+		let changed = false;
+		for (const job of deps.records()) {
+			if (job.status !== "running" || job.owned) continue;
+			const peer = job.sessionId !== deps.sessionId();
+			// A peer that is still here owns this job, a quiet one included: leave its state to
+			// that owner. The peer's id is asked however often the record says it is not ours.
+			if (peer && deps.ownerPresent(job.sessionId)) continue;
+			if (job.pid === null || !deps.alive(job.pid)) {
+				// A record with no pid cannot be judged gone; leave it alone rather than
+				// announcing on every tick.
+				if (!deps.settleGone(job)) continue;
+				changed = true;
+				continue;
+			}
+			// The owner is gone and the job is not detached: reap the abandoned
+			// process, guarding against pid reuse with the start token. A settle is the
+			// whole announcement, so the reap needs no second call of its own.
+			if (peer && !job.detached) {
+				if (deps.owns(job)) {
+					deps.signal(job.pid);
+					deps.settle(job, { status: "killed", signal: "SIGTERM" });
+				} else {
+					deps.settle(job, { status: "unknown" });
+				}
+				changed = true;
+			}
+		}
+		if (!changed) return;
+		deps.changed();
+	};
+}

package/extensions/job/commands.ts

@@ -6,10 +6,8 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { withPolledScreen } from "../../lib/screen-session.ts";
 import { formatJobList } from "./format.ts";
 import type { JobsRuntime } from "./runtime.ts";
-import { JobListComponent } from "./tui.ts";
 
 /** How often the open log pane re-reads the log file. */
 const LOG_POLL_MS = 500;
@@ -23,6 +21,10 @@ export function registerCommands(pi: ExtensionAPI, runtime: JobsRuntime): void {
 				return;
 			}
 
+			// The screen and the dock it mounts are the TUI's, not the listener's: the text
+			// listing above and registration load neither.
+			const { withPolledScreen } = await import("../../lib/screen-session.ts");
+			const { JobListComponent } = await import("./view/jobs-screen.ts");
 			await withPolledScreen(
 				pi,
 				ctx,

package/extensions/job/config.ts

@@ -27,7 +27,14 @@ export interface JobsConfig {
 	killGraceMs: number;
 	/** Status-chip refresh interval while jobs run. */
 	repaintMs: number;
-	/** How long a session heartbeat is trusted before its jobs are reaped. */
+	/**
+	 * How old a session's heartbeat may be before its pid is re-checked against the process
+	 * it named.
+	 *
+	 * The heartbeat only ticks while a job runs, so age alone means the session is idle, not
+	 * gone: a quiet session keeps its jobs. The token check is what catches a pid that has
+	 * since been reused by another program.
+	 */
 	sessionTtlMs: number;
 	/** Override for the registry directory; defaults under the agent dir. */
 	registryDir: string | undefined;

package/extensions/job/format.ts

@@ -16,7 +16,7 @@ import type { Theme } from "@earendil-works/pi-coding-agent";
 import { boundedTail, formatDuration, sanitizeUntrustedLine } from "../../lib/format.ts";
 import { clip, clipLabel, LABEL_WIDTH } from "../../lib/tui/columns.ts";
 import { GLYPHS, SEPARATORS } from "../../lib/tui/glyphs.ts";
-import { byRunningFirst } from "../../lib/tui/rows.ts";
+import { byRunningFirst, statusRow, type StatusRow } from "../../lib/tui/rows.ts";
 import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
 import type { JobRecord, JobStatus } from "./types.ts";
 
@@ -74,6 +74,27 @@ export function shortLabel(job: JobRecord): string {
 	return clipLabel(job.label || job.command);
 }
 
+/** One row for the `/jobs` screen and its transcript mirror: selection marker,
+ *  status glyph, id, label, and a right-aligned elapsed value, tagged `peer`
+ *  when another session owns it. `statusRow` owns the clipping and alignment. */
+export function jobRow(
+	job: JobRecord,
+	theme: Theme,
+	width: number,
+	options: Pick<StatusRow, "selected" | "marker"> & { foreign?: boolean } = {},
+): string {
+	const elapsed = formatDuration(elapsedMs(job, Date.now()));
+	return statusRow(theme, width, {
+		...options,
+		glyph: statusGlyphChar(job.status),
+		glyphRole: statusRole(job.status),
+		label: `${job.id}  ${shortLabel(job)}`,
+		labelRole: options.selected ? "accent" : "label",
+		// The tag rides the right-aligned cell, which survives a narrow terminal.
+		trailing: options.foreign ? `${elapsed}${SEPARATORS.item}peer` : elapsed,
+	});
+}
+
 /** One-line job summary shared by the model output and the `/jobs` screen. */
 function jobSummary(job: JobRecord, now: number, ownSessionId?: string): string {
 	const parts = [`${job.id}`, statusWord(job), formatDuration(elapsedMs(job, now))];

package/extensions/job/log-writer.ts

@@ -6,10 +6,14 @@
  * plumbing can be read separately. The writer owns no job state: every path and
  * limit is a callback over the runtime's live config, and a buffered line is
  * handed back through `onLine`.
+ *
+ * The line splitter is a seam rather than an import: `lib/lines.ts` is loaded with
+ * the process seam on the first job, so a session that never starts one never
+ * loads it.
  */
 
 import { createWriteStream, existsSync, renameSync, unlinkSync, type WriteStream } from "node:fs";
-import { LineSplitter } from "../../lib/lines.ts";
+import type { LineSplitter } from "../../lib/lines.ts";
 import type { Job, JobRecord } from "./types.ts";
 
 /** Bytes held while a rotation swaps the log stream before writes resume. */
@@ -36,6 +40,13 @@ export interface LogHandle {
 export interface LogWriterOptions {
 	/** The clock the repaint window is measured on. */
 	now(): number;
+	/**
+	 * A fresh line splitter for one job's stream.
+	 *
+	 * Injected rather than imported: the splitter is the only piece of `lib/lines.ts`
+	 * a writer needs, and a runtime that never starts a job must not load it.
+	 */
+	newSplitter(): LineSplitter;
 	/** The live segment for a job, or undefined when it cannot be used. */
 	logPath(job: JobRecord): string | undefined;
 	/** The rotated segment for a job, or undefined when it cannot be used. */
@@ -163,7 +174,7 @@ export function createLogWriter(options: LogWriterOptions): LogWriter {
 			stream?.on("error", () => {});
 			return {
 				stream,
-				lines: new LineSplitter(),
+				lines: options.newSplitter(),
 				queue: [],
 				queuedBytes: 0,
 				rotating: false,

package/extensions/job/registry.ts

@@ -22,6 +22,7 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { RosterState } from "../../lib/session-roster.ts";
 import { registryPathFor } from "./paths.ts";
 import { JOB_STATUSES, type JobRecord, type JobStatus, type RegistryFile } from "./types.ts";
 
@@ -203,6 +204,59 @@ export function settleGone(record: JobRecord, options: SettleGoneOptions): JobRe
 	return { ...record, status, exitCode: code, finishedAt: options.now };
 }
 
+/** What a load makes of every session's file, before the runtime touches a record. */
+export interface LoadedRecords {
+	/** Every record, merged across the session files and reconciled against liveness. */
+	records: JobRecord[];
+	/** Live, non-detached leftovers for the caller to kill. */
+	orphans: JobRecord[];
+	/** Sessions whose file may be dropped once their records are rewritten here. */
+	deadSessions: Set<string>;
+}
+
+/** The liveness and ownership seams a load reconciles against. */
+export interface LoadSeams {
+	/** This session, which adopts a dead one's records. */
+	sessionId: string;
+	/** What the session that wrote a file is now. */
+	ownerState: (sessionId: string) => RosterState;
+	/** The process seams: whether a pid runs, whether its token still matches, its exit code. */
+	process: {
+		alive: (pid: number) => boolean;
+		owns: (record: JobRecord) => boolean;
+		exitCode: (record: JobRecord) => number | undefined;
+	};
+	now: number;
+}
+
+/** Merge every session's file, recover dead pids, and classify the survivors. */
+export function loadRecords(files: readonly RegistryFile[], seams: LoadSeams): LoadedRecords {
+	const merged = new Map<string, JobRecord>();
+	const deadSessions = new Set<string>();
+	for (const file of files) {
+		if (file.sessionId !== seams.sessionId && seams.ownerState(file.sessionId) === "gone")
+			deadSessions.add(file.sessionId);
+		for (const record of file.jobs) {
+			const existing = merged.get(record.id);
+			merged.set(record.id, existing ? mergeRecords(existing, record, seams.sessionId) : record);
+		}
+	}
+	// Resolve dead pids (recovering exit codes), then classify the survivors.
+	const settled = [...merged.values()].map((record) =>
+		settleGone(record, {
+			isAlive: seams.process.alive,
+			tokenMatches: seams.process.owns,
+			readExitCode: seams.process.exitCode,
+			now: seams.now,
+		}),
+	);
+	const { jobs, orphans } = planReconcile(settled, seams.process.alive, seams.now, {
+		ownerState: seams.ownerState,
+		currentSessionId: seams.sessionId,
+	});
+	return { records: jobs, orphans, deadSessions };
+}
+
 export interface ReconcileResult {
 	/** The records after liveness reconciliation. */
 	jobs: JobRecord[];
@@ -213,10 +267,12 @@ export interface ReconcileResult {
 /** Owner-liveness context for {@link planReconcile}. */
 export interface ReconcileOptions {
 	/**
-	 * Whether the session that started a job is still alive. A live owner means
-	 * another session owns the job, so it is left running rather than reaped.
+	 * What the session that started a job is: `live`, `quiet`, or `gone`.
+	 *
+	 * Only `gone` frees the job to be reaped. A `quiet` owner is an idle one — its
+	 * heartbeat stops while it has nothing running — and its job is still its own.
 	 */
-	isOwnerAlive?: (sessionId: string) => boolean;
+	ownerState?: (sessionId: string) => RosterState;
 	/** The reconciling session; its own leftovers are always reaped. */
 	currentSessionId?: string;
 }
@@ -250,12 +306,12 @@ export function planReconcile(
 			jobs.push(record);
 			continue;
 		}
-		// Another live session still owns this job: keep it running instead of
-		// reaping a peer's work.
+		// Another session still owns this job: keep it running instead of reaping a
+		// peer's work. Its owner is only `gone` when its process is.
 		if (
-			options.isOwnerAlive &&
+			options.ownerState &&
 			record.sessionId !== options.currentSessionId &&
-			options.isOwnerAlive(record.sessionId)
+			options.ownerState(record.sessionId) !== "gone"
 		) {
 			jobs.push(record);
 			continue;

package/extensions/job/render.ts

@@ -0,0 +1,34 @@
+/**
+ * The `JobResult` transcript block: the `job` tool's list-or-log-tail result.
+ *
+ * It maps the job vocabulary onto the shared `TailResult` kit, so the tool's
+ * `renderResult` stays a few lines and every row is drawn by `jobRow` in
+ * `format.ts`. The `/jobs` screen draws the same rows through the same helper,
+ * which is why it lives beside the pure format helpers rather than here: this
+ * module is on the registration path, and the screen is not.
+ */
+
+import type { TailResultInput } from "../../lib/tui/tool.ts";
+import { jobRow } from "./format.ts";
+import type { JobRecord } from "./types.ts";
+
+/** Input for the transcript result: a themed job list or a log tail. */
+export type JobResultInput =
+	| { kind: "list"; jobs: JobRecord[]; more: number; sessionId?: string }
+	| { kind: "logs"; lines: string[]; earlier: number };
+
+/** Map the job vocabulary onto the shared transcript tail block. */
+export function jobTail(input: JobResultInput): TailResultInput<JobRecord> {
+	if (input.kind === "logs") {
+		return { kind: "lines", lines: input.lines, earlier: input.earlier, earlierLabel: "lines" };
+	}
+	return {
+		kind: "list",
+		rows: input.jobs,
+		more: input.more,
+		rowLine: (job, width, theme) => {
+			const foreign = input.sessionId !== undefined && job.sessionId !== input.sessionId;
+			return jobRow(job, theme, width, { marker: false, foreign });
+		},
+	};
+}