pi-goal-list-loop-audit 0.29.23 → 0.31.0

package/extensions/goal-loop-forever.ts

@@ -478,6 +478,75 @@ export function countOpenAuditFindings(cwd: string): number {
  * reasonable answers exist) are presented, never touched. DECIDE lines use
  * "- [?]" so they never inflate the loop's open-findings measure.
  */
+/** v0.31.0: /list audit — the collect-then-drain audit (user design
+ * 2026-07-31: "this command could run a project audit, collect a bunch of
+ * tasks, then do them all too"). Division of labor:
+ *   /goal audit — one audited unit: audit + fix in the SAME pass (small scopes).
+ *   /list audit — audit once, then every open finding becomes its own queued,
+ *                 individually-audited list item (the actionables stop living
+ *                 only inside findings.md — the user's "audits don't make a
+ *                 list of actionables" pain).
+ *   /loop audit — forever fix-first cadence for living codebases.
+ * The collection item FIXES NOTHING: every fix lands as its own list item with
+ * its own isolated audit trail. DECIDE findings are presented at collection
+ * completion, never queued — a decision is not a task (the agent can't "do" it).
+ * The marker survives restarts inside the objective itself (no schema change):
+ * the completion fan-out matches on it.
+ */
+export const LIST_AUDIT_COLLECT_MARKER = "[LIST-AUDIT-COLLECT]";
+
+export function listAuditCollectTarget(focus?: string): string {
+  const scope = focus && focus.trim() ? focus.trim() : "the whole project";
+  return `${LIST_AUDIT_COLLECT_MARKER} Run ONE project audit pass that COLLECTS work — the follow-up fixes are queued as separate list items, so this pass changes no code. Scope: ${scope}. (1) Run a FRESH audit pass over the codebase — spawn Explore subagents for breadth — hunting real problems: bugs, broken flows, regressions, drift between docs and code, dead code, security holes. Not style nits, not speculative refactors. (2) Append every NEW finding to ${AUDIT_FINDINGS_REL} (create the file on the first finding; append-only — never delete, rewrite, or reorder existing lines; never re-report a finding already listed), classified: "- [ ] FIX: SEVERITY: short description (file:line)" for bugs and polish — and "- [?] DECIDE: short description (what the choice is, what each side costs)" for direction, trade-offs, and scope questions where two reasonable answers exist. (3) Change NOTHING — no fixes, no refactors, no drive-by edits: the orchestrator queues each open FIX finding as its own list item after this pass completes, and each fix lands with its own commit and its own audit. (4) DECIDE findings are listed in the completion report — they are presented to the user, never queued and never silently fixed. (5) Honesty law: never fabricate findings to look busy; if the pass is genuinely clean, say so plainly — an empty findings set is a success, not a failure. Done when: the audit pass is complete and every finding it surfaced is appended to ${AUDIT_FINDINGS_REL} with the right classification (or the report states plainly that nothing was found).`;
+}
+
+/** One parsed open finding from the audit findings file. */
+export interface AuditFindingLine {
+  /** Raw finding text with the checkbox + optional "FIX:" prefix stripped. */
+  text: string;
+  /** Severity rank for sorting: 0 = CRITICAL … 4 = unclassified. */
+  rank: number;
+}
+
+const AUDIT_SEVERITY_ORDER = ["CRITICAL", "HIGH", "MEDIUM", "LOW"];
+
+/** v0.31.0: parse findings.md into the fan-out shape — OPEN boxes become
+ * actionable findings (severity-sorted, stable within a rank), DECIDE boxes
+ * ("- [?]") are returned separately for presentation (never queued). Tolerates
+ * the /loop audit format (no "FIX:" prefix): any open box that isn't a
+ * decision is actionable.
+ */
+export function parseAuditFindingsForFanout(md: string): { open: AuditFindingLine[]; decisions: string[] } {
+  const open: AuditFindingLine[] = [];
+  const decisions: string[] = [];
+  md.split("\n").forEach((line, idx) => {
+    const decide = line.match(/^\s*-\s*\[\?\]\s*(.*)$/);
+    if (decide) {
+      const text = (decide[1] ?? "").replace(/^DECIDE:\s*/i, "").trim();
+      if (text) decisions.push(text);
+      return;
+    }
+    const box = line.match(/^\s*-\s*\[ \]\s*(.*)$/);
+    if (!box) return;
+    const text = (box[1] ?? "").replace(/^FIX:\s*/i, "").trim();
+    if (!text) return;
+    const sev = text.match(/^([A-Z]+)\s*:/);
+    const rank = sev ? AUDIT_SEVERITY_ORDER.indexOf(sev[1]!) : -1;
+    open.push({ text, rank: rank >= 0 ? rank : AUDIT_SEVERITY_ORDER.length + (idx / 100000) });
+  });
+  // Severity first; stable within a rank (file order) via the fractional idx.
+  open.sort((a, b) => a.rank - b.rank);
+  return { open, decisions };
+}
+
+/** v0.31.0: the list-item text for one finding — short objective + a checkable
+ * Done when (the fix commit exists AND the box is checked with its hash, so
+ * findings.md stays honest as the drain proceeds).
+ */
+export function listAuditFanoutItemText(finding: string): string {
+  return `Fix audit finding: ${finding} — Done when: the fix is committed on the current branch with the repo's configured identity, and this finding's box in ${AUDIT_FINDINGS_REL} is checked ("- [x] … — fixed in <commit>").`;
+}
+
 export function projectAuditTarget(focus?: string): string {
   const scope = focus && focus.trim() ? focus.trim() : "the whole project";
   return `Run ONE project audit pass and leave the project in a known state. Scope: ${scope}. (1) Run a FRESH audit pass over the codebase — spawn Explore subagents for breadth — hunting real problems: bugs, broken flows, regressions, drift between docs and code, dead code, security holes. Not style nits, not speculative refactors. (2) Append every NEW finding to ${AUDIT_FINDINGS_REL} (create the file on the first finding; append-only — never delete, rewrite, or reorder existing lines; never re-report a finding already listed), classified: "- [ ] FIX: SEVERITY: short description (file:line)" for bugs and polish — whether to fix these is NOT a decision — and "- [?] DECIDE: short description (what the choice is, what each side costs)" for direction, trade-offs, and scope questions where two reasonable answers exist. (3) Fix every NEW FIX finding from this pass — real fixes, committed with the repo's configured identity on the current branch (no invented identities or branches) — then check the box: "- [x] … — fixed in <commit>". (4) Change NOTHING for DECIDE findings — present them in the completion report instead. (5) Honesty law: never fabricate findings to look busy; never check a box without the fix commit existing; never silently turn a DECIDE into a fix. Done when: the audit pass is complete, every new FIX finding has a fix commit and a checked box in ${AUDIT_FINDINGS_REL}, and every DECIDE finding is listed in the file and presented in the completion report.`;

package/extensions/loops/goal.ts

@@ -175,6 +175,10 @@ import {
   countOpenAuditFindings,
   AUDIT_FINDINGS_REL,
   projectAuditTarget,
+  LIST_AUDIT_COLLECT_MARKER,
+  listAuditCollectTarget,
+  parseAuditFindingsForFanout,
+  listAuditFanoutItemText,
   type LoopTickOutcome,
   HELD_ON_RESTORE,
   type LoopState,
@@ -225,6 +229,72 @@ let extensionApiStale = false;
  * here stranded goals until manual /goal resume (hegemon/sraaal shape).
  * sendContinuation's extensionApiStale guard already stops further sends
  * in this doomed process; the next fresh session auto-resumes. */
+/** v0.30.0: rebind-first session-replacement survival. pi's sanctioned
+ * pattern (docs/extensions.md lifecycle + the stale error text itself):
+ * session_shutdown → cleanup, session_start → re-establish with the NEW
+ * ctx. glla used to treat every stale handle as terminal ("run /reload"),
+ * but three replacement shapes need three responses:
+ *  (a) switch (resume/new/fork): pi rebinds THIS module to the new
+ *      session — session_start delivers a fresh ctx. No user action, no
+ *      warning; reset the stale flag via a re-probe and continue.
+ *  (b) /reload: pi re-imports the extension modules — a SUCCESSOR
+ *      instance owns this cwd in the same process. The old module stands
+ *      down silently (owner-file check) instead of screaming + injecting
+ *      /reload (v0.29.22's injection is right for orphans, wrong here).
+ *  (c) orphan: the session died with NO replacement (hegemon 2026-07-31:
+ *      handle dead ~06:03, zero ledger events for 5h). Only a rebuild
+ *      revives extension function — goStaleTerminal's warning + self-heal
+ *      stays for this case ONLY.
+ * session_shutdown is now ledgered with pi's reason, so the next
+ * unexplained disposal is attributable from the ledger alone. */
+const SESSION_REBIND_GRACE_MS = 60_000;
+let sessionReplacementUntil = 0;
+const instanceStartedAt = Date.now();
+const instanceId = `${process.pid}:${instanceStartedAt}`;
+let zombieStoodDown = false;
+
+function ownerFilePath(cwd: string): string {
+  return path.join(cwd, ".pi-glla", "owner.json");
+}
+
+function writeOwnerFile(cwd: string): void {
+  try {
+    fs.mkdirSync(path.join(cwd, ".pi-glla"), { recursive: true });
+    fs.writeFileSync(ownerFilePath(cwd), JSON.stringify({ instanceId, pid: process.pid, at: Date.now() }));
+  } catch {
+    /* owner file is advisory — never block activation on it */
+  }
+}
+
+function readOwnerFile(cwd: string): { instanceId?: string; pid?: number; at?: number } | null {
+  try {
+    return JSON.parse(fs.readFileSync(ownerFilePath(cwd), "utf8")) as { instanceId?: string; pid?: number; at?: number };
+  } catch {
+    return null;
+  }
+}
+
+/** A stale probe is terminal only for ORPHANS. Returns true when the
+ * stale sighting was absorbed (a rebind window is open, or a successor
+ * instance owns this cwd and we stand down silently), false when the
+ * caller should go terminal (orphan — no replacement came). */
+function absorbStaleIfSuperseded(ctx: ExtensionContext): boolean {
+  if (Date.now() < sessionReplacementUntil) {
+    appendLedger(ctx.cwd, "stale_awaiting_rebind", {});
+    return true;
+  }
+  const owner = readOwnerFile(ctx.cwd);
+  if (owner && owner.pid === process.pid && typeof owner.instanceId === "string" && owner.instanceId !== instanceId) {
+    appendLedger(ctx.cwd, "zombie_stood_down", { owner: owner.instanceId });
+    zombieStoodDown = true;
+    extensionApiStale = true; // silence the send paths WITHOUT the terminal theatre
+    clearLoopTimer();
+    if (continuationTimer) { clearTimeout(continuationTimer); continuationTimer = null; }
+    return true;
+  }
+  return false;
+}
+
 function goStaleTerminal(ctx: ExtensionContext, where: string): void {
   if (extensionApiStale) return; // already terminal — don't re-spam
   extensionApiStale = true;
@@ -325,6 +395,13 @@ function probeExtensionApiStale(): boolean {
  * and must NOT claim work started (S3's "created — starting now" lie). */
 function warnIfStaleAtEntry(ctx: ExtensionContext, what: string): boolean {
   if (!probeExtensionApiStale()) return false;
+  // v0.30.0: a successor may already own this session (e.g. /reload
+  // re-imported the modules) — the user's command belongs to the fresh
+  // instance; say so softly instead of demanding a reload.
+  if (absorbStaleIfSuperseded(ctx)) {
+    ctx.ui.notify(`glla: a refreshed instance owns this session — ${what} is handled there; nothing to do.`, "info");
+    return true;
+  }
   appendLedger(ctx.cwd, "extension_api_stale", { where: `entry probe (${what})` });
   ctx.ui.notify(
     `glla: this session's extension handle is stale (pi session replacement) — ${what} can't send continuations in this process. State is safe in .pi-glla/ — run /reload (extensions rebuild in place), then /glla resume. Restart pi only if /reload fails.`,
@@ -693,6 +770,7 @@ function escalateStallNow(ctx: ExtensionContext, threshold: number): boolean {
 }
 
 function heartbeatTick(): void {
+  if (zombieStoodDown) return; // v0.30.0: a superseded instance stays silent forever
   const ctx = freshCtx();
   if (!ctx) return;
   let idle = false;
@@ -717,7 +795,12 @@ function heartbeatTick(): void {
   // on: refiring into a dead process is misleading, and worse, the stall
   // escalation would PAUSE the goal — silently cancelling the
   // interruptedAt → hold-on-restart promise the footer shows.
-  if (probeExtensionApiStale()) { goStaleTerminal(ctx, "heartbeat probe"); return; }
+  if (probeExtensionApiStale()) {
+    // v0.30.0: stale ≠ terminal — absorb the rebind-window and
+    // successor-instance cases; only orphans go terminal.
+    if (!absorbStaleIfSuperseded(ctx)) goStaleTerminal(ctx, "heartbeat probe");
+    return;
+  }
   // v0.29.16: zombie-run watchdog. pi reports BUSY (a run is "active") but
   // zero stream events for 20 min = the provider stream hung silently —
   // queued continuations can't land, and every other watchdog stays quiet
@@ -1149,6 +1232,62 @@ function autoArbitrateStackedState(ctx: ExtensionContext): void {
   );
 }
 
+/** v0.31.0: /list audit completion fan-out — read the audit findings file,
+ * queue every OPEN finding as its own list item (severity-sorted, deduped
+ * against the live queue), present DECIDE findings without queueing them.
+ * Confirm-gated like every bulk import (v0.23.7: the user reads what lands
+ * in the queue); a decline leaves the findings open for a later re-run.
+ */
+async function fanOutListAuditFindings(ctx: ExtensionContext): Promise<void> {
+  let md = "";
+  try {
+    md = fs.readFileSync(path.join(ctx.cwd, AUDIT_FINDINGS_REL), "utf-8");
+  } catch {
+    /* no findings file — the audit was clean or never wrote */
+  }
+  const { open, decisions } = parseAuditFindingsForFanout(md);
+  // Dedupe against the live queue (a re-run must not double-queue a finding
+  // that's already waiting) — match on the finding text's first 60 chars.
+  const queuedText = listQueue().map((i) => i.objective).join("\n");
+  const fresh = open.filter((f) => !queuedText.includes(f.text.slice(0, 60)));
+  const alreadyQueued = open.length - fresh.length;
+  const decideNote =
+    decisions.length > 0
+      ? `\n${decisions.length} DECIDE finding(s) need YOU (not queued — a decision is not a task):\n` +
+        decisions.slice(0, 10).map((d) => `  ? ${d.slice(0, 110)}`).join("\n")
+      : "";
+  if (fresh.length === 0) {
+    ctx.ui.notify(
+      open.length > 0
+        ? `Audit collected ${open.length} open finding(s) — all already queued.${decideNote}`
+        : `Audit complete — no open findings; the project is clean, nothing to queue.${decideNote}`,
+      "info",
+    );
+    appendLedger(ctx.cwd, "list_audit_fanout_empty", { open: open.length, decisions: decisions.length });
+    return;
+  }
+  const preview = fresh.map((f, i) => `  ${i + 1}. ${f.text.slice(0, 110)}`).join("\n");
+  let confirmed = true;
+  if (ctx.hasUI) {
+    try {
+      confirmed = await ctx.ui.confirm(`Queue ${fresh.length} audit finding(s) as list items?`, preview);
+    } catch {
+      confirmed = false;
+    }
+  }
+  if (!confirmed) {
+    appendLedger(ctx.cwd, "list_audit_fanout_declined", { findings: fresh.length });
+    ctx.ui.notify(`Fan-out declined — the findings stay open in ${AUDIT_FINDINGS_REL}; /list audit re-queues them any time.`, "info");
+    return;
+  }
+  const n = enqueueItems(ctx, fresh.map((f) => listAuditFanoutItemText(f.text)), "list audit fan-out");
+  appendLedger(ctx.cwd, "list_audit_fanout", { queued: n, alreadyQueued, decisions: decisions.length });
+  ctx.ui.notify(
+    `Queued ${n} finding(s) — the list drains them fix by fix, each with its own audited commit.${alreadyQueued > 0 ? ` (${alreadyQueued} already queued.)` : ""}${decideNote}`,
+    "info",
+  );
+}
+
 function archiveCurrentGoal(ctx: ExtensionContext, status: Status, stopReason?: string): void {
   if (!state.goal) return;
   const goal = state.goal;
@@ -1174,9 +1313,15 @@ function archiveCurrentGoal(ctx: ExtensionContext, status: Status, stopReason?:
   // (v0.2.0 bug: bare /list next silently consumed TWO items, found by the
   // pick-any-item verification in v0.10.0).
   if (goal.policy === "list" && status === "complete") {
+    // v0.31.0: a /list audit collection item completed → fan the open
+    // findings out into the queue (async — Confirm-gated). When the queue
+    // was empty, enqueueItems activates the first fix itself, so the
+    // list-complete / reviewer noise below must NOT fire for this item.
+    const isListAuditCollect = goal.objective.includes(LIST_AUDIT_COLLECT_MARKER);
+    if (isListAuditCollect) void fanOutListAuditFindings(ctx);
     const advanced = activateNextListItem(ctx);
     // v0.26.0: the queue just EMPTIED on a completion → list-complete.
-    if (!advanced) {
+    if (!advanced && !isListAuditCollect) {
       fireReviewer(ctx, { kind: "list", goalId: goal.id, objective: goal.objective, terminal: "goal-complete" });
       // v0.29.0: the well ran dry — point at the project-audit loop. A
       // suggestion, not an action: consent, never auto-start (v0.28.28).
@@ -2005,6 +2150,26 @@ async function cmdList(args: string, ctx: ExtensionContext): Promise<void> {
   const sub = (parts[0] ?? "").toLowerCase();
   const rest = args.trim().slice(sub.length).trim();
 
+  if (sub === "audit") {
+    // v0.31.0: /list audit [focus] — collect-then-drain (user design
+    // 2026-07-31: "run a project audit, collect a bunch of tasks, then do
+    // them all too"). The audit item COLLECTS findings (changes no code);
+    // its completion fans each open finding out into the queue and the
+    // list drains them fix by fix, each with its own isolated audit.
+    // Distinct from /goal audit (fix-in-pass, one audited unit) and
+    // /loop audit (forever fix-first cadence).
+    const objective = listAuditCollectTarget(rest || undefined);
+    const n = enqueueItems(ctx, [objective], "/list audit");
+    if (n === 0) return; // zombie-twin guard already explained itself
+    ctx.ui.notify(
+      "Audit collection item queued — it CHANGES NO CODE: it appends findings to " +
+        AUDIT_FINDINGS_REL +
+        ", and on completion each open finding becomes its own list item (fixes drain one audited commit at a time). DECIDE findings are presented to you, never queued.",
+      "info",
+    );
+    return;
+  }
+
   if (sub === "depth") {
     // v0.25.3: long-running state at a glance — queue depth, oldest item
     // age, average item duration from archived list-policy goals.
@@ -5303,9 +5468,10 @@ export default function (pi: ExtensionAPI): void {
     handler: (args: string, ctx: ExtensionContext) => { rememberCtx(ctx); return cmdReview(args, ctx); },
   });
   pi.registerCommand("list", {
-    description: "Loop 2: the list of audited goals — order is the default, not the law. /list <describe tasks or name a plan file> (dumps get shaped into items, files import, 'Done when:' adds directly) | /list show | /list resume | /list next [n] | /list remove <n> | /list clear | /list cancel",
+    description: "Loop 2: the list of audited goals — order is the default, not the law. /list <describe tasks or name a plan file> (dumps get shaped into items, files import, 'Done when:' adds directly) | /list audit [focus] (collect findings, then drain them as items) | /list show | /list resume | /list next [n] | /list remove <n> | /list clear | /list cancel",
     getArgumentCompletions: completions([
       ["show", "display the waiting items"],
+      ["audit", "collect-then-drain: audit the project, queue every finding as its own item"],
       ["resume", "resume the paused list item (the list's head)"],
       ["next", "activate the next item (or /list next <n> for position n)"],
       ["remove", "remove an item: /list remove <n>"],
@@ -5493,12 +5659,43 @@ export default function (pi: ExtensionAPI): void {
     }
   });
 
+  pi.on("session_shutdown", async (event: any, ctx: ExtensionContext) => {
+    if (isForeignCtx(ctx)) return;
+    // v0.30.0: attribution + rebind window. pi announces WHY the session
+    // is being replaced (reload/resume/new/fork/quit) — the ledger can
+    // now answer "what killed the handle?" without guesswork (hegemon's
+    // 5-hour orphan silence 2026-07-31 was unattributable). The window
+    // tells the stale probe that a rebind (session_start) is imminent.
+    const shutdownReason = typeof event?.reason === "string" ? event.reason : "unknown";
+    appendLedger(ctx.cwd, "session_shutdown", { reason: shutdownReason });
+    sessionReplacementUntil = Date.now() + SESSION_REBIND_GRACE_MS;
+  });
+
   pi.on("session_start", async (event: any, ctx: ExtensionContext) => {
     rememberCtx(ctx);
     // v0.23.8: subagent sessions (pi-subagents binds extensions there too)
     // are workers — never run the restore gate or reschedule the loop from
     // a foreign session.
     if (isForeignCtx(ctx)) return;
+    // v0.30.0: rebind bookkeeping — claim ownership, close any replacement
+    // window, and reset a stale flag left over from the PREVIOUS session's
+    // invalidation. pi rebinds THIS module to the new session (switch) or
+    // re-imports it (/reload — fresh module, flag already false); either
+    // way the fresh ctx makes the old poison flag wrong. Re-probe to
+    // confirm the new handle actually works.
+    writeOwnerFile(ctx.cwd);
+    sessionReplacementUntil = 0;
+    zombieStoodDown = false;
+    const startReason = typeof event?.reason === "string" ? event.reason : "unknown";
+    appendLedger(ctx.cwd, "session_rebound", { reason: startReason });
+    if (extensionApiStale) {
+      extensionApiStale = false; // fresh ctx delivered — re-probe
+      const stillStale = probeExtensionApiStale();
+      appendLedger(ctx.cwd, "stale_flag_reset_on_rebind", { reason: startReason, stillStale });
+      if (stillStale) {
+        ctx.ui.notify("glla: session rebound but the extension handle is still stale — run /reload (extensions rebuild in place), then /glla resume.", "warning");
+      }
+    }
     state = readState(ctx.cwd);
     // v0.28.14: snapshot carryover BEFORE any restore logic mutates state —
     // a paused goal, waiting list items, or a loop that was live/held when

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-goal-list-loop-audit",
-  "version": "0.29.23",
+  "version": "0.31.0",
   "description": "Goal. Loop. Audit. Done. \u2014 a pi-coding-agent extension that supervises long-running work, with isolated auditor on each completion. Beat bamboozling by design: the auditor runs in a fresh session with no extensions, no skills, no editor \u2014 only the read tools needed to verify your goal.",
   "license": "MIT",
   "author": "dracon",