@alphacoder-v0/pi-loops 0.20.0 → 0.22.1

package/recipes/deps-sweeper/audit.md

@@ -0,0 +1,99 @@
+---
+name: deps-sweeper
+description: One run of the dependency sweeper. Runs the project's audit and outdated commands and reports each new advisory and each direct dependency a whole major behind; at propose, applies the patch and minor updates in a worktree, runs the project's checks and opens one pull request. Never applies a major; the same package failing twice is a stop.
+---
+
+# Sweep: one run
+
+Autonomy: report
+
+The line above is the installed level.
+- `report`: an advisory not in your notes, or a direct dependency a whole major behind, is a
+  finding; nothing is changed.
+- `propose`: additionally, you apply the patch and minor updates the package manager offers, in a
+  worktree, run the project's check command, and open **one** pull request. Merging stays with a
+  person. A major is still never applied.
+
+You are the dependency sweeper. Nobody is watching. Dependencies rot in two ways a person stops
+noticing: an advisory lands against a version the project pins, and a package moves on a major
+while the project stays behind. The first is worth a line the day it appears; the second is worth
+a line once. Most weeks there is nothing new, and then you write your notes and stop.
+
+## Never bump
+
+Packages a person has decided to hold, one per line, with the reason. Edit this list in place; it
+is read on every run, and a package on it is not updated at any level and not reported as behind.
+
+- *(none yet)*
+
+## What to do
+
+1. **Find the package manager** from the lockfile at the project root, and take the commands for
+   it: `package-lock.json` → `npm audit --json`, `npm outdated --json`, `npm update <pkg>`;
+   `pnpm-lock.yaml` → `pnpm audit --json`, `pnpm outdated --format json`, `pnpm update <pkg>`;
+   `yarn.lock` → `yarn npm audit --json` (or `yarn audit --json` for classic), `yarn outdated`,
+   `yarn upgrade <pkg>` for classic and `yarn up "<pkg>@<the range package.json has>"` for Berry
+   (a bare `yarn up <pkg>` jumps to latest, which can be a major); `Cargo.lock` → `cargo audit --json` and `cargo outdated --format json` if they
+   are installed, `cargo update -p <pkg>`; `uv.lock` / `poetry.lock` / `requirements*.txt` →
+   `pip-audit --format json` if installed, then `pip list --outdated --format json`, and the
+   manager's own update command. No lockfile, or the audit tool is not installed: one finding
+   saying which, notes unchanged, stop — installing tools is not yours to do. Never run an install
+   that writes outside the project or the worktree.
+
+2. **Audit.** Run the audit command and read the advisories. For each one whose id is **not** in
+   your notes: one finding, under 200 characters —
+
+   ```
+   advisory GHSA-xxxx-xxxx-xxxx: <package>@<installed> — <severity>, fixed in <version> (<title>)
+   ```
+
+   Then add the id to your notes. An advisory already in your notes is not a new finding; one
+   that has gone (the package was updated, the advisory withdrawn) is a line saying so, once, and
+   its id leaves your notes.
+
+3. **Outdated.** Run the outdated command and keep the **direct** dependencies whose latest
+   version is a whole major above the installed one. For each not in your notes at that major:
+   one finding, `<package> <installed> → <latest> (major; changelog: <url if the package names
+   one>) · waits: your decision to take the major · if not: not reported again until the next
+   major`, and record the package with the major you reported. The same gap is not repeated the
+   next week; a gap that moved to a new major is a new finding. Skip anything under **Never bump**.
+
+4. **`propose`:** the patch and minor updates. If your notes say a package was attempted **twice**
+   already without a green check, leave it out and file `deps: <package> — two attempts did not
+   pass the checks · waits: a person · if not: left out of every later pull request`. Otherwise:
+   - `git fetch origin` and `git worktree add ../<repo>-deps/<YYYY-MM-DD> -b deps/<YYYY-MM-DD>
+     origin/<default branch>`; do everything below in that worktree.
+   - Install there, then apply the updates with the package manager's own update command, patch
+     and minor only, skipping **Never bump** and anything in your notes' stop list. Never edit the
+     lockfile by hand and never change a version range's shape (a caret stays a caret).
+   - Run the project's check command (the one its `AGENTS.md`, `package.json` scripts or CI
+     workflow names). Green → commit `chore: update dependencies (<n> packages)` with the list in
+     the body, push `-u`, and open the pull request with a body that starts with a line saying it
+     was generated by AI, lists each package `old → new`, and names any advisory it closes.
+     Finding: `deps PR opened: <n> updates (<the notable ones>) — <url>`.
+     Not green → bisect once by reverting the updates to the package the failing check names (or
+     half of them, if it names none) and run the checks again; a package whose update alone makes
+     them red is recorded as attempted in your notes and left out of this pull request. Still red
+     with every update reverted: the branch is red on its own, that is the CI sweeper's problem —
+     commit nothing, remove the worktree, finding `deps: checks are red on <default branch>
+     without any update; nothing applied`.
+   - If a pull request of yours is already open and unmerged, update its branch instead of
+     opening a second one; if it was closed without merging, do not reopen it this run — a finding
+     says a person closed it, and the packages it carried go on the stop list.
+
+5. **Housekeeping.** A worktree of yours whose pull request is merged or closed is removed and its
+   branch deleted. Advisories closed by a merged pull request leave your notes.
+
+## Notes for the next run
+
+`watermark=<ISO with offset>` · `advisories: <id> <id> …` · `majors-reported: <package>@<major> …`
+· `attempted: <package> ×<n> …` · `open-pr=<url or none>` · `worktree=<path or none>`. Under 2000
+characters; when the advisory list grows past that, keep the open ones and say `older ones in the
+merged PRs`.
+
+## Never
+
+Never apply a major version, never touch a package under **Never bump**, never edit a lockfile by
+hand, never push to the default branch, never force-push, never merge, never touch a branch you did
+not create. Never disable an audit
+rule, an audit level, or a check to get to green — that is a finding, not a fix.

package/recipes/deps-sweeper/recipe.toml

@@ -0,0 +1,17 @@
+# deps-sweeper: new advisories and major-version gaps reported; patch and minor updates applied in a
+# 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."
+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
+levels = ["report", "propose"]
+needs = ["lockfile"]
+needs_propose = ["gh", "git-remote"]
+budget_hint_usd = 5
+
+[[job]]
+name = "deps-sweeper"
+schedule = "0 8 * * 1"
+playbook = "audit.md"
+timeout = "40m"

package/recipes/ecosystem/recipe.toml

@@ -1,8 +1,11 @@
 # 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."
+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
 levels = ["propose"]
+needs = ["gh"]
 budget_hint_usd = 2
 
 [[job]]

package/recipes/ecosystem/scan.md

@@ -39,7 +39,7 @@ It names this repository; the searches below take that name.
 4. **Findings**, one per draft, under 500 characters:
 
    ```
-   ecosystem: <repo> — <what they did/hit>; draft reply for <url>: "<the text, ready to post>"
+   ecosystem: <repo> — <what they did/hit>; draft reply for <url>: "<the text, ready to post>" · waits: you, to send it by claiming · if not: never sent, not drafted again
    ```
 
    A person claims the finding to send it (the claim hands the draft to the agent in their chat,

package/recipes/issue-loop/implement.md

@@ -33,7 +33,10 @@ Do these in order; stop after the first that produces a full run's work.
    review state is `CHANGES_REQUESTED`, or that has a comment by a person newer than the
    timestamp in your notes: check out its worktree, address every point (reply to each comment
    saying what you did, or why not), run the project's checks, push, and re-request review.
-   Report: `#<n> review feedback addressed — PR <url>`.
+   Report: `#<n> review feedback addressed — PR <url>`. With a local Markdown tracker there is no
+   pull request: the feedback is a comment under the item's `## Comments` newer than your notes'
+   timestamp, and the person has set the item back to `agent-working`; address it on the branch
+   and set `in-review` again.
 3. **One new issue.** The frontier is the open issues labeled `ready-for-agent` with no assignee
    whose blockers are all closed (a `Blocked by: #m` line in the body or brief, or the tracker's
    native dependency). Take the **oldest one**. One per run — a second one waits for the next run.
@@ -95,8 +98,9 @@ branch and worktree path to your notes **now**, before any implementation, so a
   gh issue edit <n> --add-label in-review --remove-label agent-working
   ```
 
-  Report: `#<n> PR opened — <url> (<k> commits, checks green)`. The maintainer merges; the
-  `Closes` line closes the issue.
+  Report: `#<n> PR opened — <url> (<k> commits, checks green) · waits: your review · if not:
+  stays in-review; I address review comments and re-request, and do not nudge`. The maintainer
+  merges; the `Closes` line closes the issue.
 
 ## Blocked
 
@@ -108,7 +112,8 @@ gh issue edit <n> --add-label agent-blocked --remove-label agent-working
 ```
 
 Comment with the specific question or the specific failure (command and output), the branch, and
-what you would do next given an answer. Report: `#<n> blocked — <one-line reason>`. The
+what you would do next given an answer. Report: `#<n> blocked — <one-line reason> · waits: your
+answer on the issue · if not: untouched; other ready-for-agent issues still get built`. The
 maintainer answers, edits the brief if needed, and moves the issue back to `ready-for-agent`; do
 not touch an `agent-blocked` issue again until they do.
 
@@ -133,3 +138,11 @@ tracker has the rest.
 
 One line per state change you made, in the shapes above. Housekeeping produces no inbox lines. A
 run that only resumed and is still working produces none either.
+
+## Never
+
+Never push to the default branch, never force-push, never rebase a branch someone has reviewed.
+Never merge: the pull request — or, with a local tracker, the branch — waits for a person at
+every level. Never make a third attempt at a check command that failed twice on the same issue.
+Never touch an `agent-blocked` issue until a person has moved it back to `ready-for-agent`.
+Never post a comment without the line saying it was generated by AI.

package/recipes/issue-loop/labels.sh

@@ -2,8 +2,26 @@
 # The labels the issue loop moves issues through. Idempotent: --force updates the colour and
 # description of a label that already exists and never touches the issues carrying it.
 # Run inside a clone of the repository (gh infers the repository from the remote).
+#
+# Labels are GitHub's: a local Markdown tracker (docs/agents/issue-tracker.md naming
+# .scratch/issues/) has none to create, and a GitHub tracker without a working `gh` gets its
+# labels later — the first run reports the missing CLI as a finding. Neither stops the install.
 set -e
 
+tracker="docs/agents/issue-tracker.md"
+if [ -f "$tracker" ] && grep -q '\.scratch/issues' "$tracker"; then
+  echo "local Markdown tracker ($tracker): no labels to create"
+  exit 0
+fi
+if ! command -v gh >/dev/null 2>&1; then
+  echo "gh is not on the PATH: no labels created; install the GitHub CLI and run this script by hand, or let the first run report it"
+  exit 0
+fi
+if ! gh auth status >/dev/null 2>&1; then
+  echo "gh is not logged in: no labels created; run 'gh auth login' and this script by hand, or let the first run report it"
+  exit 0
+fi
+
 lab() { gh label create "$1" --description "$2" --color "$3" --force >/dev/null && echo "  $1"; }
 
 echo "category labels"

package/recipes/issue-loop/recipe.toml

@@ -1,6 +1,8 @@
 # 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."
+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
 levels = ["propose", "act"]
 setup = "labels.sh"

package/recipes/issue-loop/triage.md

@@ -74,9 +74,12 @@ instead (the states and the checkpoints are the same).
 4. **Apply the outcome.**
    - **Fully specified and verified** → post an *Agent Brief* (template below), make sure the
      labels are `needs-triage` plus the category, and report to the inbox:
-     `#<n> brief posted — recommend ready-for-agent (<category>, <verified how>)`.
+     `#<n> brief posted — recommend ready-for-agent (<category>, <verified how>) · waits: the
+     implement loop skips it until labeled · if not: stays needs-triage, no reminder`.
    - **Needs a person** (design decision, external access, manual testing, taste) → post the brief
-     anyway with a line saying why it cannot be delegated; recommend `ready-for-human`.
+     anyway with a line saying why it cannot be delegated; recommend `ready-for-human`:
+     `#<n> brief posted — recommend ready-for-human (<why>) · waits: a person · if not: stays
+     needs-triage`.
    - **Not enough to act on** → post *Triage Notes* (template below) with specific questions,
      move to `needs-info`, report: `#<n> → needs-info (asked: <one phrase per question>)`.
    - **Already implemented** → say where it lives in a comment; recommend `wontfix (already
@@ -86,6 +89,10 @@ instead (the states and the checkpoints are the same).
    - **Reporter replied on a `needs-info` issue** → move it back to `needs-triage` and evaluate
      it again from step 2 in this same run.
 
+   Every recommendation you report is a checkpoint, and the shape is fixed: the recommendation,
+   then ` · waits: <what the label unblocks> · if not: <what stays as it is>`. Under `act`, the
+   moves you make yourself are reported as news, without the two clauses.
+
    Labels: `gh issue edit <n> --add-label "<state>" --remove-label "<old state>"`. Never leave an
    issue with two state labels. Under `propose`, never close an issue.
 
@@ -145,3 +152,10 @@ the oldest `needs-info` lines; the tracker still has everything.
 
 One line per issue you acted on, in the shapes above. No issues needing attention → no inbox
 lines. A finding is a decision for the maintainer, so it carries the recommendation and the reason.
+
+## Never
+
+Never edit code, open a branch or a worktree, or touch an issue in `ready-for-agent`,
+`agent-working`, `in-review` or `agent-blocked`. Never leave an issue with two state labels.
+Never close an issue under `propose`; under `act`, never close anything but an already-implemented
+request or a duplicate. Never post a comment without the line saying it was generated by AI.

package/recipes/pr-watch/recipe.toml

@@ -1,8 +1,11 @@
 # 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."
+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
 levels = ["report", "propose"]
+needs = ["gh", "tracker-github"]
 budget_hint_usd = 2
 
 [[job]]

package/skills/pi-loops/SKILL.md

@@ -17,7 +17,7 @@ The user's pi has pi-loops installed. Prefer its tools over ad-hoc `sleep` loops
 | 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 |
 | a reminder in N minutes | `cron_create` with schedule `in 10m` |
-| run the project's issue tracker as a standing process (triage, build, review), or an experiment loop against a research contract | tell the user to run `/recipe list` and `/recipe add <name>` — a packaged set of loops installed with one confirmation; do not recreate it with `cron_create` |
+| run the project's issue tracker as a standing process (triage, build, review), an experiment loop against a research contract, a CI or dependency sweeper, a PR watch, a daily digest | tell the user to run `/recipe list` and `/recipe add <name>` — a packaged set of loops installed with one confirmation; do not recreate it with `cron_create` |
 
 Never use `new_trigger` for time-based schedules; never use `cron_create` for conditions.
 
@@ -42,7 +42,8 @@ reported in your notes; report only new or newly closed issues". Findings should
 
 ## Triage
 
-`/inbox` lists findings; `/inbox claim <n>` hands one to you as a real turn; `/inbox dismiss <n>`.
+`/inbox` lists findings; `/inbox claim <n>` hands one to you as a real turn; `/inbox dismiss <n> [reason]`
+(a reason is shown to the loop's next run, so a finding the user calls noise can say why).
 `/cron` lists jobs, `/cron runs`, `/cron trace <job> [k]` shows what a run did. `/triggers rules`,
 `/triggers audit` for dynamic triggers.
 

package/src/archive.ts

@@ -17,11 +17,12 @@ 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 { LOOP_STATE_MAX_CHARS, capChars } from "./protocol.ts";
 import { previewRedacted } from "./redact.ts";
 import { computeNext, formatSchedule, isValidSchedule, stamp } from "./schedule.ts";
-import { newId, type LoopJob } from "./store.ts";
-import { type DynamicTriggerRule, newRuleId } from "./triggers.ts";
+import { type JobStore, newId, type LoopJob } from "./store.ts";
+import { type DynamicTriggerRule, type TriggerStore, newRuleId } from "./triggers.ts";
 
 export const ARCHIVE_SCHEMA = "pi-loops.session_export.v1";
 export const ARCHIVE_EXT = ".pisession";
@@ -182,6 +183,24 @@ export function defaultExportPath(cwd: string, sessionId: string): string {
 	return path.join(cwd, `pi-session-${sessionId.slice(0, 16)}${ARCHIVE_EXT}`);
 }
 
+/**
+ * What an export of `sessionId` in `cwd` carries: this project's automation, narrowed to what that
+ * session created.
+ *
+ * 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
+ * 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[] } {
+	const mine = (owner: { sessionId?: string } | undefined, ownerCwd: string): boolean => (owner?.sessionId ? owner.sessionId === sessionId : sameProject(ownerCwd, cwd));
+	return {
+		jobs: jobs.filter((j) => sameProject(j.cwd, cwd) && mine(j.createdBy, j.cwd)),
+		rules: rules.filter((r) => sameProject(r.cwd, cwd) && mine(r.createdBy, r.cwd)),
+	};
+}
+
 export function exportSession(input: ExportInput): ExportSummary {
 	const sessionBytes = fs.readFileSync(input.sessionFile);
 	if (sessionBytes.length > MAX_SESSION_BYTES) throw new Error("session file exceeds the 50 MiB archive cap");
@@ -437,6 +456,82 @@ export function importSession(input: ImportInput): ImportSummary {
 	};
 }
 
+/**
+ * What `--activate-triggers` says about the automation an archive carries: leave it off and say
+ * nothing (`off`), ask once after the import whether to switch back on what the source had on
+ * (`ask`, the default), or activate it as part of the import (`on`).
+ */
+export type ActivateMode = "off" | "ask" | "on";
+
+/** `--activate-triggers=X` and `--activate-triggers X`, wherever either is typed. */
+export function parseActivateMode(value: string | undefined): ActivateMode {
+	if (value === undefined) return "ask";
+	if (value === "off" || value === "ask" || value === "on") return value;
+	throw new Error(`--activate-triggers must be off, ask or on (got ${value})`);
+}
+
+/**
+ * Commit an import to the stores: jobs, then their loop state, then rules.
+ *
+ * A write that fails part way is rolled back — the imported session file, the imported jobs and
+ * their state files go, and the original error is rethrown — because the alternative is a store
+ * holding half an archive: jobs whose rules never arrived, or a session file nothing points at.
+ * The rollback is best effort by construction; the failure it is undoing is usually a store that
+ * cannot be written.
+ */
+export async function applyImport(imp: ImportSummary, jobStore: JobStore, triggerStore: TriggerStore): Promise<void> {
+	try {
+		if (imp.jobs.length) await jobStore.mutate((jobs) => ({ jobs: [...jobs, ...imp.jobs], result: undefined }));
+		for (const [id, text] of Object.entries(imp.states)) jobStore.writeState(id, text);
+		if (imp.rules.length) await triggerStore.mutate((rules) => rules.push(...imp.rules));
+	} catch (err) {
+		const ids = new Set(imp.jobs.map((j) => j.id));
+		const attempt = (fn: () => void) => {
+			try {
+				fn();
+			} catch {
+				/* best effort */
+			}
+		};
+		attempt(() => fs.rmSync(imp.sessionPath, { force: true }));
+		await jobStore.mutate((jobs) => ({ jobs: jobs.filter((j) => !ids.has(j.id)), result: undefined })).catch(() => {});
+		for (const id of ids) attempt(() => fs.rmSync(jobStore.statePath(id), { force: true }));
+		throw err;
+	}
+}
+
+/**
+ * What `ask` means: after an import that did not activate, offer once to switch back on what the
+ * source session had on, and do it if the answer is yes. Returns what was enabled.
+ *
+ * `confirm` is the caller's way of asking — a TUI dialog, a terminal prompt — and a caller with
+ * nobody to ask passes nothing, which is the same as no. `onJobEnabled` is the hook the extension
+ * uses to keep its cron audit trail; nothing else needs it.
+ */
+export async function offerToEnable(
+	imp: ImportSummary,
+	jobStore: JobStore,
+	triggerStore: TriggerStore,
+	confirm?: (question: string, detail: string) => boolean | Promise<boolean>,
+	onJobEnabled?: (before: LoopJob, after: LoopJob) => void,
+): Promise<{ jobs: number; rules: number }> {
+	const none = { jobs: 0, rules: 0 };
+	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?`);
+	if (!ok) return none;
+	for (const id of imp.originallyEnabledJobs) {
+		const before = jobStore.load().find((j) => j.id === id);
+		const after = await jobStore.update(id, (j) => {
+			j.enabled = true;
+		});
+		if (before && after) onJobEnabled?.(before, after);
+	}
+	for (const id of imp.originallyEnabledRules) await triggerStore.setEnabled(id, true);
+	return { jobs: imp.originallyEnabledJobs.length, rules: imp.originallyEnabledRules.length };
+}
+
 /**
  * Recognises automation this store already imported from the same archive. Without it, importing an
  * archive twice leaves two live copies of every job and rule, each running and each billing.