pi-orchestrator-config 4.24.0 → 4.24.2

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [4.24.2] - 2026-11-04
+
+- Async work is tracked even when an agent starts it: the task trigger now covers work set in
+  motion by an async result, and `taskId: "-1"` is restricted to a single read-only check in
+  every place that taught the old habit.
+- Task-id validation actually runs. `pitasks` exports the store as a live binding that the
+  subagent tool used to snapshot before it was assigned, so an unknown id was accepted; the
+  store is now published on a symbol bridge and read at access time. Verified live: unknown
+  ids rejected, a real id and the read-only sentinel accepted.
+- Machine-generated notices declare their provenance: follow-ups are prefixed
+  "[system message — not written by the user]", so a guard rail cannot be read as user input.
+- Board updates are success-gated — a failed agent keeps its task open — and reconciling the
+  board before new dispatch is mandatory. Status reports derive from `TaskList`.
+
+## [4.24.1] - 2026-11-03
+
+- Dreaming no longer stores re-derivable changelog: `[done]` takes non-derivable outcomes only (conclusions, measurements, root causes) and reorganizing prunes PR/version/ticket
+  history, so `completions` shrinks instead of rotating changelog for changelog. A live run took this project's topic from 18 entries to 2, keeping the cost baseline and the
+  self-reload finding.
+- Learned memory now survives maintenance: anything a dream deletes that is pinned, enforced, or review-distilled is restored when it finishes, and a topic file it deleted is
+  rebuilt. A deliberate removal is respected because removals are recorded as tombstones rather than inferred from score state — the inference inverted whenever the scheduled
+  rebuild ran mid-dream.
+- `completions` is capped at 6,000 characters through per-topic caps, applied by both write paths. The cap is never satisfied by deleting memory: an over-cap topic is reported and
+  left intact.
+
 ## [4.24.0] - 2026-11-03
 
 - `/pr-review` asks how to decide after the findings table — `Post all`, `Skip all`, or

package/extensions/orchestrator/dreaming.ts

@@ -23,15 +23,248 @@ import { getSetting } from "./project-settings.js";
 import { discoverAgents } from "./agents.js";
 import { ICON_DREAM } from "./icons.js";
 import { setSlot } from "./status-bar.js";
+import { distilledLessonTextList } from "./review-learning.js";
+import { invalidateTopicFileCache, removalsSince, topicCharCap } from "./memory-tree.js";
+import { entryHash } from "./memory-scoring.js";
+
+/** Topic files memory maintenance rewrites. */
+const MEMORY_TOPIC_FILES = ["lessons", "preferences", "patterns", "decisions", "completions", "mistakes"];
+
+/** Line text without its `- [category] ` prefix, lock markers, or `{#id}` suffix. */
+function topicLineText(line: string): string {
+  return line
+    .replace(/^- \[[a-z]+\] /, "")
+    .replace(/\s*\*\((?:pinned|enforced)\)\*/g, "")
+    .replace(/\s*\{#[0-9a-f]+\}\s*$/, "")
+    .trim();
+}
+
+/**
+ * Entries memory maintenance must never delete, whatever the prompt says:
+ * pinned/enforced entries (user-locked, or keyed by text hash for enforcement) and
+ * lessons distilled from reviews — their source is the reviews DB, but nothing
+ * re-materializes the topic line once a dream removes it (issue #1010).
+ */
+export function isProtectedTopicLine(line: string, reviewLessons: readonly string[]): boolean {
+  if (!line.startsWith("- [")) return false;
+  if (line.includes("*(pinned)*") || line.includes("*(enforced)*")) return true;
+  const text = topicLineText(line);
+  return reviewLessons.some((lesson) => {
+    const candidate = lesson.trim();
+    return candidate.length > 0 && text === candidate;
+  });
+}
+
+/** Snapshot every memory topic file's lines, so a dream's deletions can be audited. */
+export function snapshotTopicLines(topicsDir: string): Record<string, string[]> {
+  const before: Record<string, string[]> = {};
+  for (const name of MEMORY_TOPIC_FILES) {
+    try {
+      before[`${name}.md`] = fs.readFileSync(path.join(topicsDir, `${name}.md`), "utf-8").split("\n");
+    } catch {
+      // Topic absent — nothing to protect.
+    }
+  }
+  return before;
+}
+
+/**
+ * Restore protected entries a dream removed, at their original index. Returns how
+ * many lines were put back; zero means the dream stayed inside its mandate.
+ * Any failure is the caller's to log — this never throws.
+ */
+/** Canonical `- [category] text` form used as the memory score key. */
+export function topicLineCanonical(line: string): string {
+  const category = /^- \[([a-z]+)\] /.exec(line)?.[1] ?? "";
+  return `- [${category}] ${topicLineText(line)}`;
+}
+
+export type TopicRestoreReport = {
+  restored: number;
+  failed: number;
+  /** Topics still over their cap after reconcile. Never trimmed here: see below. */
+  overCapTopics: string[];
+};
+
+/**
+ * Restore protected entries a dream removed, at their original index, then keep the
+ * file inside its per-topic cap by dropping unprotected additions — never protected
+ * ones. Recreates a topic the dream deleted outright. Returns what it did; logging is
+ * the caller's, this never throws.
+ */
+export function restoreProtectedTopicLines(
+  topicsDir: string,
+  before: Record<string, string[]>,
+  reviewLessons: readonly string[],
+  removedByUser: (line: string) => boolean = () => false,
+): TopicRestoreReport {
+  const report: TopicRestoreReport = { restored: 0, failed: 0, overCapTopics: [] };
+  for (const [file, beforeLines] of Object.entries(before)) {
+    const filePath = path.join(topicsDir, file);
+    let current: string[] | null = null;
+    try {
+      current = fs.readFileSync(filePath, "utf-8").split("\n");
+    } catch {
+      current = null; // Deleted outright — rebuilt below from the snapshot.
+    }
+    const base = current ?? beforeLines.filter((line) => !line.startsWith("- ["));
+    // A dream that *rewrites* a protected entry keeps it: compare canonical text, not the
+    // raw line, or the original returns beside the rewrite as a duplicate.
+    const surviving = new Set((current ?? []).map(topicLineCanonical));
+    const beforeEntries = new Set(
+      beforeLines.filter((line) => line.startsWith("- [")).map(topicLineCanonical),
+    );
+    const missing = beforeLines
+      .map((line, index) => ({ line, index }))
+      .filter(({ line }) => {
+        if (!line.startsWith("- [") || !isProtectedTopicLine(line, reviewLessons)) return false;
+        if (surviving.has(topicLineCanonical(line))) return false;
+        // Only an explicit tombstone proves a removal. Score absence does not: the
+        // scheduled rebuild prunes scores for lines a dream deleted, which would look
+        // exactly like a user removal and strand the entry (issue #1010).
+        return !removedByUser(line);
+      });
+    if (missing.length === 0 && current !== null) continue;
+
+    const merged = [...base];
+    for (const { line, index } of missing) {
+      merged.splice(Math.min(index, merged.length), 0, line);
+      report.restored += 1;
+    }
+
+    const cap = topicCharCap(file.replace(/\.md$/, ""));
+    // Never trim here. Text cannot distinguish a dream's addition from its rewrite of an
+    // existing memory, and deleting the wrong one loses knowledge that the score rebuild
+    // cannot recover. The write paths still enforce the cap for normal additions; an
+    // over-cap file is reported so the next prune can shrink it with judgment.
+    if (merged.join("\n").length > cap) report.overCapTopics.push(file);
+
+    try {
+      fs.writeFileSync(filePath, merged.join("\n"), "utf-8");
+      invalidateTopicFileCache(filePath);
+    } catch {
+      report.failed += 1;
+      report.restored -= missing.length;
+    }
+  }
+  return report;
+}
+
 import { rebuildAndOrganize } from "./situation-report.js";
 import { runPromotionPass } from "./memory-promotion.js";
 import { mergeProvenancePending } from "./memory-provenance.js";
-import { getProjectTmpDir, getProjectMemoryDir, shouldSkipOneshotShutdownDream } from "./utils.js";
+import { getProjectTmpDir, getProjectMemoryDir, getProjectDataDir, shouldSkipOneshotShutdownDream } from "./utils.js";
 import { fileLog } from "../shared/file-logger.js";
 
 // Scoring rebuild runs every 30 minutes (cheap, no LLM — just rescores and reorganizes)
 const REBUILD_INTERVAL_MS = 30 * 60 * 1000;
 
+export function buildDreamPrompt(
+  lastSessionFile: string | undefined,
+  topicsDir: string,
+): string {
+  return (
+    `Memory dreaming — analyze session and maintain topic files.\n` +
+    `Session file: ${lastSessionFile || "none"}\n` +
+    `Topics directory: ${topicsDir}\n\n` +
+    `Topic files are the source of truth for project memory. Each file holds entries for one category.\n\n` +
+    `Steps:\n` +
+    `1. Read all existing topic files in ${topicsDir}/ (lessons.md, preferences.md, patterns.md, decisions.md, completions.md, mistakes.md).\n` +
+    `   If the directory doesn't exist, create it.\n` +
+    `2. QUALITY GATE: Before extracting from any session, assess its quality:\n` +
+    `   - Score depth (substantive exchanges > 100 chars? decisions made? corrections?)\n` +
+    `   - Skip sessions that are only greetings, trivial Q&A, or < 3 exchanges\n` +
+    `   - Only extract from sessions with real decisions, corrections, or completed work\n` +
+    `3. If a session file is provided, read it and extract things worth remembering:\n` +
+    `   - User corrections → [lesson] → lessons.md\n` +
+    `   - User preferences → [preference] → preferences.md\n` +
+    `   - Mistakes or repeated fix attempts → [mistake] → mistakes.md\n` +
+    `   - Completed work → [done] → completions.md — ONLY non-derivable outcome knowledge:\n` +
+    `     a conclusion, a measurement, a root cause, "X was fixed by Y because Z".\n` +
+    `     NEVER store a PR/issue number list, merge or release history, version changelogs,\n` +
+    `     or closed-ticket roundups — git log, gh, and the tracker already hold them, and a\n` +
+    `     stored "Open: #772" answers "is it fixed?" wrongly once it ships.\n` +
+    `   - Patterns or conventions → [pattern] → patterns.md\n` +
+    `   - Architectural/design decisions → [decision] → decisions.md\n` +
+    `   QUALITY GATE for extraction: one-off permissions granted in a single session\n` +
+    `   ("you can merge this PR", "skip tests just this once") AND task-scoped instructions\n` +
+    `   ("when done, I want an html report", "when bumping to 1.4.0, drop the vendor dir",\n` +
+    `   config-change notes like "every 30min (changed from 1h)") are session/task\n` +
+    `   instructions, NOT memories — never extract them. Apply the standing test: would\n` +
+    `   this apply to a future, unrelated task? No → discard. Only standing, repeated\n` +
+    `   rules are durable.\n` +
+    `   Do NOT add duplicates of existing entries.\n` +
+    `3b. Review the preference candidate queue: if ${topicsDir}/../preference-candidates.jsonl\n` +
+    `   exists and has entries, each holds a VERBATIM sentence the regex extractor queued\n` +
+    `   from user input (issue #961). For each candidate:\n` +
+    `   - Durable standing preference → DISTILL it into a clean one-line [preference]\n` +
+    `     (≤100 chars, actionable, no verbatim chatter) and add to preferences.md\n` +
+    `   - Task-scoped instruction, one-off ask, question, or already covered → discard\n` +
+    `   After processing: RE-READ preference-candidates.jsonl and rewrite it keeping ONLY\n` +
+    `   the entries that appeared after your first read — the extractor appends\n` +
+    `   concurrently, so do NOT truncate the whole file (an entry queued between your\n` +
+    `   read and your rewrite would be erased before any dream cycle reviewed it).\n` +
+    `   Keep the file bounded: if it exceeds 200 lines, also drop the oldest entries\n` +
+    `   beyond that cap.\n` +
+    `4. Scan past session files for unprocessed knowledge. Check if ${topicsDir}/../.dream-watermark exists.\n` +
+    `   If it does, read the timestamp — only process sessions newer than that.\n` +
+    `   Session directory: find .jsonl files under the pi sessions directory.\n` +
+    `   For each unprocessed session, extract durable knowledge (same categories as step 3).\n` +
+    `   Limit: process at most 5 sessions per dream cycle to avoid overload.\n` +
+    `5. Reorganize each topic file:\n` +
+    `   - Remove duplicate or near-duplicate entries\n` +
+    `   - Remove stale/useless entries\n` +
+    `   - Remove session-scoped or expired entries — they are transient by design\n` +
+    `   - Remove task-scoped instruction entries (issue #961): verbatim user utterances\n` +
+    `     (colloquial chat captured raw), mid-sentence cutoffs, one-off deliverable asks\n` +
+    `     ("when done I want a report"), version-pinned migration checklists, config-change\n` +
+    `     notes — these are task/session artifacts, not durable rules. NEVER remove\n` +
+    `     pinned or enforced entries even when they match these shapes.\n` +
+    `   - Remove entries that restate git/GitHub/Jira history — merged-PR lists, release and\n` +
+    `     version notes, closed-ticket roundups. Recoverable by query, therefore not memory.\n` +
+    `     When an entry mixes history with a non-derivable finding, keep only the finding.\n` +
+    `   - Keep each file at a reasonable size (aim for under 20 entries per topic)\n` +
+    `   - NEVER remove or modify entries marked with *(pinned)*\n` +
+    `   - NEVER remove or modify entries marked with *(enforced)* — these have code-enforced triggers/actions that are keyed by text hash. ANY text change destroys the enforcement binding.\n` +
+    `6. Write each updated topic file with this format:\n` +
+    `   # TopicName\n` +
+    `   \n` +
+    `   - [category] summary *(pinned)*              (if pinned)\n` +
+    `   - [category] summary *(enforced)*            (if enforced)\n` +
+    `   - [category] summary *(pinned)* *(enforced)* (if both)\n` +
+    `   - [category] summary                         (if neither)\n` +
+    `7. Auto-generate skills: if you notice a multi-step workflow pattern across entries,\n` +
+    `   create a skill file at .pi/skills/<name>/SKILL.md (project-level, NOT global ~/.agents/).\n` +
+    `   The SKILL.md MUST start with YAML frontmatter:\n` +
+    `   ---\n` +
+    `   name: <name>\n` +
+    `   description: "What this skill does and when to use it"\n` +
+    `   ---\n` +
+    `   Only create skills for workflows with 3+ steps that are likely to recur.\n` +
+    `8. Write the current timestamp to ${topicsDir}/../.dream-watermark to track progress.\n` +
+    `9. Memory rules: one line per entry, max ~100 chars, specific and actionable, no fluff.\n` +
+    `10. Promotion destinations: append candidates to ${topicsDir}/../promotions.md using this block format:\n` +
+    `   ### <12-char-id>\n` +
+    `   - destination: memory|skill|enforcement|project_rule|discard\n` +
+    `   - status: proposed\n` +
+    `   - category: <category>\n` +
+    `   - text: <exact topic entry text>\n` +
+    `   - reason: <why this should graduate>\n` +
+    `   - created: <ISO timestamp>\n` +
+    `   Optional fields: evidence_count, trigger, action, verifier, skill_name, skill_created.\n` +
+    `   Rules:\n` +
+    `   - skill: create .pi/skills/ when confident; set skill_created: true\n` +
+    `   - enforcement: propose trigger/action when mechanical (never/always + command); do NOT invent run_after\n` +
+    `   - project_rule: propose only — NEVER write rules/ or .pi/rules/\n` +
+    `   - discard: stale or superseded noise\n` +
+    `   - Do not reopen entries already marked applied or rejected in promotions.md\n` +
+    `11. Provenance sidecar (optional): for newly extracted entries, write\n` +
+    `   ${topicsDir}/../provenance-pending.jsonl as a single line of JSON (preferred):\n` +
+    `   {"entries":[{"category":"lesson","text":"<exact topic text>","sourceSession":"<session basename>","derivedFrom":"<optional>","informs":["optional"]}]}\n` +
+    `   Do NOT edit memory-scores.jsonl yourself — onComplete merges the sidecar.`
+  );
+}
+
 export function registerDreaming(
   pi: ExtensionAPI,
   spawnAsyncAgent: (
@@ -102,99 +335,13 @@ export function registerDreaming(
     currentDreamId = "";  // Reset until we get the ID from spawnAsyncAgent
     const { agents } = discoverAgents(cwd, "user");
     const topicsDir = path.join(getProjectMemoryDir(cwd), "topics");
+    // Snapshot before the dream touches anything: whatever it removes that is learned
+    // knowledge rather than re-derivable history is put back below (issue #1010).
+    const topicsBeforeDream = snapshotTopicLines(topicsDir);
+    const dreamStartedAt = Date.now();
     const { id } = spawnAsyncAgent(
       "worker",
-      `Memory dreaming — analyze session and maintain topic files.\n` +
-      `Session file: ${lastSessionFile || "none"}\n` +
-      `Topics directory: ${topicsDir}\n\n` +
-      `Topic files are the source of truth for project memory. Each file holds entries for one category.\n\n` +
-      `Steps:\n` +
-      `1. Read all existing topic files in ${topicsDir}/ (lessons.md, preferences.md, patterns.md, decisions.md, completions.md, mistakes.md).\n` +
-      `   If the directory doesn't exist, create it.\n` +
-      `2. QUALITY GATE: Before extracting from any session, assess its quality:\n` +
-      `   - Score depth (substantive exchanges > 100 chars? decisions made? corrections?)\n` +
-      `   - Skip sessions that are only greetings, trivial Q&A, or < 3 exchanges\n` +
-      `   - Only extract from sessions with real decisions, corrections, or completed work\n` +
-      `3. If a session file is provided, read it and extract things worth remembering:\n` +
-      `   - User corrections → [lesson] → lessons.md\n` +
-      `   - User preferences → [preference] → preferences.md\n` +
-      `   - Mistakes or repeated fix attempts → [mistake] → mistakes.md\n` +
-      `   - Completed features/PRs merged → [done] → completions.md\n` +
-      `   - Patterns or conventions → [pattern] → patterns.md\n` +
-      `   - Architectural/design decisions → [decision] → decisions.md\n` +
-      `   QUALITY GATE for extraction: one-off permissions granted in a single session\n` +
-      `   ("you can merge this PR", "skip tests just this once") AND task-scoped instructions\n` +
-      `   ("when done, I want an html report", "when bumping to 1.4.0, drop the vendor dir",\n` +
-      `   config-change notes like "every 30min (changed from 1h)") are session/task\n` +
-      `   instructions, NOT memories — never extract them. Apply the standing test: would\n` +
-      `   this apply to a future, unrelated task? No → discard. Only standing, repeated\n` +
-      `   rules are durable.\n` +
-      `   Do NOT add duplicates of existing entries.\n` +
-      `3b. Review the preference candidate queue: if ${topicsDir}/../preference-candidates.jsonl\n` +
-      `   exists and has entries, each holds a VERBATIM sentence the regex extractor queued\n` +
-      `   from user input (issue #961). For each candidate:\n` +
-      `   - Durable standing preference → DISTILL it into a clean one-line [preference]\n` +
-      `     (≤100 chars, actionable, no verbatim chatter) and add to preferences.md\n` +
-      `   - Task-scoped instruction, one-off ask, question, or already covered → discard\n` +
-      `   After processing: RE-READ preference-candidates.jsonl and rewrite it keeping ONLY\n` +
-      `   the entries that appeared after your first read — the extractor appends\n` +
-      `   concurrently, so do NOT truncate the whole file (an entry queued between your\n` +
-      `   read and your rewrite would be erased before any dream cycle reviewed it).\n` +
-      `   Keep the file bounded: if it exceeds 200 lines, also drop the oldest entries\n` +
-      `   beyond that cap.\n` +
-      `4. Scan past session files for unprocessed knowledge. Check if ${topicsDir}/../.dream-watermark exists.\n` +
-      `   If it does, read the timestamp — only process sessions newer than that.\n` +
-      `   Session directory: find .jsonl files under the pi sessions directory.\n` +
-      `   For each unprocessed session, extract durable knowledge (same categories as step 3).\n` +
-      `   Limit: process at most 5 sessions per dream cycle to avoid overload.\n` +
-      `5. Reorganize each topic file:\n` +
-      `   - Remove duplicate or near-duplicate entries\n` +
-      `   - Remove stale/useless entries\n` +
-      `   - Remove session-scoped or expired entries — they are transient by design\n` +
-      `   - Remove task-scoped instruction entries (issue #961): verbatim user utterances\n` +
-      `     (colloquial chat captured raw), mid-sentence cutoffs, one-off deliverable asks\n` +
-      `     ("when done I want a report"), version-pinned migration checklists, config-change\n` +
-      `     notes — these are task/session artifacts, not durable rules. NEVER remove\n` +
-      `     pinned or enforced entries even when they match these shapes.\n` +
-      `   - Keep each file at a reasonable size (aim for under 20 entries per topic)\n` +
-      `   - NEVER remove or modify entries marked with *(pinned)*\n` +
-      `   - NEVER remove or modify entries marked with *(enforced)* — these have code-enforced triggers/actions that are keyed by text hash. ANY text change destroys the enforcement binding.\n` +
-      `6. Write each updated topic file with this format:\n` +
-      `   # TopicName\n` +
-      `   \n` +
-      `   - [category] summary *(pinned)*              (if pinned)\n` +
-      `   - [category] summary *(enforced)*            (if enforced)\n` +
-      `   - [category] summary *(pinned)* *(enforced)* (if both)\n` +
-      `   - [category] summary                         (if neither)\n` +
-      `7. Auto-generate skills: if you notice a multi-step workflow pattern across entries,\n` +
-      `   create a skill file at .pi/skills/<name>/SKILL.md (project-level, NOT global ~/.agents/).\n` +
-      `   The SKILL.md MUST start with YAML frontmatter:\n` +
-      `   ---\n` +
-      `   name: <name>\n` +
-      `   description: "What this skill does and when to use it"\n` +
-      `   ---\n` +
-      `   Only create skills for workflows with 3+ steps that are likely to recur.\n` +
-      `8. Write the current timestamp to ${topicsDir}/../.dream-watermark to track progress.\n` +
-      `9. Memory rules: one line per entry, max ~100 chars, specific and actionable, no fluff.\n` +
-      `10. Promotion destinations: append candidates to ${topicsDir}/../promotions.md using this block format:\n` +
-      `   ### <12-char-id>\n` +
-      `   - destination: memory|skill|enforcement|project_rule|discard\n` +
-      `   - status: proposed\n` +
-      `   - category: <category>\n` +
-      `   - text: <exact topic entry text>\n` +
-      `   - reason: <why this should graduate>\n` +
-      `   - created: <ISO timestamp>\n` +
-      `   Optional fields: evidence_count, trigger, action, verifier, skill_name, skill_created.\n` +
-      `   Rules:\n` +
-      `   - skill: create .pi/skills/ when confident; set skill_created: true\n` +
-      `   - enforcement: propose trigger/action when mechanical (never/always + command); do NOT invent run_after\n` +
-      `   - project_rule: propose only — NEVER write rules/ or .pi/rules/\n` +
-      `   - discard: stale or superseded noise\n` +
-      `   - Do not reopen entries already marked applied or rejected in promotions.md\n` +
-      `11. Provenance sidecar (optional): for newly extracted entries, write\n` +
-      `   ${topicsDir}/../provenance-pending.jsonl as a single line of JSON (preferred):\n` +
-      `   {"entries":[{"category":"lesson","text":"<exact topic text>","sourceSession":"<session basename>","derivedFrom":"<optional>","informs":["optional"]}]}\n` +
-      `   Do NOT edit memory-scores.jsonl yourself — onComplete merges the sidecar.`,
+      buildDreamPrompt(lastSessionFile, topicsDir),
       cwd,
       agents,
       {
@@ -206,6 +353,34 @@ export function registerDreaming(
           dreamInFlight = false;
           log.info("dream complete", cwd);
           updateDreamStatus();
+          // Undo any deletion of learned knowledge before anything reads the topics.
+          try {
+            const reviewLessons = distilledLessonTextList(getProjectDataDir(cwd));
+            const removed = removalsSince(cwd, dreamStartedAt);
+            const report = restoreProtectedTopicLines(topicsDir, topicsBeforeDream, reviewLessons, (line) =>
+              removed.has(entryHash(topicLineCanonical(line))),
+            );
+            if (report.restored > 0) {
+              log.warn("dream_restored_protected_entries", { restored: report.restored });
+            }
+            if (report.overCapTopics.length > 0) {
+              log.warn("dream_restore_left_topic_over_cap", { topics: report.overCapTopics });
+            }
+            if (report.failed > 0) {
+              log.error("dream_restore_write_failed", { failedTopics: report.failed });
+            }
+            if (report.restored > 0 || report.failed > 0 || report.overCapTopics.length > 0) {
+              fileLog(
+                "dreaming",
+                report.failed > 0 ? "error" : "warn",
+                "dreaming",
+                `protected-memory reconcile: restored=${report.restored} over_cap=${report.overCapTopics.join(",") || "-"} failed=${report.failed}`,
+              );
+            }
+          } catch (err) {
+            log.error("dream_restore_failed", { reason: String((err as Error)?.message ?? err).slice(0, 200) });
+            fileLog("dreaming", "error", "dreaming", "protected-memory restore failed", err);
+          }
           // File log only — console.* leaks into the chat text box.
           try {
             rebuildAndOrganize(cwd);

package/extensions/orchestrator/memory-tools.ts

@@ -31,9 +31,10 @@ import {
   listTopics,
   readAllTopicEntries,
   CATEGORY_TO_TOPIC,
-  MAX_TOPIC_CHARS,
+  topicCharCap,
   findTopicLine,
   invalidateTopicFileCache,
+  recordRemoval,
   type TopicInfo,
 } from "./memory-tree.js";
 import { embedEntry, removeEmbedding, vectorSearch, embedMissing } from "./memory-embeddings.js";
@@ -406,6 +407,9 @@ function registerMemoryRemove(pi: ExtensionAPI): void {
         }
       });
 
+      // Tombstone the removal: the dream guard must be able to tell this from its own damage.
+      recordRemoval(cwd, canonicalLine);
+
       log.info("memory_remove", category, text.slice(0, 60));
       return {
         content: [{ type: "text", text: `Removed: [${category}] ${text}` }],
@@ -551,8 +555,10 @@ function registerMemoryEdit(pi: ExtensionAPI): void {
         const markers = `${wasPinned ? " *(pinned)*" : ""}${wasEnforced ? " *(enforced)*" : ""}${wasId ? ` {#${wasId}}` : ""}`;
         const replacement = `- [${category}] ${newText}${markers}`;
         const newContent = content.replace(lines[matchIndex]!, replacement);
-        if (newContent.length > MAX_TOPIC_CHARS) {
-          return { content: [{ type: "text", text: `Update would exceed topic size limit (${newContent.length}/${MAX_TOPIC_CHARS} chars).` }], details: undefined };
+        const cap = topicCharCap(topicName);
+        if (newContent.length > cap) {
+          log.warn("memory_edit_topic_cap_rejected", { topic: topicName, chars: newContent.length, cap });
+          return { content: [{ type: "text", text: `Update would exceed topic size limit (${newContent.length}/${cap} chars).` }], details: undefined };
         }
         // Replace the line
         lines[matchIndex] = replacement;

package/extensions/orchestrator/memory-tree.ts

@@ -12,8 +12,8 @@
 
 import { createLogger } from "../shared/logger.js";
 import { getProjectMemoryDir } from "./utils.js";
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import {
   type MemoryCategory,
   loadScores,
@@ -27,6 +27,65 @@ const log = createLogger("memory");
 /** Max chars per topic file (~3000 tokens × 4 chars/token) */
 export const MAX_TOPIC_CHARS = 12000;
 
+/** Per-topic override of MAX_TOPIC_CHARS. `completions` accretes by default, so it gets
+ *  a tighter budget: completed-work entries crowd out the knowledge worth keeping. */
+export const TOPIC_CHAR_CAP: Record<string, number> = { completions: 6000 };
+
+/** Char cap for a topic file name (without `.md`), falling back to MAX_TOPIC_CHARS. */
+export function topicCharCap(topic: string): number {
+  const cap = TOPIC_CHAR_CAP[topic] ?? MAX_TOPIC_CHARS;
+  log.debug("topic_char_cap_resolved", { topic, cap, overridden: topic in TOPIC_CHAR_CAP });
+  return cap;
+}
+
+/** Append-only log of deliberate entry removals, so background maintenance can tell a
+ *  user removal from its own damage. Score absence cannot: the scheduled rebuild prunes
+ *  scores for lines missing from topic files (issue #1010). */
+const REMOVALS_FILE = "removals.jsonl";
+const MAX_REMOVAL_ROWS = 5000;
+
+/** Record that an entry was removed on purpose. Fail-soft: a lost tombstone can only
+ *  make the dream guard restore a line the user deleted, never delete one. */
+export function recordRemoval(cwd: string, canonicalLine: string): void {
+  try {
+    const file = join(getProjectMemoryDir(cwd), REMOVALS_FILE);
+    const row = `${JSON.stringify({ hash: entryHash(canonicalLine), at: new Date().toISOString() })}\n`;
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, row, "utf-8");
+    log.debug("memory_removal_recorded", { hash: entryHash(canonicalLine) });
+    const rows = readFileSync(file, "utf-8").split("\n").filter(Boolean);
+    if (rows.length > MAX_REMOVAL_ROWS) {
+      writeFileSync(file, `${rows.slice(-MAX_REMOVAL_ROWS).join("\n")}\n`, "utf-8");
+    }
+  } catch (error) {
+    log.warn("memory_removal_record_failed", { reason: String((error as Error)?.message ?? error).slice(0, 120) });
+  }
+}
+
+/** Hashes removed at or after `sinceMs` — the only trustworthy signal that a line
+ *  missing after a background dream was the user's decision, not the dream's damage. */
+export function removalsSince(cwd: string, sinceMs: number): Set<string> {
+  const hashes = new Set<string>();
+  try {
+    const file = join(getProjectMemoryDir(cwd), REMOVALS_FILE);
+    if (!existsSync(file)) return hashes;
+    for (const row of readFileSync(file, "utf-8").split("\n")) {
+      if (!row.trim()) continue;
+      try {
+        const parsed = JSON.parse(row) as { hash?: unknown; at?: unknown };
+        if (typeof parsed.hash !== "string" || typeof parsed.at !== "string") continue;
+        if (Date.parse(parsed.at) >= sinceMs) hashes.add(parsed.hash);
+      } catch {
+        // Skip a malformed row rather than losing the whole log.
+      }
+    }
+    log.debug("memory_removals_since", { sinceMs, count: hashes.size });
+  } catch (error) {
+    log.warn("memory_removals_read_failed", { reason: String((error as Error)?.message ?? error).slice(0, 120) });
+  }
+  return hashes;
+}
+
 /** Topic mapping: which categories go into which topic files */
 export const CATEGORY_TO_TOPIC: Record<MemoryCategory, string> = {
   preference: "preferences",

package/extensions/orchestrator/memory-write.ts

@@ -39,7 +39,7 @@ import {
   isTaskScopedText,
   hasDurabilityMarker,
 } from "./memory-scoring.js";
-import { CATEGORY_TO_TOPIC, MAX_TOPIC_CHARS, readAllTopicEntries, formatTopicLine, findTopicLine, invalidateTopicFileCache } from "./memory-tree.js";
+import { CATEGORY_TO_TOPIC, topicCharCap, readAllTopicEntries, formatTopicLine, findTopicLine, invalidateTopicFileCache, recordRemoval } from "./memory-tree.js";
 import { embedEntry, removeEmbedding, vectorSearch } from "./memory-embeddings.js";
 import { getSetting } from "./project-settings.js";
 
@@ -2165,6 +2165,8 @@ function supersedeEntry(cwd: string, category: string, text: string): void {
     removeEmbedding(cwd, text, category);
 
     const canonicalLine = `- [${category}] ${text}`;
+    // The old text is gone on purpose: tombstone it so the dream guard does not undo an edit.
+    recordRemoval(cwd, canonicalLine);
     const removedId = match.id;
     mutateScores(cwd, (scores) => {
       delete scores.entries[entryHash(canonicalLine)];
@@ -2197,11 +2199,13 @@ function topicCapRejection(cwd: string, category: string, entryLine: string): Ad
     content = `# ${title}\n`;
   }
   const newContent = content.trimEnd() + "\n" + entryLine + "\n";
-  if (newContent.length > MAX_TOPIC_CHARS) {
+  const cap = topicCharCap(topicName);
+  if (newContent.length > cap) {
+    log.warn("memory_topic_cap_rejected", { topic: topicName, chars: newContent.length, cap });
     return {
       status: "rejected",
       message:
-        `Topic "${topicName}" would exceed size limit (${newContent.length}/${MAX_TOPIC_CHARS} chars). ` +
+        `Topic "${topicName}" would exceed size limit (${newContent.length}/${cap} chars). ` +
         `Consolidate or remove entries first using memory_remove.`,
     };
   }

package/extensions/orchestrator/review-learning.ts

@@ -87,6 +87,8 @@ const MAX_LESSON_CHARS = 100;
 const STATE_FILE_NAME = "review-learning-state.json";
 /** Cap on tracked review ids — old reviews never re-distill in practice. */
 const MAX_TRACKED_REVIEWS = 200;
+/** Cap on the long-lived protection list that outlives MAX_TRACKED_REVIEWS. */
+const MAX_PROTECTED_LESSON_TEXTS = 5000;
 
 // ── Command matching ───────────────────────────────────────────────────────
 
@@ -350,17 +352,58 @@ export function loadReviewLessons(dataDir: string): Map<number, Set<string>> {
   return byReview;
 }
 
+/** Every distilled review-lesson text recorded in the state file, flattened.
+ *  Memory maintenance must treat these as learned knowledge, not history: the source
+ *  (the reviews DB) keeps the finding, but nothing re-materializes the topic line
+ *  once it is gone, so a dream that deletes one loses it for good (issue #1010).
+ *  Unions the bounded per-review map with the long-lived protection list so lessons
+ *  from reviews older than the tracking window stay protected. */
+export function distilledLessonTextList(dataDir: string): string[] {
+  const texts = new Set<string>();
+  for (const lessons of loadReviewLessons(dataDir).values()) {
+    for (const lesson of lessons) if (lesson.trim()) texts.add(lesson.trim());
+  }
+  for (const lesson of loadProtectedLessonTexts(dataDir)) if (lesson.trim()) texts.add(lesson.trim());
+  log.debug("distilled_lesson_texts_loaded", { count: texts.size });
+  return [...texts];
+}
+
 function writeStateFile(dataDir: string, distilledReviews: number[], reviewLessons: Map<number, Set<string>>): void {
   const lessons: Record<string, string[]> = {};
   const ids = [...reviewLessons.keys()];
   for (const id of ids.slice(-MAX_TRACKED_REVIEWS)) lessons[String(id)] = [...reviewLessons.get(id)!];
+  // Protection set for older reviews: `lessons` is bounded by MAX_TRACKED_REVIEWS, so
+  // without this union a lesson from review #1 stops being recognizable as reviewed
+  // knowledge once 200 newer reviews land, and memory maintenance may delete it (#1010).
+  const protectedTexts = new Set(loadProtectedLessonTexts(dataDir));
+  for (const set of reviewLessons.values()) for (const text of set) if (text.trim()) protectedTexts.add(text.trim());
   mkdirSync(dataDir, { recursive: true });
   writeFileSync(
     stateFilePath(dataDir),
-    `${JSON.stringify({ distilledReviews: distilledReviews.slice(-MAX_TRACKED_REVIEWS), reviewLessons: lessons }, null, 2)}\n`,
+    `${JSON.stringify(
+      {
+        distilledReviews: distilledReviews.slice(-MAX_TRACKED_REVIEWS),
+        reviewLessons: lessons,
+        protectedLessonTexts: [...protectedTexts].slice(-MAX_PROTECTED_LESSON_TEXTS),
+      },
+      null,
+      2,
+    )}\n`,
   );
 }
 
+/** Lesson texts that must stay recognizable as reviewed knowledge, independent of
+ *  the bounded per-review map. Empty on a fresh or unreadable state file. */
+export function loadProtectedLessonTexts(dataDir: string): string[] {
+  try {
+    const raw = JSON.parse(readFileSync(stateFilePath(dataDir), "utf-8"));
+    const texts = Array.isArray(raw?.protectedLessonTexts) ? raw.protectedLessonTexts : [];
+    return texts.filter((text: unknown): text is string => typeof text === "string" && text.trim().length > 0);
+  } catch {
+    return [];
+  }
+}
+
 /** Record a review id as distilled (bounded — oldest entries drop off). Fail-soft. */
 export function markReviewDistilled(dataDir: string, reviewId: number): void {
   try {

package/extensions/orchestrator/subagent-tool.ts

@@ -16,6 +16,8 @@ import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Message } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { createLogger } from "../shared/logger.js";
+import { sendSystemNote } from "../shared/system-note.js";
+import { publishedTaskStore } from "../shared/task-store-bridge.js";
 import { createBridgedUi } from "../shared/ui-bridge.js";
 import {
   getMarkdownTheme,
@@ -30,12 +32,44 @@ import {
 import { Type } from "typebox";
 import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.js";
 
-// Task store access via shared instance from extensions/pitasks
-let _taskStore: any = null;
+// Task store access via the pitasks module.
+// `taskStore` is `export let` — a live binding the pitasks extension assigns when it
+// initializes. Copying the value at import time captured `undefined` and disabled
+// task-id validation for the whole session (issue #1016), so the binding is read fresh.
+let _pitasksModule: any = null;
+let _pitasksLoad: Promise<any> | null = null;
+async function pitasksModule(): Promise<any> {
+  if (_pitasksModule) return _pitasksModule;
+  if (!_pitasksLoad) {
+    _pitasksLoad = (async () => {
+      try {
+        _pitasksModule = await import("../pitasks/index.js");
+        return _pitasksModule;
+      } catch (err) {
+        log.warn(`[subagent] pitasks module unavailable: ${String((err as Error)?.message ?? err).slice(0, 120)}`);
+        _pitasksLoad = null; // retry on the next call
+        return null;
+      }
+    })();
+  }
+  return _pitasksLoad;
+}
+
+/** The live task store, or null while pitasks has not initialized it yet.
+ *  Read from the global symbol registry: this tool's module instance cannot see the
+ *  pitasks extension's `export let taskStore` binding (it snapshots `undefined`), which
+ *  is why task-id validation silently failed open (issue #1016). */
 async function getTaskStore(): Promise<any> {
-  if (_taskStore) return _taskStore;
-  try { const mod = await import("../pitasks/index.js"); _taskStore = mod.taskStore; } catch { /* ignore */ }
-  return _taskStore;
+  const published = publishedTaskStore();
+  if (published) return published;
+  // Fall back to the module binding for in-process loads that share this instance.
+  const mod = await pitasksModule();
+  const store = mod?.taskStore ?? null;
+  if (!store) {
+    // Validation is about to be skipped: that is a degraded state, not routine flow.
+    log.warn("task_store_unavailable", { note: "pitasks store not initialized — taskId validation skipped" });
+  }
+  return store;
 }
 import {
   decideAsyncLlmDispatch,
@@ -153,7 +187,7 @@ const SubagentParams = Type.Object({
     Type.String({ description: "Display name for async agents in status line and notifications (e.g., 'Dream', 'Code Review'). Defaults to agent name." }),
   ),
   taskId: Type.Optional(
-    Type.String({ description: "Task ID to auto-complete when this async agent finishes. Required for async agents — pass \"-1\" if not linked to any task." }),
+    Type.String({ description: "Task ID to auto-complete when this async agent finishes. Required for async agents — pass \"-1\" only for a single read-only check; an agent that edits, pushes, or drives a PR needs a real task id." }),
   ),
   asyncKill: Type.Optional(
     Type.String({ description: "Kill async agent(s) by name, id prefix, or 'all'. Returns which agents were killed." }),
@@ -577,22 +611,27 @@ export async function runSingleAgent(
   }
 }
 
-/** Validate that a taskId references an existing task in the pitasks store. */
-function validateTaskId(taskId: string, _cwd: string, _sessionId?: string): string | null {
+/** The message for a task id the store does not know; null when it is valid or exempt. */
+export function taskIdError(taskId: string, lookup: (id: string) => boolean): string | null {
+  if (taskId === "-1") return null;
+  return lookup(taskId)
+    ? null
+    : `Task #${taskId} not found. Verify the task ID exists (use TaskList to check), or pass taskId: "-1" for a read-only check (editing or PR work needs a real task id).`;
+}
+
+/** Validate that a taskId references an existing task. Awaits the store load, so the
+ *  first async call of a session validates too instead of failing open (issue #1016). */
+async function validateTaskId(taskId: string, _cwd: string, _sessionId?: string): Promise<string | null> {
   if (taskId === "-1") return null;
+  const store = await getTaskStore();
+  if (!store) return null; // pitasks genuinely unavailable — warned in getTaskStore
   try {
-    // Ensure store is loaded (async init may not have completed)
-    if (!_taskStore) {
-      getTaskStore().catch(() => {});
-    }
-    const store = _taskStore;
-    if (!store) {
-      // Store not loaded yet (async init) — fail open, skip validation
-      return null;
-    }
-    if (store.get(taskId)) return null;
-  } catch { return null; }
-  return `Task #${taskId} not found. Verify the task ID exists (use TaskList to check), or pass taskId: "-1" if not linked to a task.`;
+    return taskIdError(taskId, (id) => Boolean(store.get(id)));
+  } catch (err) {
+    // Same fail-open as before, but a broken store must not look like a valid id.
+    log.warn("task_id_validation_failed", { reason: String((err as Error)?.message ?? err).slice(0, 120) });
+    return null;
+  }
 }
 
 // ── Registration ─────────────────────────────────────────────────────────
@@ -629,7 +668,7 @@ export function registerSubagentTool(
     };
   }
 
-  function executeAsync(
+  async function executeAsync(
     params: any,
     agents: AgentConfig[],
     mkd: (mode: "single" | "parallel" | "chain") => (results: SingleResult[]) => SubagentDetails,
@@ -659,13 +698,13 @@ export function registerSubagentTool(
       }
       const noTaskId = params.tasks.filter((t: any) => (t as any).taskId == null);
       if (noTaskId.length > 0) {
-        const errorMsg = `Missing required parameter: taskId. Every async agent MUST have a taskId.\n\nMissing taskId for: ${noTaskId.map((t: any) => t.agent).join(", ")}\n\nIf an agent is working on a task: pass the task ID (e.g., taskId: "5")\nIf an agent is NOT linked to any task: pass taskId: "-1"`;
+        const errorMsg = `Missing required parameter: taskId. Every async agent MUST have a taskId.\n\nMissing taskId for: ${noTaskId.map((t: any) => t.agent).join(", ")}\n\nIf an agent is working on a task: pass the task ID (e.g., taskId: "5")\nIf an agent is only doing a single read-only check: pass taskId: "-1" (editing or PR work needs a real task id)`;
         // Force a follow-up turn so the AI MUST deal with this error
-        pi.sendMessage({
-          customType: "subagent-taskid-error",
-          content: `🚨 CRITICAL: Async subagent call was REJECTED — missing taskId for: ${noTaskId.map((t: any) => t.agent).join(", ")}. NO agents were spawned. You MUST retry with taskId for each agent. Use TaskList to find task IDs, or pass taskId: "-1" if not linked.`,
-          display: true,
-        }, { triggerTurn: true, deliverAs: "followUp" });
+        await sendSystemNote(
+          pi,
+          `🚨 CRITICAL: Async subagent call was REJECTED — missing taskId for: ${noTaskId.map((t: any) => t.agent).join(", ")}. NO agents were spawned. You MUST retry with taskId for each agent. Use TaskList to find task IDs; "-1" is only for a single read-only check.`,
+          { customType: "subagent-taskid-error", triggerTurn: true, deliverAs: "followUp" },
+        );
         return {
           content: [{ type: "text" as const, text: errorMsg }],
           details: mkd("single")([]),
@@ -674,13 +713,13 @@ export function registerSubagentTool(
       }
       for (const t of params.tasks) {
         const tid = (t as any).taskId as string;
-        const taskErr = validateTaskId(tid, ctx.cwd, ctx.sessionManager?.getSessionId?.());
+        const taskErr = await validateTaskId(tid, ctx.cwd, ctx.sessionManager?.getSessionId?.());
         if (taskErr) {
-          pi.sendMessage({
-            customType: "subagent-taskid-error",
-            content: `🚨 CRITICAL: ${taskErr} (agent: ${t.agent}). NO agents were spawned. Fix the taskId and retry.`,
-            display: true,
-          }, { triggerTurn: true, deliverAs: "followUp" });
+          await sendSystemNote(
+            pi,
+            `🚨 CRITICAL: ${taskErr} (agent: ${t.agent}). NO agents were spawned. Fix the taskId and retry.`,
+            { customType: "subagent-taskid-error", triggerTurn: true, deliverAs: "followUp" },
+          );
           return {
             content: [{ type: "text" as const, text: `${taskErr} (agent: ${t.agent})` }],
             details: mkd("single")([]),
@@ -747,13 +786,13 @@ export function registerSubagentTool(
       };
     }
     if (params.taskId == null) {
-      const errorMsg = `Missing required parameter: taskId. Every async agent MUST have a taskId.\n\nIf this agent is working on a task: pass the task ID (e.g., taskId: "5")\nIf this agent is NOT linked to any task: pass taskId: "-1"\n\nExample: subagent(agent="${params.agent}", task="...", async=true, name="${params.name}", taskId="-1")`;
+      const errorMsg = `Missing required parameter: taskId. Every async agent MUST have a taskId.\n\nIf this agent is working on a task: pass the task ID (e.g., taskId: "5")\nIf this agent is only doing a single read-only check: pass taskId: "-1" (editing or PR work needs a real task id)\n\nExample: subagent(agent="${params.agent}", task="...", async=true, name="${params.name}", taskId="-1")`;
       // Force a follow-up turn so the AI MUST deal with this error
-      pi.sendMessage({
-        customType: "subagent-taskid-error",
-        content: `🚨 CRITICAL: Async subagent call for "${params.agent}" was REJECTED — missing taskId. The agent was NOT spawned. You MUST retry the subagent call with taskId. Use TaskList to find the task ID, or pass taskId: "-1" if not linked to any task. Do NOT proceed without fixing this.`,
-        display: true,
-      }, { triggerTurn: true, deliverAs: "followUp" });
+      await sendSystemNote(
+        pi,
+        `🚨 CRITICAL: Async subagent call for "${params.agent}" was REJECTED — missing taskId. The agent was NOT spawned. You MUST retry the subagent call with taskId. Use TaskList to find the task ID; "-1" is only for a single read-only check. Do NOT proceed without fixing this.`,
+        { customType: "subagent-taskid-error", triggerTurn: true, deliverAs: "followUp" },
+      );
       return {
         content: [{ type: "text" as const, text: errorMsg }],
         details: mkd("single")([]),
@@ -761,13 +800,13 @@ export function registerSubagentTool(
       };
     }
     {
-      const taskErr = validateTaskId(params.taskId, ctx.cwd, ctx.sessionManager?.getSessionId?.());
+      const taskErr = await validateTaskId(params.taskId, ctx.cwd, ctx.sessionManager?.getSessionId?.());
       if (taskErr) {
-        pi.sendMessage({
-          customType: "subagent-taskid-error",
-          content: `🚨 CRITICAL: ${taskErr} The agent was NOT spawned. Fix the taskId and retry.`,
-          display: true,
-        }, { triggerTurn: true, deliverAs: "followUp" });
+        await sendSystemNote(
+          pi,
+          `🚨 CRITICAL: ${taskErr} The agent was NOT spawned. Fix the taskId and retry.`,
+          { customType: "subagent-taskid-error", triggerTurn: true, deliverAs: "followUp" },
+        );
         return {
           content: [{ type: "text" as const, text: taskErr }],
           details: mkd("single")([]),
@@ -1689,7 +1728,7 @@ export function registerSubagentTool(
 
       // Async mode — spawn in background and return immediately
       if (params.async === true) {
-        const result = executeAsync(params, agents, mkd, parentModelId, parentProvider, ctx, explicit);
+        const result = await executeAsync(params, agents, mkd, parentModelId, parentProvider, ctx, explicit);
         if (capabilityNote && result.content?.[0]?.type === "text") {
           result.content[0].text = `${capabilityNote}\n\n${result.content[0].text}`;
         }

package/extensions/pitasks/index.ts

@@ -11,6 +11,7 @@ import { TaskStore } from "./task-store.js";
 import { TaskWidget } from "./task-widget.js";
 import { registerTaskTools } from "./task-tools.js";
 import { createLogger } from "../shared/logger.js";
+import { publishTaskStore } from "../shared/task-store-bridge.js";
 import { createBridgedUi } from "../shared/ui-bridge.js";
 import { getSetting } from "../orchestrator/project-settings.js";
 import { shouldSkipOneshotRegister } from "../shared/oneshot.js";
@@ -43,6 +44,11 @@ export function setTaskTelemetryActive(taskId: string, active = true): void {
 /** Exported store instance — set during extension init. */
 export let taskStore: TaskStore;
 
+// The store is published to other extension modules through the shared bridge: they
+// cannot read this `export let` binding (they would snapshot `undefined`), which silently
+// disabled task-id validation (issue #1016). Published once, from registration only —
+// the bridge's getter follows later store swaps, so the upgrade path needs no republish.
+
 /** Create a task directly — for use by other extensions (e.g., coms auto-create). */
 export function createTask(subject: string, description: string, createdBy?: any, metadata?: Record<string, any>): any {
 	return taskStore.create(subject, description, createdBy || { type: "local", origin: "system", session: "", project: "" }, undefined, metadata);
@@ -189,6 +195,8 @@ export default function (pi: ExtensionAPI) {
 	currentWidget?.dispose();
 	let store = new TaskStore(resolveStorePath());
 	taskStore = store;
+	// Registration is the only publish site: the getter follows store swaps.
+	publishTaskStore(() => taskStore);
 	currentStore = store;
 	const widget = new TaskWidget(store);
 	store.setOnChange(() => { widget.update(); broadcastTasks(); });

package/extensions/shared/system-note.ts

@@ -0,0 +1,44 @@
+/**
+ * Provenance-marked injections for content the user did NOT write.
+ *
+ * The transcript gives an extension no room to say "this is not the user's words":
+ * `pi.sendMessage` renders as `role: "custom"` and `pi.sendUserMessage` renders as a
+ * user turn, so machine text arrives looking exactly like something the user typed.
+ * A model reading it will answer "as you said" and attribute its own guard rails to the
+ * user (issue #1016 review, where a REJECTED call looked like a user message).
+ *
+ * Every message this module sends starts with MARKER, which is self-explanatory on
+ * purpose: no rule has to teach the model what it means.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createLogger } from "./logger.js";
+
+const log = createLogger("system-note");
+
+/** Prefix that identifies machine-generated text in the transcript. */
+export const SYSTEM_NOTE_MARKER = "[system message — not written by the user]";
+
+export interface SystemNoteOptions {
+  /** Stable kind for renderers/filters, e.g. "subagent-taskid-error". */
+  customType: string;
+  /** Start a turn from this message when the session is idle. */
+  triggerTurn?: boolean;
+  /** Delivery slot for a busy session. */
+  deliverAs?: "steer" | "followUp" | "nextTurn";
+  /** Render in the TUI transcript. */
+  display?: boolean;
+}
+
+/** Send machine-generated text, marked so it cannot be mistaken for user input. */
+export async function sendSystemNote(
+  pi: ExtensionAPI,
+  text: string,
+  options: SystemNoteOptions,
+): Promise<void> {
+  const body = text.startsWith(SYSTEM_NOTE_MARKER) ? text : `${SYSTEM_NOTE_MARKER}\n${text}`;
+  log.debug("send_system_note", { customType: options.customType, chars: body.length });
+  await pi.sendMessage(
+    { customType: options.customType, content: body, display: options.display ?? true },
+    { triggerTurn: options.triggerTurn, deliverAs: options.deliverAs },
+  );
+}

package/extensions/shared/task-store-bridge.ts

@@ -0,0 +1,43 @@
+/**
+ * Cross-module bridge for the pitasks store.
+ *
+ * `pitasks` exports `taskStore` as `export let`, assigned when the extension
+ * initializes. Another extension's module instance cannot read that binding: it
+ * snapshots `undefined` at import time, which silently disabled task-id validation
+ * (issue #1016). The store is therefore published on the global symbol registry, and
+ * the published object reads the live binding on every access — publishing once is
+ * enough, and a store swap needs no republish.
+ *
+ * Publish only from the instance that owns the store (pitasks registration), never from
+ * module-load code: a duplicate import would otherwise displace the real getter with one
+ * bound to a store that instance never creates.
+ *
+ * Same pattern as the pricing-provenance and session-cwd markers.
+ */
+import { createLogger } from "./logger.js";
+
+const log = createLogger("task-store-bridge");
+
+export const TASK_STORE_SYMBOL = Symbol.for("pi-config.taskStore");
+
+interface TaskStoreBridge {
+  readonly current: unknown;
+}
+
+/** Publish a getter over the live store binding. Called by the owning extension. */
+export function publishTaskStore(getStore: () => unknown): void {
+  (globalThis as Record<symbol, unknown>)[TASK_STORE_SYMBOL] = {
+    get current(): unknown {
+      return getStore();
+    },
+  } satisfies TaskStoreBridge;
+  log.debug("task_store_bridge_published", { at: Date.now() });
+}
+
+/** The published store, or null when the owning extension has not registered. */
+export function publishedTaskStore(): unknown {
+  const bridge = (globalThis as Record<symbol, unknown>)[TASK_STORE_SYMBOL] as TaskStoreBridge | undefined;
+  const store = bridge?.current ?? null;
+  log.debug("task_store_bridge_read", { found: Boolean(store) });
+  return store;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-orchestrator-config",
-  "version": "4.24.0",
+  "version": "4.24.2",
   "description": "Orchestrator pattern for pi: specialist subagents, enforcement, code review loop, workflow commands",
   "keywords": [
     "pi-package"

package/rules/00-orchestrator-core.md

@@ -34,7 +34,8 @@ Outside slash commands, never use edit, write, or bash directly (except `codemod
 
 ## Before Implementation (MANDATORY)
 
-**For 2+ distinct actions, your first action is one `TaskBulkCreate` listing every step** — before the first edit or the first agent call (see `60-task-tracking.md`).
+**For 2+ distinct actions — requested, or set in motion by an async result — your first action is one `TaskBulkCreate` listing every step**
+— before the first edit or the first agent call (see `60-task-tracking.md`).
 
 Before ANY code changes, run the pre-implementation checklist:
 

package/rules/40-critical-rules.md

@@ -34,7 +34,7 @@ its output. Use it ONLY for work whose result nobody consumes — in pi-config,
 dreaming and nothing else. Every watcher, poll, and review agent exists to report
 something back, so leave `fireAndForget` unset for them. If you are about to set it,
 ask whether you will ever read the result; if yes, do not set it.
-**`taskId` is required on every async call** (use `-1` when unlinked) — a call without
+**`taskId` is required on every async call** (`-1` only for a single read-only check; anything that edits, pushes, or drives a PR needs a real task id) — a call without
 it is rejected, and the agent does not run.
 
 Do NOT write bash loops, sleep commands, or poll for results after spawning async agents.

package/rules/60-task-tracking.md

@@ -9,12 +9,13 @@
 
 ## When Tasks Are Required
 
-The request needs **2+ distinct actions** — then tasks are required:
+The request — **or work any step sets in motion** — needs **2+ distinct actions** — then tasks are required:
 
 - more than one file to change, or code plus tests plus docs
 - any workflow from `05-issue-first-workflow.md` or `20-code-review-loop.md`
 - the user lists several things to do ("do X, then Y", numbered items)
 - work conditioned on a future event ("after Qodo approves, deploy and test") — create the tasks now, put the trigger in the description, and block the dependents on it
+- an async result comes back with follow-up work — reacting only to finished agents still needs a board
 
 **No tasks:** a single-step action, a one-file/one-line change, a question, an explanation, read-only investigation.
 
@@ -22,6 +23,10 @@ The request needs **2+ distinct actions** — then tasks are required:
 
 Plan the whole job in **one `TaskBulkCreate` call** listing every step — not one `TaskCreate` per step, and not after the first edit. `TaskCreate` is for a single step added later.
 
+**Before dispatching new work, reconcile the board (MANDATORY):** complete, re-scope, or
+delete stale tasks. Dispatching over a task that is `in_progress` for work that already changed
+is a violation.
+
 When `TaskCreate`'s own tool description suggests per-step calls, **this rule wins**: one bulk call for the whole job.
 
 ## Granularity
@@ -31,10 +36,22 @@ One concrete action per task: which file, which change.
 - ❌ `Implement the fix` / `Create PR`
 - ✅ `Edit extensions/orchestrator/utils.ts — add timeout parameter to fetchData()` / `Create PR with the test plan`
 
+**Multi-issue work:** one task per **stage** per issue, named `#<n>: <stage>` (e.g.
+`#1016: contract test`). Later stages carry `blockedBy` in the bulk create — `addBlockedBy` is an
+update field, and stage ids only exist after the call returns, so wire them with `TaskUpdate` if
+the order was not set at creation. File-level detail lives in the description, not the subject.
+
 ## Lifecycle
 
 `in_progress` before starting a task, `completed` immediately after. Work in order. Never abandon a task — drop a stale one with `TaskUpdate status: "deleted"`.
 
+**When an async result arrives, update the board in that same turn:** on success complete the
+owning task, then plan any follow-up in one `TaskBulkCreate` and activate its first stage. A
+failed agent keeps its task open — the runtime never auto-completes a failure, and closing it
+would activate a stage whose input never arrived.
+
+Status reports come from `TaskList`, not recollection.
+
 ## Side Questions
 
 Answer the question, then resume the next unchecked task — the task list says where you left off.
@@ -44,14 +61,18 @@ Answer the question, then resume the next unchecked task — the task list says
 ## Async Agent taskId (MANDATORY — code-enforced)
 
 **Every async agent call MUST include `taskId`.** Enforced — calls without it are rejected.
-Pass the task ID (e.g., `"5"`) when linked to a task, or `"-1"` when not.
-Linked tasks auto-complete on agent success — no manual `TaskUpdate` needed.
+Pass the id of the task the agent performs (e.g. `"5"`). `"-1"` is only for a single read-only
+check that changes nothing: an agent that edits code, pushes, or drives a PR must carry a real
+task id, because an unlinked poll is work that never appears on the board.
 
 ```text
 subagent(agent="code-reviewer-quality", task="...", cwd="...", async=true, name="Review", taskId="5")
-subagent(agent="worker", task="...", cwd="...", async=true, name="Qodo Poll", taskId="-1")
+subagent(agent="worker", task="...", cwd="...", async=true, name="Read one file", taskId="-1")
 ```
 
-- ✅ **ALWAYS** pass `taskId` — auto-completes on success, stays `in_progress` on failure
-- ❌ **NEVER** manually `TaskUpdate` a task to `completed` if it has an async agent
+**Stage tasks are yours to close.** An agent links to the narrow task it performs; the stage
+completes when the stage's acceptance holds — binding a stage to a poll marks it done when
+only the poll finished.
+
+- ❌ **NEVER** let a narrow agent task stand in for a stage — auto-complete ends the task the agent was linked to
 - ❌ **NEVER** omit `taskId` — the call will fail