@alphacoder-v0/pi-loops 0.22.8 → 0.24.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphacoder-v0/pi-loops",
-  "version": "0.22.8",
+  "version": "0.24.1",
   "description": "An automation layer for pi: cron + stateful loops with a triage inbox, maker/checker verification, dynamic triggers, MCP notifications and tools, lifecycle hooks, session archives. A non-invasive pi extension.",
   "type": "module",
   "license": "MIT",
@@ -52,8 +52,9 @@
     "check:docs": "node scripts/check-docs.mjs",
     "check:downstream": "sh test/downstream/run.sh",
     "check:contract": "sh test/contract/run.sh",
-    "test": "node --import ./src/register-pi.mjs --test test/*.test.ts",
-    "check:scripts": "node --check src/web.mjs && node --check src/cli-entry.mjs && node --check src/host-entry.mjs && node --check src/ts-entry.mjs && node --check src/pi-resolver.mjs && node --check src/register-pi.mjs && node --check examples/mcp-notify-server.mjs"
+    "journey": "node test/journey/run.mjs",
+    "test": "PI_LOOPS_HOST=off node --import ./src/register-pi.mjs --test test/*.test.ts",
+    "check:scripts": "node --check src/web.mjs && node --check src/cli-entry.mjs && node --check src/host-entry.mjs && node --check src/ts-entry.mjs && node --check src/pi-resolver.mjs && node --check src/register-pi.mjs && node --check examples/mcp-notify-server.mjs && for f in test/journey/boot.mjs test/journey/run.mjs test/journey/journeys/*.mjs; do node --check \"$f\" || exit 1; done"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

package/recipes/autoresearch/recipe.toml

@@ -2,6 +2,7 @@
 # a ledger, a checker re-measures on held-out data before anything is proposed. docs/recipes.md.
 name = "autoresearch"
 summary = "One experiment per run against a research contract you wrote; a ledger of what was tried; promotion only on held-out evidence."
+line = "Runs one experiment an hour and keeps only what held-out data confirms."
 tier = "advanced"
 useful_when = ["You have a metric a script can print and a search space wider than your evenings.", "You want every attempt in a ledger, the failed ones included."]
 needs_tracker = false

package/recipes/changelog-draft/recipe.toml

@@ -1,5 +1,6 @@
 name = "changelog-draft"
 summary = "When the default branch is ahead of the last tag, draft the changelog entry and propose a version; a person tags."
+line = "Drafts the next changelog entry and version; you tag the release."
 tier = "starter"
 useful_when = ["Releases wait on someone finding an evening to write the entry.", "You want the version and the entry proposed from the commits, and to tag it yourself."]
 needs_tracker = false

package/recipes/ci-sweeper/recipe.toml

@@ -1,6 +1,7 @@
 # ci-sweeper: a red default branch gets a finding, or a fix in a worktree and a pull request. docs/recipes.md.
 name = "ci-sweeper"
 summary = "When the default branch's checks go red, says so — or, at propose, reproduces the failure in a worktree, fixes it, and opens the pull request; twice failing to fix the same failure is a stop."
+line = "Tells you when the default branch goes red, or fixes it."
 tier = "advanced"
 useful_when = ["The default branch goes red and every open pull request looks red with it.", "The failures are the boring kind: a flaky assertion, a renamed fixture, a dependency that moved."]
 needs_tracker = false

package/recipes/daily-digest/recipe.toml

@@ -1,6 +1,7 @@
 # daily-digest: one finding a morning saying what needs a look today, or nothing. docs/recipes.md.
 name = "daily-digest"
 summary = "Every morning, one finding that says what in this project needs a look today — open items, a red CI, a loop that keeps failing — or nothing when nothing does."
+line = "Every morning, one finding on what in this project needs a look."
 tier = "starter"
 useful_when = ["You open the tracker each morning to ask what happened overnight.", "You want the first loop in a project to write nowhere but the inbox."]
 needs_tracker = true

package/recipes/deps-sweeper/recipe.toml

@@ -2,6 +2,7 @@
 # worktree and put up as one pull request. docs/recipes.md.
 name = "deps-sweeper"
 summary = "Once a week, runs the project's audit and outdated commands and reports each new advisory and each dependency a major behind — or, at propose, applies the patch and minor updates in a worktree, runs the checks, and opens one pull request; a major is never applied, and the same package failing twice is a stop."
+line = "Weekly, reports new advisories or opens one pull request of safe updates."
 tier = "advanced"
 useful_when = ["Advisories arrive by email and the patch bumps pile up.", "You want the safe updates put up as one pull request a week and the majors left to you."]
 needs_tracker = false

package/recipes/ecosystem/recipe.toml

@@ -1,6 +1,7 @@
 # ecosystem: who uses this project, drafted — every outward word is a finding a person claims. docs/recipes.md.
 name = "ecosystem"
 summary = "Once a week, finds projects that use or fork this one and drafts the one reply or upstream invitation worth sending; every draft is a finding, and a person sends it."
+line = "Finds projects that use this one and drafts the reply worth sending."
 tier = "advanced"
 useful_when = ["People use or fork the project and you find out months later.", "You want the reply drafted and to send it yourself."]
 needs_tracker = true

package/recipes/issue-loop/recipe.toml

@@ -1,6 +1,7 @@
 # The issue loop: the tracker as a state machine that three loops turn. docs/recipes.md explains it.
 name = "issue-loop"
 summary = "Triage new issues into agent briefs, build the accepted ones in a worktree, open pull requests; a person promotes and merges."
+line = "Turns new issues into briefs and accepted briefs into pull requests."
 tier = "advanced"
 useful_when = ["Issues arrive faster than you read them, and most are buildable once someone writes the brief.", "You want the tracker to be the state machine, and your part to be two clicks: accept the brief, merge the pull request."]
 needs_tracker = true

package/recipes/pr-watch/recipe.toml

@@ -1,6 +1,7 @@
 # pr-watch: the open pull requests, and only what changed about them. docs/recipes.md.
 name = "pr-watch"
 summary = "Watches the open pull requests for what stalls them — a red check, a conflict, a review nobody answered — and reports only what changed since last time."
+line = "Reports what changed on open pull requests: red checks, conflicts, unanswered reviews."
 tier = "starter"
 useful_when = ["Pull requests stall for days before anyone notices the red check or the unanswered review.", "You want to hear what changed about them, not what they are."]
 needs_tracker = true

package/skills/pi-loops/SKILL.md

@@ -11,8 +11,8 @@ The user's pi has pi-loops installed. Prefer its tools over ad-hoc `sleep` loops
 
 | The user wants… | Use |
 |---|---|
-| "every day at 9 / hourly / 每小时 …" and the result belongs in this chat (a reminder, a question to answer here) | `cron_create` with `stateful: false` — it belongs to this session and runs only while this session is open; the user leaving the window means it sleeps |
-| anything that must run whether or not a window is open — a nightly digest, a report, a watch | `cron_create` with `stateful: true`, even when the user did not say "loop": a plain job cannot run unattended |
+| "every day at 9 / hourly / 每小时 …" and the result belongs in this chat (a reminder, a question to answer here) | `cron_create` with `stateful: false` — it belongs to this session; while the session is closed, it runs in the background in the conversation, so the answer is there when the user comes back. Each run is a model turn. Its turns run with the chat's built-in tools under the dangerous-command guard: in an open window a dangerous command or a tool outside them asks the user first, and in the background it is refused. In the background they also run without this window's -e extensions or flags |
+| work whose result should not land in a conversation — a nightly digest, a report, a watch | `cron_create` with `stateful: true`, even when the user did not say "loop" |
 | recurring watch/triage: "check X and tell me what changed", "report new issues" | `cron_create` with `stateful: true` — the loop keeps notes between runs and reports findings to `/inbox` instead of interrupting the chat |
 | the findings must be double-checked before the user sees them | `cron_create` with `stateful: true, verify: true` (a second adversarial sub-agent reviews each finding) |
 | "when <condition> happens, do <action>" (a file appears, a PR merges, a build finishes) | `new_trigger` — condition + action, fires once unless the user asks for repeating |
@@ -49,5 +49,7 @@ reported in your notes; report only new or newly closed issues". Findings should
 
 ## Confirmations
 
-Creating or removing a trigger, and re-enabling a job or trigger, asks the user to confirm. If the
-confirmation is declined, stop; do not retry with different arguments.
+With the user present, `cron_create` and `new_trigger` ask them first, in the same call, and
+return `created ...` or `cancelled: ...`. Removing a trigger, and re-enabling a job or trigger, asks
+the user to confirm. If the user cancels or declines, stop: do not retry with different arguments,
+do not set it up another way, and do not do the action now.

package/src/activity.ts

@@ -0,0 +1,199 @@
+/**
+ * The activity strip's items and the attention counts, computed when the page asks: runs from
+ * `runs.jsonl`, rule results from `triggers-audit.jsonl` joined to their findings in `inbox.jsonl`.
+ * There is no store of its own, so nothing here has to be kept in step with the files it reads.
+ * Pure: the caller reads the files, and this decides what they say.
+ */
+import type { InboxEntry } from "./inbox.ts";
+import { ruleResultText, splitFinding } from "./inbox-card.ts";
+import { failingJobs } from "./job-health.ts";
+import { redact } from "./redact.ts";
+import { runCardFor } from "./run-card.ts";
+import type { LoopJob, RunRecord } from "./store.ts";
+import type { AuditRecord } from "./triggers.ts";
+
+/** Items the strip is given at most; `more` counts the rest of the window. */
+export const ACTIVITY_LIMIT = 100;
+/** How far back the strip looks. */
+export const ACTIVITY_WINDOW_MS = 24 * 60 * 60 * 1000;
+/** Machine-wide new decisions the page is told about, newest first, for its notification. */
+export const NEW_DECISIONS_LIMIT = 20;
+/** A strip row's text, clipped so a row stays one line. */
+const ACTIVITY_TEXT_CHARS = 160;
+
+export interface ActivityItem {
+	/** The run id, or the rule check's trace id. */
+	id: string;
+	kind: "run" | "rule";
+	/** The loop, or the first matched rule (`name` is its condition); `gone` when it is no longer there. */
+	source: { id: string; name?: string; gone: boolean };
+	finishedAt: string;
+	ok: boolean;
+	/** The run was stopped (a person, a quit, a restart): no failure, no card. */
+	stopped: boolean;
+	/** Set when a person stopped it, which the strip says as "stopped by you". */
+	stoppedBy?: "person";
+	/** A run: the findings it filed. A rule check: the findings its result is. */
+	findings: number;
+	seconds: number;
+	costUsd?: number;
+	/** Redacted and clipped. */
+	error?: string;
+	/** A rule check: the start of what it said, redacted and clipped. */
+	text?: string;
+	/** The run wrote a card into its conversation (src/run-card.ts). */
+	carded: boolean;
+	/** A rule check: its findings, so a row can point at the card. */
+	inboxIds: string[];
+	/** A rule check: the result also went to a conversation (`promote_to_chat`). */
+	inChat: boolean;
+	/** The run's loop or the rule was made in the conversation asking. */
+	fromThisConversation: boolean;
+}
+
+export interface Attention {
+	/** New decisions and new news in the project asked about (the whole machine when none is). */
+	decisions: number;
+	news: number;
+	/** New decisions on the whole machine, newest first. */
+	newDecisions: Array<{ id: string; cwd: string; headline: string }>;
+	/** Loops failing three or more times in a row; `key` is the same for the whole streak. */
+	failing: Array<{ jobId: string; name?: string; streak: number; key: string }>;
+	/** Only when today's spend has reached the cap. */
+	budget?: { day: string; spent: number; cap: number };
+}
+
+export interface ActivityInput {
+	runs: readonly RunRecord[];
+	audit: readonly AuditRecord[];
+	findings: readonly InboxEntry[];
+	jobs: ReadonlyMap<string, { name?: string; createdBy?: { sessionId?: string } }>;
+	rules: ReadonlyMap<string, { condition: string; createdBy?: { sessionId?: string } }>;
+	/** The project asked about, and how a path is matched to it; no cwd is the whole machine. */
+	cwd?: string;
+	inProject: (entryCwd: string, cwd: string) => boolean;
+	sessionId?: string;
+	sinceMs: number;
+	limit?: number;
+}
+
+/** Text from a file another process wrote, as one redacted line: a field of the wrong type is no text. */
+const clip = (text: unknown, n = ACTIVITY_TEXT_CHARS) => {
+	const one = redact(typeof text === "string" ? text : "").replace(/\s+/g, " ").trim();
+	return one.length > n ? `${one.slice(0, n - 1)}…` : one;
+};
+const secondsBetween = (from: string | undefined, to: string) => {
+	const s = from ? Math.round((Date.parse(to) - Date.parse(from)) / 1000) : 0;
+	return Number.isFinite(s) && s > 0 ? s : 0;
+};
+
+/** Whether a path is in `cwd`'s project (always, with no cwd), asked once per distinct path. */
+function projectMatch(cwd: string | undefined, inProject: (entryCwd: string, cwd: string) => boolean): (entryCwd: unknown) => boolean {
+	const known = new Map<string, boolean>();
+	return (entryCwd) => {
+		if (cwd === undefined) return true;
+		if (typeof entryCwd !== "string") return false;
+		let yes = known.get(entryCwd);
+		if (yes === undefined) known.set(entryCwd, (yes = inProject(entryCwd, cwd)));
+		return yes;
+	};
+}
+
+/** The strip's items, newest first, at most `limit`; `more` counts the rest, `failed` the failures among all. */
+export function activityFrom(input: ActivityInput): { items: ActivityItem[]; more: number; failed: number } {
+	// Matching a project resolves paths on disk, and this runs on every page's poll: once per distinct
+	// cwd, and only for a record inside the window.
+	const here = projectMatch(input.cwd, input.inProject);
+	const recent = (at: string | undefined) => typeof at === "string" && Date.parse(at) >= input.sinceMs;
+	const items: ActivityItem[] = [];
+	for (const r of input.runs) {
+		if (!r.stateful || typeof r.runId !== "string" || !recent(r.finishedAt) || !here(r.cwd)) continue;
+		const job = input.jobs.get(r.jobId);
+		items.push({
+			id: r.runId,
+			kind: "run",
+			source: { id: String(r.jobId), name: job?.name ?? (typeof r.jobName === "string" ? r.jobName : undefined), gone: !job },
+			finishedAt: r.finishedAt,
+			ok: r.ok === true,
+			stopped: !!r.aborted,
+			...(r.stoppedBy === "person" ? { stoppedBy: "person" as const } : {}),
+			findings: typeof r.findings === "number" ? r.findings : 0,
+			seconds: secondsBetween(r.startedAt, r.finishedAt),
+			...(typeof r.usage?.cost === "number" && r.usage.cost ? { costUsd: r.usage.cost } : {}),
+			...(!r.ok && r.error ? { error: clip(r.error) } : {}),
+			carded: runCardFor(r) === "card",
+			inboxIds: [],
+			inChat: false,
+			fromThisConversation: !!input.sessionId && r.forSession === input.sessionId,
+		});
+	}
+	// A rule check is the `running` row and its result; a result that matched nothing is not news.
+	const started = new Map<string, string>();
+	const inChat = new Set<string>();
+	for (const a of input.audit) {
+		if (a.type === "trigger_result" && a.state === "running") started.set(a.traceId, a.ts);
+		if (a.type === "trigger_promotion" && (a.state === "promoted" || a.state === "appended")) inChat.add(a.traceId);
+	}
+	const filed = new Map<string, InboxEntry[]>();
+	for (const f of input.findings) if (typeof f.source === "string" && f.source.startsWith("trigger:")) filed.set(f.run_id, [...(filed.get(f.run_id) ?? []), f]);
+	for (const a of input.audit) {
+		if (a.type !== "trigger_result" || a.sourceLabel !== "local:dynamic" || typeof a.traceId !== "string" || !recent(a.ts) || !here(a.cwd)) continue;
+		// This project's rules the check named (src/trigger-runtime.ts), not every id it wrote.
+		const matched = Array.isArray(a.details?.matched_rule_ids) ? (a.details.matched_rule_ids as unknown[]).filter((id): id is string => typeof id === "string") : [];
+		if (!(a.state === "failed" || (a.state === "completed" && matched.length))) continue;
+		const ruleId = matched[0] ?? "";
+		const rule = ruleId ? input.rules.get(ruleId) : undefined;
+		const findings = filed.get(a.traceId) ?? [];
+		const cost = typeof a.details?.cost_usd === "number" ? a.details.cost_usd : 0;
+		items.push({
+			id: a.traceId,
+			kind: "rule",
+			source: { id: ruleId, ...(rule ? { name: clip(rule.condition, 80) } : {}), gone: !!ruleId && !rule },
+			finishedAt: a.ts,
+			ok: a.state === "completed",
+			stopped: false,
+			findings: findings.length,
+			seconds: secondsBetween(started.get(a.traceId), a.ts),
+			...(cost ? { costUsd: cost } : {}),
+			...(a.state === "failed" ? { error: clip(a.summary) || "the check failed" } : { text: clip(ruleResultText(typeof a.summary === "string" ? a.summary : "")) }),
+			carded: false,
+			inboxIds: findings.map((f) => f.id),
+			inChat: inChat.has(a.traceId),
+			fromThisConversation: !!input.sessionId && rule?.createdBy?.sessionId === input.sessionId,
+		});
+	}
+	items.sort((x, y) => y.finishedAt.localeCompare(x.finishedAt));
+	const limit = input.limit ?? ACTIVITY_LIMIT;
+	return { items: items.slice(0, limit), more: Math.max(0, items.length - limit), failed: items.filter((i) => !i.ok && !i.stopped).length };
+}
+
+/** The title's counts, the hidden tab's notifications and the budget line, from the same files. */
+export function attentionFrom(input: {
+	findings: readonly InboxEntry[];
+	jobs: readonly LoopJob[];
+	cwd?: string;
+	inProject: (entryCwd: string, cwd: string) => boolean;
+	budget?: { spent: number; cap: number; over: boolean };
+	day: string;
+}): Attention {
+	const fresh = input.findings.filter((f) => f.status === "new");
+	const inHere = projectMatch(input.cwd, input.inProject);
+	// A finding with no cwd is in every project, as `/inbox` lists it (inbox.ts belongsToProject).
+	const here = fresh.filter((f) => !f.cwd || inHere(f.cwd));
+	const decisions = fresh.filter((f) => f.kind === "checkpoint");
+	return {
+		decisions: here.filter((f) => f.kind === "checkpoint").length,
+		news: here.filter((f) => f.kind !== "checkpoint").length,
+		newDecisions: decisions
+			.slice(-NEW_DECISIONS_LIMIT)
+			.reverse()
+			.map((f) => ({ id: f.id, cwd: f.cwd, headline: clip(splitFinding(clip(f.text, 500), "checkpoint").headline, 120) })),
+		failing: failingJobs([...input.jobs]).map((j) => ({ jobId: j.id, ...(j.name ? { name: j.name } : {}), streak: j.consecutiveFailures ?? 0, key: `${j.id}:${(j.runCount ?? 0) - (j.consecutiveFailures ?? 0)}` })),
+		...(input.budget?.over ? { budget: { day: input.day, spent: input.budget.spent, cap: input.budget.cap } } : {}),
+	};
+}
+
+/** The attention block for a conversation in no project known: what is said of the whole machine, and no project's counts. */
+export function machineWide(a: Attention): Pick<Attention, "newDecisions" | "failing" | "budget"> {
+	return { newDecisions: a.newDecisions, failing: a.failing, ...(a.budget ? { budget: a.budget } : {}) };
+}

package/src/archive.ts

@@ -17,8 +17,9 @@ import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { sameProject } from "./presence.ts";
+import { sameProject } from "./paths.ts";
 import { LOOP_STATE_MAX_CHARS, capChars } from "./protocol.ts";
+import { pathOnlyCondition } from "./path-precheck.ts";
 import { previewRedacted } from "./redact.ts";
 import { computeNext, formatSchedule, isValidSchedule, stamp } from "./schedule.ts";
 import { type JobStore, newId, type LoopJob } from "./store.ts";
@@ -190,7 +191,7 @@ export function defaultExportPath(cwd: string, sessionId: string): string {
  * The store is machine-global, so the project alone would sweep in a colleague's loops — or your
  * own from another window — and the session that created a job or rule is what scopes the archive.
  * A job or rule from before `createdBy` existed has no owner to ask, and counts as this session's
- * when it is in this project. "This project" is `sameProject`, not a string comparison: a worktree
+ * when it is in this project; so does a job the project owns (`owner: "project"`). "This project" is `sameProject`, not a string comparison: a worktree
  * or a symlinked path is the same project and its loops belong in the same archive.
  */
 export function automationOf(jobs: LoopJob[], rules: DynamicTriggerRule[], cwd: string, sessionId?: string): { jobs: LoopJob[]; rules: DynamicTriggerRule[] } {
@@ -373,7 +374,7 @@ export function importSession(input: ImportInput): ImportSummary {
 			// hand-made archive would throw there, and the tick has no per-job recovery upstream.
 			if (!isValidSchedule(raw.schedule)) throw new Error(`cron sidecar contains an invalid schedule for job ${raw.id}`);
 			// And one that parses but can never match ("0 0 30 2 *"): the job would go quiet with nothing
-			// to see, and every scan for its next run walks the whole lookahead window on the leader's
+			// to see, and every scan for its next run walks the whole lookahead window on the scheduler's
 			// tick. `/cron add` and `/cron set` have refused it since they existed; an archive is user
 			// input at the same boundary. Only cron is asked — a `once` whose time has passed is due now.
 			if (raw.schedule.kind === "cron" && computeNext({ schedule: raw.schedule, createdAt: Date.parse(raw.createdAt) || Date.now() }, Date.now()) === undefined) {
@@ -385,7 +386,10 @@ export function importSession(input: ImportInput): ImportSummary {
 			// `createdBy` is left as the archive carries it: it names the session that created the job,
 			// which is what lets a second import of the same archive recognise itself. Re-stamping it
 			// with the fresh import session would make every import look new and double the automation.
-			const { host: _legacyHost, ...rawJob } = raw as typeof raw & { host?: unknown };
+			// A job the project owns stays the project's; one with no owner at all is from before
+			// `createdBy` and counts as the exporting conversation's.
+			const { host: _legacyHost, owner: _owner, createdBy: _createdBy, ...rawJob } = raw as typeof raw & { host?: unknown };
+			const projectOwned = raw.owner === "project";
 			const job: LoopJob = {
 				...rawJob,
 				cwd: input.targetCwd,
@@ -395,7 +399,7 @@ export function importSession(input: ImportInput): ImportSummary {
 				lastError: undefined,
 				skippedOverlap: 0,
 				sessionId: raw.stateful ? undefined : sessionId,
-				createdBy: raw.createdBy ?? { sessionId: parsed.header.id, cwd: manifest.source?.cwd ?? input.targetCwd },
+				...(projectOwned ? { owner: "project" as const } : { createdBy: raw.createdBy ?? { sessionId: parsed.header.id, cwd: manifest.source?.cwd ?? input.targetCwd } }),
 			};
 			if (dedup.hasJob(job)) continue;
 			if (input.existingJobIds.has(job.id)) job.id = newId("cron");
@@ -414,8 +418,11 @@ export function importSession(input: ImportInput): ImportSummary {
 		for (const raw of file.rules as DynamicTriggerRule[]) {
 			if (!raw || typeof raw.id !== "string" || typeof raw.condition !== "string" || typeof raw.action !== "string") throw new Error("trigger sidecar contains an invalid rule");
 			if (!SAFE_ID.test(raw.id)) throw new Error("trigger sidecar contains an invalid rule id");
-			const { host: _legacyRuleHost, ...rawRule } = raw as typeof raw & { host?: unknown };
+			const { host: _legacyRuleHost, precheck: _theirPrecheck, ...rawRule } = raw as typeof raw & { host?: unknown };
 			const rule: DynamicTriggerRule = { ...rawRule, cwd: input.targetCwd, enabled: raw.enabled && input.activate, createdBy: raw.createdBy ?? { sessionId: parsed.header.id } };
+			// Read again here, against this project and this home: the archive's was resolved on the machine that wrote it.
+			const only = pathOnlyCondition(rule.condition, { cwd: input.targetCwd, home: os.homedir() });
+			if ("watch" in only) rule.precheck = only.watch;
 			if (dedup.hasRule(rule)) continue;
 			if (input.existingRuleIds.has(rule.id)) rule.id = newRuleId();
 			if (raw.enabled) originallyEnabledRules.push(rule.id);
@@ -519,7 +526,7 @@ export async function offerToEnable(
 	if (imp.automationEnabled) return none;
 	const pending = imp.originallyEnabledJobs.length + imp.originallyEnabledRules.length;
 	if (!pending || !confirm) return none;
-	const ok = await confirm("Enable imported automation?", `${imp.originallyEnabledJobs.length} cron job(s) and ${imp.originallyEnabledRules.length} trigger rule(s) were enabled in the source session. Enable them here now?`);
+	const ok = await confirm("Enable imported automation?", `${count(imp.originallyEnabledJobs.length, "loop")} and ${count(imp.originallyEnabledRules.length, "rule")} were enabled in the source conversation. Enable them here now?`);
 	if (!ok) return none;
 	for (const id of imp.originallyEnabledJobs) {
 		const before = jobStore.load().find((j) => j.id === id);
@@ -564,8 +571,13 @@ class Dedup {
 
 	notes(): string[] {
 		const out: string[] = [];
-		if (this.jobs) out.push(`${this.jobs} cron job(s) already imported from this archive were skipped`);
-		if (this.rules) out.push(`${this.rules} trigger rule(s) already imported from this archive were skipped`);
+		if (this.jobs) out.push(`${count(this.jobs, "loop")} already imported from this archive ${this.jobs === 1 ? "was" : "were"} skipped`);
+		if (this.rules) out.push(`${count(this.rules, "rule")} already imported from this archive ${this.rules === 1 ? "was" : "were"} skipped`);
 		return out;
 	}
 }
+
+/** `1 loop`, `2 loops`: a count a person reads, never `loop(s)`. */
+function count(n: number, one: string): string {
+	return `${n} ${n === 1 ? one : `${one}s`}`;
+}

package/src/args.ts

@@ -144,7 +144,8 @@ export interface SetArgs {
 	thinking?: string | null;
 	timeoutMs?: number | null;
 	name?: string | null;
-	/** `"here"` = this machine; `null` = any machine. */
+	/** Jobs only: the tools its turns run with; `null` clears the list. */
+	tools?: string[] | null;
 	/** Jobs only: the new prompt, verbatim. A loop's notes live under its id, so rewording it here keeps them. */
 	prompt?: string;
 	/** Jobs only: already parsed, so a typo is rejected before it can be stored. */
@@ -162,7 +163,7 @@ export interface SetOptions {
  * `--model -` (or `current`) removes the pin.
  */
 export function parseSetArgs(input: string, opts: SetOptions = {}): SetArgs {
-	const usage = `usage: /cron|/triggers set <id> [--model <provider/id>|-] [--thinking <level>|-] [--timeout <dur>|-] [--name <n>|-]${opts.job ? ' [--prompt "<text>"] [--schedule "<expr>"]' : ""}`;
+	const usage = `usage: /cron|/triggers set <id> [--model <provider/id>|-] [--thinking <level>|-] [--timeout <dur>|-] [--name <n>|-]${opts.job ? ' [--tools a,b|-] [--prompt "<text>"] [--schedule "<expr>"]' : ""}`;
 	const tokens = tokenize(input);
 	const out: SetArgs = { ref: "" };
 	let touched = 0;
@@ -185,6 +186,9 @@ export function parseSetArgs(input: string, opts: SetOptions = {}): SetArgs {
 		else if (t === "--thinking") out.thinking = clear ? null : requireThinkingLevel(val);
 		else if (t === "--timeout") out.timeoutMs = clear ? null : parseDuration(val);
 		else if (t === "--name") out.name = clear ? null : val;
+		// A plain job's `--tools` was inert in 0.22 and caps its turns since 0.23: `-` is how such a job
+		// is uncapped without remove-and-re-add. A rule has no tools of its own.
+		else if (opts.job && t === "--tools") out.tools = clear ? null : val.split(",").map((s) => s.trim()).filter(Boolean);
 		// Rewording a loop or moving it to another hour used to mean remove-and-re-add, which mints a
 		// new id — and the notes a stateful loop has been accumulating live at `state/<id>.md`.
 		else if (opts.job && (t === "--prompt" || t === "--schedule")) {

package/src/browser-open.ts

@@ -0,0 +1,169 @@
+/**
+ * Which command opens a browser here, and whether one did. The table copies pi's own opener (macOS
+ * `open`, Windows `rundll32`) and adds the WSL branch pi lacks: there `xdg-open` finds no browser and
+ * exits 3 after five seconds, so the Windows side is asked directly, with pi's Windows opener. "Opened" comes from the exit
+ * code, never from the spawn alone: a terminal that says it opened a browser when nothing opened
+ * leaves a person waiting for a window that never comes.
+ */
+
+import { spawn } from "node:child_process";
+import * as os from "node:os";
+import { pathToFileURL } from "node:url";
+
+/**
+ * One command to try: what to run, from where, which exit codes mean the browser got it, and how
+ * long it may run before still running counts as opened.
+ */
+export type Opener = { cmd: string; args: string[]; cwd?: string; okExit: number[]; waitMs: number };
+
+/** For an opener that exits as soon as it has handed the address on. */
+const QUICK_MS = 1_500;
+/** xdg-open that finds no browser exits 3 after about five seconds. */
+const XDG_OPEN_MS = 10_000;
+
+/** What the choice depends on, passed in so a test can be any machine. */
+export type OpenEnv = { platform: NodeJS.Platform; release: string; env: NodeJS.ProcessEnv };
+
+/** ssh and mosh set at least one of these; opening a browser on the far end helps nobody. */
+export function isRemoteTty(env: NodeJS.ProcessEnv = process.env): boolean {
+	return ["SSH_CONNECTION", "SSH_CLIENT", "SSH_TTY", "MOSH_CONNECTION"].some((k) => !!env[k]);
+}
+
+function isWsl(e: Pick<OpenEnv, "platform" | "release" | "env">): boolean {
+	return e.platform === "linux" && (!!e.env.WSL_DISTRO_NAME || /microsoft/i.test(e.release));
+}
+
+/** The commands to try in order, or why none is tried. */
+export function openerFor(e: OpenEnv & { target: string }): Opener[] | "no-display" | "remote" {
+	if (isRemoteTty(e.env)) return "remote";
+	const t = e.target;
+	if (e.platform === "darwin") return [{ cmd: "open", args: [t], okExit: [0], waitMs: QUICK_MS }];
+	// No shell: cmd would read `&` in the address as the end of the command.
+	if (e.platform === "win32") return [{ cmd: "rundll32", args: ["url.dll,FileProtocolHandler", t], okExit: [0], waitMs: QUICK_MS }];
+	// Both start from a Windows drive: a long \\wsl.localhost cwd breaks them. Not wslview: wslu 3.2.3
+	// reads a wsl.localhost address as a relative Linux path and exits 0 without opening anything. Not
+	// explorer.exe: it exits 1 whether or not anything opened. rundll32 exits 0 even for a missing
+	// file, so cmd.exe is reached only when rundll32.exe cannot start.
+	if (isWsl(e))
+		return [
+			{ cmd: "rundll32.exe", args: ["url.dll,FileProtocolHandler", t], cwd: "/mnt/c", okExit: [0], waitMs: QUICK_MS },
+			// cmd re-reads its line: `^` escapes the characters it would act on.
+			{ cmd: "cmd.exe", args: ["/c", "start", "", t.replace(/[\^&|]/g, "^$&")], cwd: "/mnt/c", okExit: [0], waitMs: QUICK_MS },
+		];
+	if (!e.env.DISPLAY && !e.env.WAYLAND_DISPLAY) return "no-display";
+	return [{ cmd: "xdg-open", args: [t], okExit: [0], waitMs: XDG_OPEN_MS }];
+}
+
+/**
+ * The address the opener is given for the launch file, which holds the one-use key so no argv does.
+ * On WSL the browser is a Windows one, which reads the file through `\\wsl.localhost`: measured on
+ * WSL 2 with rundll32 and `cmd.exe /c start`, each loads the file and follows it to the page.
+ * Undefined on WSL without `WSL_DISTRO_NAME`, which that address needs, and for a path holding a
+ * character Windows does not allow in a name: `\\wsl.localhost` shows those under other names, so
+ * the browser cannot find the file while rundll32 still exits 0.
+ */
+export function openFileTarget(file: string, e: Pick<OpenEnv, "platform" | "release" | "env">): string | undefined {
+	const href = pathToFileURL(file).href;
+	if (!isWsl(e)) return href;
+	const distro = e.env.WSL_DISTRO_NAME;
+	return distro && !/[\\:*?"<>|]/.test(file) ? `file://wsl.localhost/${encodeURIComponent(distro)}${href.slice("file://".length)}` : undefined;
+}
+
+/** This machine, as `openerFor` reads it. */
+export function thisMachine(): OpenEnv {
+	return { platform: process.platform, release: os.release(), env: process.env };
+}
+
+/**
+ * Hand `target` to each opener in turn until one takes it: true when one exits with a code it
+ * counts as success, or is still running at its own deadline, which is how a browser started
+ * straight from the opener looks. `waitMs` replaces every deadline, for a test.
+ */
+export async function openUrl(target: string, e: OpenEnv = thisMachine(), waitMs?: number): Promise<boolean> {
+	const openers = openerFor({ ...e, target });
+	if (typeof openers === "string") return false;
+	for (const opener of openers) if (await tryOpener(opener, e.env, waitMs ?? opener.waitMs)) return true;
+	return false;
+}
+
+function tryOpener(o: Opener, env: NodeJS.ProcessEnv, waitMs: number): Promise<boolean> {
+	return new Promise((resolve) => {
+		let child: ReturnType<typeof spawn>;
+		try {
+			child = spawn(o.cmd, o.args, { stdio: "ignore", detached: true, cwd: o.cwd, env });
+		} catch {
+			resolve(false); // the next opener, or the printed link
+			return;
+		}
+		const timer = setTimeout(() => {
+			child.unref();
+			resolve(true);
+		}, waitMs);
+		child.once("error", () => {
+			clearTimeout(timer);
+			resolve(false);
+		});
+		child.once("exit", (code) => {
+			clearTimeout(timer);
+			resolve(code !== null && o.okExit.includes(code));
+		});
+	});
+}
+
+/** One command that copies its stdin to the clipboard and exits 0 when it has. */
+export type CopyCommand = { cmd: string; args: string[]; cwd?: string };
+
+/**
+ * The clipboard commands to try in order, the ones pi's `copyToClipboard` runs. Not OSC 52, which
+ * pi also writes and which no terminal confirms: tmux in Windows Terminal drops it, so a terminal
+ * that said "copied" after it could be wrong. None over ssh or mosh, where this machine's clipboard
+ * is not the one in front of you.
+ */
+export function copyCommandsFor(e: OpenEnv): CopyCommand[] {
+	if (isRemoteTty(e.env)) return [];
+	if (e.platform === "darwin") return [{ cmd: "pbcopy", args: [] }];
+	if (e.platform === "win32") return [{ cmd: "clip", args: [] }];
+	if (e.platform !== "linux") return [];
+	// The link is ASCII, so clip.exe reading it in the console code page changes nothing.
+	const windows = isWsl(e) ? [{ cmd: "clip.exe", args: [], cwd: "/mnt/c" }] : [];
+	return [
+		...windows,
+		...(e.env.WAYLAND_DISPLAY ? [{ cmd: "wl-copy", args: [] }] : []),
+		...(e.env.DISPLAY ? [{ cmd: "xclip", args: ["-selection", "clipboard"] }, { cmd: "xsel", args: ["--clipboard", "--input"] }] : []),
+	];
+}
+
+/** Copy `text` with the first command that takes it: true only when one exited 0. */
+export async function copyText(text: string, e: OpenEnv = thisMachine()): Promise<boolean> {
+	for (const c of copyCommandsFor(e)) if (await runCopy(c, text, e.env)) return true;
+	return false;
+}
+
+const COPY_WAIT_MS = 5_000;
+
+function runCopy(c: CopyCommand, text: string, env: NodeJS.ProcessEnv): Promise<boolean> {
+	return new Promise((resolve) => {
+		let child: ReturnType<typeof spawn>;
+		try {
+			// xclip and xsel stay behind to own the selection; "exit" is the command that answered.
+			child = spawn(c.cmd, c.args, { stdio: ["pipe", "ignore", "ignore"], cwd: c.cwd, env });
+		} catch {
+			resolve(false); // the next command
+			return;
+		}
+		const timer = setTimeout(() => {
+			child.kill();
+			resolve(false);
+		}, COPY_WAIT_MS);
+		child.once("error", () => {
+			clearTimeout(timer);
+			resolve(false);
+		});
+		child.once("exit", (code) => {
+			clearTimeout(timer);
+			resolve(code === 0);
+		});
+		child.stdin?.once("error", () => {}); // EPIPE from a command that exited first: its exit code decides
+		child.stdin?.end(text);
+	});
+}

package/src/cli-entry.mjs

@@ -7,6 +7,12 @@ import { register } from "node:module";
 import { importTs } from "./ts-entry.mjs";
 
 register("./pi-resolver.mjs", import.meta.url);
+// `pi-loops status | head` closes the pipe early: the reader has what it wanted, which is not an error.
+process.stdout.on("error", (err) => {
+	if (err?.code === "EPIPE") process.exit(process.exitCode ?? 0);
+	process.stderr.write(`pi-loops: ${err?.message ?? err}\n`);
+	process.exit(1);
+});
 let cli;
 try {
 	cli = await importTs(import.meta.url, "./cli.ts");
@@ -15,9 +21,12 @@ try {
 	process.stderr.write(`pi-loops: ${err?.message ?? err}\n`);
 	process.exit(1);
 }
+const argv = process.argv.slice(2);
 try {
-	process.exitCode = await cli.runCli(process.argv.slice(2));
+	process.exitCode = await cli.runCli(argv);
 } catch (err) {
-	process.stderr.write(`pi-loops: ${err?.message ?? err}\n\n${cli.CLI_USAGE}\n`);
-	process.exitCode = 1;
+	// Only a command typed wrong is answered with its usage; a missing file or a lock is not fixed by reading one.
+	const usage = err instanceof cli.UsageError;
+	process.stderr.write(`pi-loops: ${err?.message ?? err}\n${usage ? `\n${cli.usageFor(argv[0])}\n` : ""}`);
+	process.exitCode = usage ? 2 : 1;
 }