pi-crew 0.10.6 → 0.11.0

package/src/extension/registration/command-registration.ts

@@ -2,16 +2,19 @@
  * Command registration installer for pi-crew.
  *
  * Single entry point that wires every `pi.registerCommand(...)` call
- * site in the extension. Today that means one heavy call:
+ * site in the extension. Today that means:
  *   • `registerTeamCommands` — registers every `/crew-*`, `/team-*`,
  *     `/teams`, and friends. The full set lives in
  *     `registration/commands.ts` (already extracted); this file is
  *     the orchestrator-level wrapper that calls it with the right deps.
+ *   • `registerSchedulesCommands` — the headless `/schedules` command
+ *     (Scheduled Jobs UI tier E; no deps beyond the ExtensionAPI).
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadConfig } from "../../config/config.ts";
 import { updatePiCrewPowerbar } from "../../ui/powerbar-publisher.ts";
 import { updateCrewWidget } from "../../ui/widget/index.ts";
+import { registerSchedulesCommands } from "./commands/schedules.ts";
 import { registerTeamCommands } from "./commands.ts";
 import type { RegistrationContext } from "./registration-types.ts";
 
@@ -56,4 +59,5 @@ export function registerPiCommands(pi: ExtensionAPI, ctx: RegistrationContext):
 			}
 		},
 	});
+	registerSchedulesCommands(pi);
 }

package/src/extension/registration/commands/schedules.ts

@@ -0,0 +1,212 @@
+/**
+ * `/schedules` command — Scheduled Jobs UI tier E (headless-compatible).
+ *
+ * Pattern: `registration/commands/status.ts` — `pi.registerCommand` with a
+ * handler whose ONLY output channel is `notifyCommandResult` (ctx.ui.notify
+ * text block, capped at 800 chars). No TUI dependency: works under `pi -p`.
+ *
+ * Single source of truth (G17): jobs are read through `getScheduledJobs()`
+ * from team-tool/handle-schedule.ts — never from a local defaults copy.
+ * Rendering reuses the SAME pane renderer as the dashboard (tier A) via
+ * `renderSchedulesTextBlock` → `renderSchedulesPane` — no copied table logic,
+ * no drift. Clock (D6-T4): `now` is injected into the render path; the single
+ * `new Date()` read lives here at the handler boundary, never in a renderer.
+ *
+ * `/schedules log <jobId-or-name>` resolves a job by id or name, takes its
+ * LATEST spawned run (`loadRunManifestById`), and tails the most recent
+ * output artifact (run summary + task result artifacts — the same candidate
+ * set as team-tool/run.ts) bounded to SCHEDULES_LOG_TAIL_BYTES via
+ * `readTextTail`, with every path resolved inside `artifactsRoot` through
+ * `resolveRealContainedPath` (H-3 traversal guard).
+ */
+import * as fs from "node:fs";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import { readTextTail } from "../../../runtime/agent-observability.ts";
+import type { ScheduledJob } from "../../../runtime/scheduling/scheduler.ts";
+import { loadRunManifestById } from "../../../state/stores/state-store.ts";
+import type { TeamRunManifest, TeamTaskState } from "../../../state/types.ts";
+import { renderSchedulesTextBlock } from "../../../ui/dashboard-panes/schedules-pane.ts";
+import { resolveRealContainedPath } from "../../../utils/safe-paths.ts";
+import { getCrewScheduler, getScheduledJobs, getScheduledJobsHiddenCountView } from "../../team-tool/handle-schedule.ts";
+import { notifyCommandResult } from "../command-utils.ts";
+
+/** Bounded tail for `/schedules log` — matches the dashboard's
+ *  read-agent-output cap (32_000 bytes, commands/shared.ts). */
+export const SCHEDULES_LOG_TAIL_BYTES = 32_000;
+
+export type ParsedSchedulesArgs = { mode: "list" } | { mode: "log"; target: string } | { mode: "usage"; error: string };
+
+/** Parse `/schedules` arguments: bare → list, `log <target>` → log tail
+ *  (target may contain spaces — job names do), anything else → usage error. */
+export function parseSchedulesArgs(args: string): ParsedSchedulesArgs {
+	const trimmed = args.trim();
+	if (trimmed === "") return { mode: "list" };
+	const tokens = trimmed.split(/\s+/);
+	if ((tokens[0] ?? "").toLowerCase() !== "log") {
+		return { mode: "usage", error: `Unknown subcommand '${tokens[0]}'. Usage: /schedules [log <jobId-or-name>]` };
+	}
+	const target = tokens.slice(1).join(" ").trim();
+	if (!target) return { mode: "usage", error: "Usage: /schedules log <jobId-or-name>" };
+	return { mode: "log", target };
+}
+
+/** Resolve a job by exact id first, then by (case-insensitive) name. When
+ *  several jobs share a name, the most recently created wins so `log` follows
+ *  the newest schedule (ISO timestamps sort lexicographically). */
+export function resolveScheduledJobByIdOrName(jobs: ScheduledJob[], target: string): ScheduledJob | undefined {
+	const needle = target.trim();
+	if (!needle) return undefined;
+	const byId = jobs.find((job) => job.id === needle);
+	if (byId) return byId;
+	const lower = needle.toLowerCase();
+	const byName = jobs.filter((job) => job.name.trim().toLowerCase() === lower);
+	if (byName.length === 0) return undefined;
+	return byName.reduce((newest, job) => (job.createdAt > newest.createdAt ? job : newest));
+}
+
+/**
+ * Build the `/schedules` text block. Thin wrapper over the shared text-block
+ * variant of the pane renderer — kept exported so the parity test can pin
+ * byte-for-byte equality against `renderSchedulesPane` (no drift). The
+ * optional `hiddenCount` (P2-1) flows straight through to the shared hint
+ * line; omitted/0 keeps the legacy layout.
+ */
+export function buildSchedulesCommandLines(jobs: ScheduledJob[], now: Date, hiddenCount = 0): string[] {
+	return renderSchedulesTextBlock(jobs, now, { hiddenCount });
+}
+
+/** Test seam for the run-manifest loader (defaults to the real state store). */
+export interface SchedulesLogDeps {
+	loadManifest?: typeof loadRunManifestById;
+}
+
+/**
+ * Build the `/schedules log <jobId-or-name>` text: resolve the job, take its
+ * latest spawned run, and tail the most recent output artifact. Pure-ish
+ * read-only helper (no clock, no mutation) so tests can drive every branch.
+ */
+export function buildSchedulesLogText(
+	cwd: string,
+	jobs: ScheduledJob[],
+	target: string,
+	deps: SchedulesLogDeps = {},
+): { isError: boolean; text: string } {
+	const job = resolveScheduledJobByIdOrName(jobs, target);
+	if (!job) return { isError: true, text: `No scheduled job with id or name '${target}'.` };
+	const runId = job.spawnedRunIds?.[job.spawnedRunIds.length - 1];
+	if (!runId) return { isError: true, text: `Job '${job.name}' has no spawned runs yet.` };
+	// Security review F-3: runId is a persisted settings field under only a
+	// weak shape guard; the state store's assertSafePathId THROWS on unsafe
+	// charsets (traversal containment — it fails closed). Catch it here and
+	// degrade to the run-not-found-style error toast instead of an unhandled
+	// rejection inside the command handler.
+	let loaded: ReturnType<typeof loadRunManifestById>;
+	try {
+		loaded = (deps.loadManifest ?? loadRunManifestById)(cwd, runId);
+	} catch {
+		return { isError: true, text: `Run '${runId}' is not a valid run id.` };
+	}
+	if (!loaded) return { isError: true, text: `Run '${runId}' not found (it may have been cleaned up).` };
+	const artifact = pickMostRecentOutputArtifact(loaded.manifest, loaded.tasks);
+	if (!artifact) return { isError: true, text: `Run '${runId}' has no output artifacts yet.` };
+	const tail = readTextTail(artifact.path, SCHEDULES_LOG_TAIL_BYTES);
+	const lines = [
+		`Scheduled job '${job.name}' — latest run ${runId}`,
+		`artifact: ${artifact.path} (${tail.bytes} bytes${tail.truncated ? `, showing last ${SCHEDULES_LOG_TAIL_BYTES}` : ""})`,
+		tail.text.trimEnd(),
+	];
+	return { isError: false, text: lines.join("\n") };
+}
+
+/**
+ * Most-recent output artifact of a run. Candidate set mirrors
+ * team-tool/run.ts:252-273 — the run-level summary artifact plus per-task
+ * result artifacts — each resolved inside `artifactsRoot` through
+ * `resolveRealContainedPath` (rejects absolute paths and `..` traversal);
+ * unresolvable/unreadable candidates are skipped, newest mtime wins.
+ */
+function pickMostRecentOutputArtifact(manifest: TeamRunManifest, tasks: TeamTaskState[]): { path: string; mtimeMs: number } | undefined {
+	const relPaths: string[] = [];
+	for (const artifact of manifest.artifacts ?? []) {
+		if (artifact?.kind === "summary" || artifact?.kind === "result" || artifact?.kind === "log") relPaths.push(artifact.path);
+	}
+	for (const task of tasks) {
+		if (task?.resultArtifact?.path) relPaths.push(task.resultArtifact.path);
+	}
+	let best: { path: string; mtimeMs: number } | undefined;
+	for (const rel of relPaths) {
+		try {
+			const resolved = resolveRealContainedPath(manifest.artifactsRoot, rel);
+			const mtimeMs = fs.statSync(resolved).mtimeMs;
+			if (!best || mtimeMs > best.mtimeMs) best = { path: resolved, mtimeMs };
+		} catch {
+			/* traversal-guarded or missing artifact — skip */
+		}
+	}
+	return best;
+}
+
+/** Error-level variant of notifyCommandResult (same 800-char bound). */
+async function notifySchedulesError(ctx: ExtensionCommandContext, text: string): Promise<void> {
+	ctx.ui.notify(text.length > 800 ? `${text.slice(0, 797)}...` : text, "error");
+}
+
+/** Tab-completion: `log` subcommand, then job ids (labeled by name). */
+function suggestSchedulesArgs(argumentPrefix: string): AutocompleteItem[] | null {
+	const prefix = argumentPrefix ?? "";
+	if (prefix === "" || prefix === "l" || prefix === "lo" || prefix === "log") {
+		return [{ value: "log", label: "log", description: "tail the latest run output of a job" }];
+	}
+	// Raw prefix (NOT trimmed) so `log ` (trailing space) means "suggest jobs".
+	const match = prefix.match(/^log\s+(\S*)$/i);
+	if (!match) return null;
+	const query = match[1] ?? "";
+	const items: AutocompleteItem[] = [];
+	// Review round 1 minor-3: autocomplete runs on EVERY keystroke. Gate on
+	// the registered scheduler (same discipline as the widget's default
+	// reader) so a missing scheduler can never fall back to the settings-store
+	// DISK read per keystroke — pre-registration simply suggests nothing.
+	const jobs = getCrewScheduler() ? getScheduledJobs(process.cwd()) : [];
+	for (const job of jobs) {
+		if (query && !job.id.startsWith(query) && !job.name.toLowerCase().includes(query.toLowerCase())) continue;
+		items.push({ value: `log ${job.id}`, label: job.name, description: `id ${job.id}` });
+		if (items.length >= 10) break;
+	}
+	return items.length > 0 ? items : null;
+}
+
+/** Register the `/schedules` command (see module doc). Headless-safe: the
+ *  handler touches only `ctx.cwd` and `ctx.ui.notify`. */
+export function registerSchedulesCommands(pi: ExtensionAPI): void {
+	pi.registerCommand("schedules", {
+		description: "List scheduled jobs (/schedules log <jobId-or-name> tails the latest output)",
+		getArgumentCompletions: (argumentPrefix: string) => suggestSchedulesArgs(argumentPrefix),
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const parsed = parseSchedulesArgs(args);
+			if (parsed.mode === "usage") {
+				await notifyCommandResult(ctx, parsed.error);
+				return;
+			}
+			const jobs = getScheduledJobs(ctx.cwd);
+			if (parsed.mode === "log") {
+				const outcome = buildSchedulesLogText(ctx.cwd, jobs, parsed.target);
+				if (outcome.isError) {
+					await notifySchedulesError(ctx, outcome.text);
+					return;
+				}
+				await notifyCommandResult(ctx, outcome.text);
+				return;
+			}
+			// D6-T4: the render path takes `now` as a parameter — this single
+			// `new Date()` at the handler boundary is the clock injection point.
+			// P2-1: the hidden count rides the same user-initiated invocation
+			// (stash-first provider read — in-memory when the scheduler singleton
+			// is registered, one tiers read otherwise; never on a render tick).
+			await notifyCommandResult(
+				ctx,
+				buildSchedulesCommandLines(jobs, new Date(), getScheduledJobsHiddenCountView(ctx.cwd)).join("\n"),
+			);
+		},
+	});
+}

package/src/extension/registration/commands/shared.ts

@@ -35,7 +35,7 @@ import { withSessionId } from "../../team-tool/context.ts";
 import type { handleTeamTool as HandleTeamToolFn } from "../../team-tool.ts";
 import { commandText, notifyCommandResult } from "../command-utils.ts";
 import type { UiState } from "../ui.ts";
-import { openLiveConversation, openTranscriptViewer } from "../viewers.ts";
+import { openAgentsJobsBrowser, openLiveConversation, openTranscriptViewer } from "../viewers.ts";
 
 let _cachedHandleTeamTool: typeof HandleTeamToolFn | undefined;
 let _handleTeamToolPromise: Promise<typeof HandleTeamToolFn> | undefined;
@@ -439,6 +439,42 @@ async function handlePlanDashboardAction(ctx: ExtensionCommandContext, selection
 
 let depsRef: RegisterTeamCommandsDeps | undefined;
 
+/**
+ * Tier A finalize (review round 1, MAJOR-1): dashboard schedule mutations
+ * (T/N/X in pane 8) consumed at the extension layer. The dashboard emits
+ * `done()` selections carrying schedule-* actions + jobId; this routes them
+ * through the SAME team-tool channel the chat surface uses —
+ * handleTeamTool({action:'schedule', subAction, jobId}) → handle-schedule.ts —
+ * so the UI layer never calls the scheduler directly (approved-design
+ * constraint #3). Modeled on handlePlanDashboardAction: dispatch, then surface
+ * the result at its true level (isError → red). No snapshot-cache
+ * invalidation: schedule actions carry no runId (the run list is untouched).
+ * The 2-step delete confirm-gate lives in the dashboard itself (pane-8 X);
+ * this is the final hop to the mutation channel.
+ */
+async function handleScheduleDashboardAction(ctx: ExtensionCommandContext, selection: RunDashboardSelection): Promise<void> {
+	const jobId = selection.jobId;
+	if (!jobId) {
+		depsNotify(ctx, "schedule action requires a job id", "warning");
+		return;
+	}
+	// Defer the dynamic import of run-dashboard.ts (already warm — ui()
+	// loaded it to host the dashboard) so this module's import graph stays
+	// free of the UI chain at Pi startup. The mapping is the UI layer's
+	// published action→subAction contract; importing it (instead of re-deriving)
+	// keeps the two from drifting.
+	// LAZY: run-dashboard.ts — UI chain; warm by the time this runs (ui()).
+	const { scheduleDashboardActionToSubAction } = await import("../../../ui/run-dashboard.ts");
+	const subAction = scheduleDashboardActionToSubAction(selection.action);
+	if (!subAction) {
+		depsNotify(ctx, `unhandled schedule action '${selection.action}'`, "warning");
+		return;
+	}
+	const result = await handleTeamTool({ action: "schedule", subAction, jobId }, teamCommandContext(ctx));
+	const text = commandText(result);
+	depsNotify(ctx, text.length > 800 ? `${text.slice(0, 797)}...` : text, result.isError ? "error" : "info");
+}
+
 /**
  * Internal setter for `depsRef` (Phase 2.1 split). ESM import bindings are
  * read-only, so `registerTeamCommands` in index.ts cannot assign to the
@@ -546,8 +582,27 @@ export async function openTeamDashboard(ctx: ExtensionContext): Promise<void> {
 			deps.getRunSnapshotCache?.(cmdCtx.cwd).invalidate(selection.runId);
 			continue;
 		}
+		// Tier A (review round 1, MAJOR-1): pane-8 schedule mutations route
+		// through the extension channel (handle-schedule.ts subActions) instead
+		// of falling into the generic handleTeamTool fall-through below, where
+		// they dead-ended with an "unknown action" error and CLOSED the
+		// dashboard. runId is "" for these selections — no snapshot invalidation.
+		if (
+			selection.action === "schedule-enable" ||
+			selection.action === "schedule-disable" ||
+			selection.action === "schedule-run-now" ||
+			selection.action === "schedule-remove"
+		) {
+			await handleScheduleDashboardAction(cmdCtx, selection);
+			continue;
+		}
 		if (selection.action === "agent-transcript" && (await openTranscriptViewer(cmdCtx, selection.runId))) continue;
 		if (selection.action === "agent-live" && (await openLiveConversation(cmdCtx, selection.runId))) continue;
+		// feat/agents-browser: `b` from the dashboard opens the unified Agents
+		// & Jobs overlay WITHOUT closing the loop — continue reopens the
+		// dashboard underneath, mirroring the transcript/live-conversation
+		// viewers. runId may be "" (no run selected — jobs-only view).
+		if (selection.action === "browser-open" && (await openAgentsJobsBrowser(cmdCtx))) continue;
 		if (selection.action === "agent-live") {
 			await notifyCommandResult(
 				cmdCtx,

package/src/extension/registration/lifecycle-handlers.ts

@@ -36,7 +36,7 @@ import { reconcileAllStaleRuns } from "../../runtime/recovery/crash-recovery.ts"
 import { CrewScheduler, type ScheduledJob } from "../../runtime/scheduling/scheduler.ts";
 import { tryRegisterSessionCleanup } from "../../runtime/session-resources.ts";
 import { createSessionSnapshot } from "../../runtime/session-snapshot.ts";
-import { applyCrewSettingsTiersToConfig, loadCrewSettingsTiers } from "../../runtime/settings-store.ts";
+import { applyCrewSettingsTiersToConfig, loadCrewSettingsTiers, scheduledJobsHiddenCountOf } from "../../runtime/settings-store.ts";
 import { loadRunManifestById } from "../../state/stores/state-store.ts";
 import type { TeamRunManifest } from "../../state/types.ts";
 import { summarizeHeartbeats } from "../../ui/heartbeat-aggregator.ts";
@@ -61,10 +61,11 @@ import { getBrokerSocketPath } from "../../utils/socket-path.ts";
 import { startAsyncRunNotifier, stopAsyncRunNotifier } from "../async-notifier.ts";
 import { registerCrewAutocomplete } from "../crew-autocomplete.ts";
 import { notifyActiveRuns } from "../session-summary.ts";
-import { persistScheduledJobUpdate, registerCrewScheduler } from "../team-tool/handle-schedule.ts";
+import { persistScheduledJobUpdate, registerCrewScheduler, stashScheduledJobsHiddenCount } from "../team-tool/handle-schedule.ts";
 import { handleTeamTool } from "../team-tool.ts";
 import { runArtifactCleanup } from "./artifact-cleanup.ts";
 import type { RegistrationContext } from "./registration-types.ts";
+import { createScheduleEventNotifier } from "./schedule-toast-bridge.ts";
 
 /**
  * Register all session-lifecycle handlers on the ExtensionAPI. The caller
@@ -283,6 +284,11 @@ function installSessionStartHandler(pi: ExtensionAPI, ctx: RegistrationContext):
 		// Wire scheduler into handle-schedule.ts so handlers can add/list jobs.
 		// EXT-9: module-scoped setter (was globalThis[Symbol.for(...)]).
 		registerCrewScheduler(ctx.crewScheduler);
+		// P2-1 (B2 gate visibility): stash the hidden project-tier count from the
+		// SAME tiers read above (zero extra disk I/O — disk reads are legal here
+		// at session_start but never on later paint paths) so the crew widget
+		// line and the dashboard pane can surface "N project-tier jobs hidden".
+		stashScheduledJobsHiddenCount(scheduledJobsHiddenCountOf(crewSettingsTiers));
 		// Load scheduled jobs from settings if present.
 		// BOUNDARY (Wave B2): project-tier scheduledJobs are OPT-IN GATED — the
 		// registration loop reads the gated `effectiveScheduledJobs` view (user
@@ -497,9 +503,17 @@ function setupCrewScheduler(
 	sessionId: string | undefined,
 ): CrewScheduler {
 	const crewScheduler = new CrewScheduler();
+	// Tier D (schedules UI): scheduler events → terminal-status toasts. Bounded
+	// (hung-notice pattern): at most one notice per event; headless sessions
+	// no-op inside the bridge (hasUI probed defensively) instead of crashing.
+	const notifyScheduleEvent = createScheduleEventNotifier({
+		hasUI: () => extensionCtx.hasUI,
+		ui: extensionCtx.ui,
+	});
 	crewScheduler.start({
 		emit: (event) => {
 			if (ctx.cleanedUp) return;
+			notifyScheduleEvent(event);
 			pi.events?.emit?.("crew-scheduler", event);
 		},
 		executor: (job) => {

package/src/extension/registration/schedule-toast-bridge.ts

@@ -0,0 +1,109 @@
+/**
+ * Tier D (schedules UI): bridge ScheduleChangeEvent → terminal-status toasts.
+ *
+ * Bounded like the hung-notice pattern (foreground-watchdog): at most ONE
+ * notice per event, no drip. Mapping (approved design):
+ *   • fired  → `⏰ <name> fired → <agentId>`            (info)
+ *   • error  → `⏰ scheduled job <jobId> failed: …`     (error — red)
+ *   • run completion is NOT an event of its own — it surfaces as an `updated`
+ *     event whose job.lastStatus transitions INTO "success" (tracked per job,
+ *     the "if trackable" clause), so repeated `updated` emissions
+ *     (enable/disable patches, runCount bumps) stay silent.
+ *   • run FAILURE has two producers: the scheduler's synchronous `error`
+ *     event (fire()'s catch) AND — the common path — the ASYNC executor
+ *     rejection, which lifecycle-handlers records as an `updated` event whose
+ *     lastStatus moves running→error with no `error` event at all. That
+ *     transition gets the red `✗ failed` toast. A per-job `failedNotified`
+ *     set de-dupes the two producers (fire() marks running → clears the flag;
+ *     whichever failure notice lands first claims it) so a sync-throwing
+ *     executor still yields exactly ONE notice per attempt.
+ *
+ * All interpolated fields pass through sanitizeLine (untrusted job fields
+ * and LLM-derived error strings must never inject line breaks / control
+ * chars into the terminal status area).
+ *
+ * Headless-safe: hasUI is probed defensively (the getter THROWS on a stale
+ * context) and ui.notify failures are swallowed — the bridge is a no-op, never
+ * a crash path, inside the scheduler's emit callback.
+ */
+import type { ScheduleChangeEvent } from "../../runtime/scheduling/scheduler.ts";
+import { sanitizeLine } from "../../utils/visual.ts";
+
+export interface ScheduleToastTarget {
+	notify(text: string, level: "info" | "warning" | "error"): unknown;
+}
+
+export interface ScheduleToastDeps {
+	/** hasUI probe — may throw on a stale ctx; a throw counts as "no UI". */
+	hasUI(): boolean;
+	ui: ScheduleToastTarget | undefined;
+}
+
+/** Error-toast payload cap: first line only, at most ~200 chars (toast
+ * convention — tighter than the 800-char command text block). */
+const ERROR_TEXT_MAX = 200;
+
+export function createScheduleEventNotifier(deps: ScheduleToastDeps): (event: ScheduleChangeEvent) => void {
+	/** Per-job lastStatus tracker — the "transition" memory for success toasts. */
+	const lastStatusByJob = new Map<string, string | undefined>();
+	/** Per-job "failure already noticed" marker — de-dupes the error-event and
+	 *  running→error-transition producers so one failed attempt = one notice. */
+	const failedNotified = new Set<string>();
+	const deliver = (text: string, level: "info" | "error"): void => {
+		try {
+			if (!deps.hasUI() || !deps.ui) return;
+			deps.ui.notify(text, level);
+		} catch {
+			/* toasts are best-effort — never break the scheduler path */
+		}
+	};
+	return (event: ScheduleChangeEvent): void => {
+		switch (event.type) {
+			case "fired":
+				deliver(`⏰ ${sanitizeLine(event.name)} fired → ${sanitizeLine(event.agentId)}`, "info");
+				return;
+			case "error": {
+				// Sync producer (fire()'s catch / past-time once-job). Skipped only
+				// when the running→error transition already claimed this attempt.
+				if (failedNotified.has(event.jobId)) return;
+				failedNotified.add(event.jobId);
+				const firstLine = event.error.split("\n")[0] ?? "";
+				const clipped = firstLine.length > ERROR_TEXT_MAX ? `${firstLine.slice(0, ERROR_TEXT_MAX - 1)}…` : firstLine;
+				deliver(`⏰ scheduled job ${sanitizeLine(event.jobId)} failed: ${sanitizeLine(clipped)}`, "error");
+				return;
+			}
+			case "added":
+				// Persisted jobs re-register here at session start — record, never
+				// toast (otherwise every session boot would spam one line per job).
+				lastStatusByJob.set(event.job.id, event.job.lastStatus);
+				return;
+			case "updated": {
+				const previous = lastStatusByJob.get(event.job.id);
+				lastStatusByJob.set(event.job.id, event.job.lastStatus);
+				// A new attempt underway: re-arm the failure notice for it.
+				if (event.job.lastStatus === "running") {
+					failedNotified.delete(event.job.id);
+					return;
+				}
+				// Async executor rejection (lifecycle finalization path): running →
+				// error with NO scheduler `error` event — the most common failure
+				// route. Guarded on previous === "running" so a persisted
+				// error-status re-registration (undefined/"error" → "error") stays
+				// silent and cannot double-toast with the sync producer.
+				if (event.job.lastStatus === "error" && previous === "running") {
+					failedNotified.add(event.job.id);
+					deliver(`⏰ ${sanitizeLine(event.job.name)} ✗ failed`, "error");
+					return;
+				}
+				if (event.job.lastStatus === "success" && previous !== "success") {
+					deliver(`⏰ ${sanitizeLine(event.job.name)} ✓ succeeded`, "info");
+				}
+				return;
+			}
+			case "removed":
+				lastStatusByJob.delete(event.jobId);
+				failedNotified.delete(event.jobId);
+				return;
+		}
+	};
+}

package/src/extension/registration/viewers.ts

@@ -1,9 +1,12 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { matchesKey } from "@earendil-works/pi-tui";
 import { loadConfig } from "../../config/config.ts";
 import { readCrewAgents } from "../../runtime/crew-agent-records.ts";
 import { listLiveAgents } from "../../runtime/live-session/live-agent-manager.ts";
 import { loadRunManifestById } from "../../state/stores/state-store.ts";
+import { AgentsJobsBrowser } from "../../ui/agents-jobs-browser.ts";
 import { LiveConversationOverlay } from "../../ui/live-conversation-overlay.ts";
+import { requestRenderTarget } from "../../ui/pi-ui-compat.ts";
 import { asCrewTheme } from "../../ui/theme-adapter.ts";
 // Lazy-loaded: DurableTranscriptViewer is 658ms — only needed for /crew transcript command
 import type { DurableTranscriptViewer as DurableTranscriptViewerType } from "../../ui/transcript-viewer.ts";
@@ -87,7 +90,7 @@ export async function openLiveConversation(
 					return overlay.render(width);
 				},
 				handleInput(data: string) {
-					if (data === "\x1b" || data === "q") {
+					if (matchesKey(data, "escape") || matchesKey(data, "q")) {
 						overlay.close();
 						done(undefined);
 					}
@@ -111,3 +114,65 @@ export async function openLiveConversation(
 	);
 	return true;
 }
+
+/**
+ * feat/agents-browser: open the unified Agents & Jobs browser overlay.
+ *
+ * Full-view component (the SAME custom() precedent as openLiveConversation —
+ * pi's overlay-anchor option was evaluated and set aside: overlays float over
+ * chat with different key routing; the modal form matches every existing
+ * pi-crew viewer, so users get one consistent interaction model). Opened from the run
+ * dashboard with ONE keypress (`b`); lists ALL live agents + scheduled jobs
+ * via the G17 providers — independent of any single run. Headless sessions
+ * (`ctx.hasUI === false`) are a silent no-op returning false.
+ */
+export async function openAgentsJobsBrowser(
+	ctx: Pick<ExtensionCommandContext, "hasUI" | "cwd" | "ui" | "sessionManager">,
+): Promise<boolean> {
+	if (!ctx.hasUI) return false;
+	const theme = asCrewTheme({});
+	const workspaceId = ctx.sessionManager?.getSessionId?.();
+	await ctx.ui.custom<undefined>(
+		(tui, _theme, _keybindings, done) => {
+			const columns = tui?.terminal?.columns ?? 80;
+			const rows = tui?.terminal?.rows ?? 24;
+			const browser = new AgentsJobsBrowser({
+				cwd: ctx.cwd,
+				workspaceId,
+				theme,
+				columns,
+				rows,
+				requestRender: () => requestRenderTarget(tui),
+				// Enter on an agent opens the full transcript overlay — the
+				// `/crew transcript` experience ("chi tiết như subagent cũ").
+				onOpenTranscript: ({ runId, taskId }) => {
+					void openTranscriptViewer(ctx as ExtensionCommandContext, runId, taskId);
+				},
+			});
+			return {
+				render(width: number) {
+					return browser.render(width);
+				},
+				handleInput(data: string) {
+					browser.handleInput(data);
+					if (browser.isClosed) done(undefined);
+				},
+				invalidate() {
+					browser.refreshData(true);
+				},
+				dispose() {
+					browser.dispose();
+				},
+			};
+		},
+		{
+			overlay: true,
+			overlayOptions: {
+				width: "92%",
+				maxHeight: "70%",
+				anchor: "center",
+			},
+		},
+	);
+	return true;
+}