@neriros/ralphy 3.2.0 → 3.3.0

package/dist/shell/index.js

@@ -18928,8 +18928,8 @@ import { readFileSync } from "fs";
 import { resolve } from "path";
 function getVersion() {
   try {
-    if ("3.2.0")
-      return "3.2.0";
+    if ("3.3.0")
+      return "3.3.0";
   } catch {}
   const dirsToTry = [];
   try {
@@ -59219,11 +59219,10 @@ var init_use_app = __esm(() => {
 });
 
 // node_modules/.bun/ink@5.2.1+1f88f629f0141b18/node_modules/ink/build/hooks/use-stdout.js
-var import_react18, useStdout = () => import_react18.useContext(StdoutContext_default), use_stdout_default;
+var import_react18;
 var init_use_stdout = __esm(() => {
   init_StdoutContext();
   import_react18 = __toESM(require_react(), 1);
-  use_stdout_default = useStdout;
 });
 
 // node_modules/.bun/ink@5.2.1+1f88f629f0141b18/node_modules/ink/build/hooks/use-stderr.js
@@ -59448,6 +59447,50 @@ function runOpenspec(args, options = {}) {
     stderr: proc.stderr ? decoder.decode(proc.stderr) : ""
   };
 }
+function appendSteeringTaskToTasksMd(existing, taskLine) {
+  const SECTION = "## Steering";
+  const trimmed = existing.replace(/\s+$/, "");
+  if (trimmed.length === 0) {
+    return `${SECTION}
+
+${taskLine}
+`;
+  }
+  const lines = trimmed.split(/\r?\n/);
+  let sectionStart = -1;
+  for (let i = 0;i < lines.length; i += 1) {
+    if (/^##\s+Steering\s*$/i.test(lines[i])) {
+      sectionStart = i;
+      break;
+    }
+  }
+  if (sectionStart === -1) {
+    return `${trimmed}
+
+${SECTION}
+
+${taskLine}
+`;
+  }
+  let sectionEnd = lines.length;
+  for (let i = sectionStart + 1;i < lines.length; i += 1) {
+    if (/^##\s+/.test(lines[i])) {
+      sectionEnd = i;
+      break;
+    }
+  }
+  let insertAt = sectionEnd;
+  while (insertAt - 1 > sectionStart && (lines[insertAt - 1] ?? "").trim() === "") {
+    insertAt -= 1;
+  }
+  const before2 = lines.slice(0, insertAt);
+  const after2 = lines.slice(insertAt);
+  const out = [...before2, taskLine, ...after2.length ? [""] : [], ...after2].join(`
+`);
+  return out.endsWith(`
+`) ? out : `${out}
+`;
+}
 
 class OpenSpecChangeStore {
   async createChange(name, description) {
@@ -59504,6 +59547,16 @@ ${existing.trimStart()}` : `${message}
 `;
     await mkdir(dirname4(path), { recursive: true });
     await Bun.write(path, updated);
+    const firstLine = message.split(/\r?\n/).map((l) => l.trim()).find((l) => l.length > 0) ?? message.trim();
+    if (firstLine.length === 0)
+      return;
+    const tasksPath = join6("openspec", "changes", name, "tasks.md");
+    const tasksFile = Bun.file(tasksPath);
+    const existingTasks = await tasksFile.exists() ? await tasksFile.text() : "";
+    const taskLine = `- [ ] Address steering: ${firstLine}`;
+    const next = appendSteeringTaskToTasksMd(existingTasks, taskLine);
+    await mkdir(dirname4(tasksPath), { recursive: true });
+    await Bun.write(tasksPath, next);
   }
   async readSection(name, artifact, heading) {
     const file = Bun.file(join6("openspec", "changes", name, artifact));
@@ -63850,7 +63903,12 @@ var init_types2 = __esm(() => {
     createPr: exports_external.boolean().default(false),
     usage: UsageSchema.default({}),
     history: exports_external.array(HistoryEntrySchema).default([]),
-    metadata: exports_external.object({ branch: exports_external.string().optional() }).default({})
+    metadata: exports_external.object({ branch: exports_external.string().optional() }).default({}),
+    linearComments: exports_external.object({
+      planCommentId: exports_external.string().nullable().default(null),
+      tasksCommentId: exports_external.string().nullable().default(null),
+      planPostedAt: exports_external.string().nullable().default(null)
+    }).default({ planCommentId: null, tasksCommentId: null, planPostedAt: null })
   });
   PhaseFrontmatterSchema = exports_external.object({
     name: exports_external.string(),
@@ -68802,21 +68860,26 @@ function readSize() {
     rows: process.stdout.rows ?? 24
   };
 }
+function clearScreenAndScrollback() {
+  if (process.stdout.isTTY)
+    process.stdout.write("\x1B[2J\x1B[3J\x1B[H");
+}
 function useTerminalSize() {
-  const [size2, setSize] = import_react53.useState(() => ({
-    ...readSize(),
-    resizeKey: 0
-  }));
+  const initial2 = import_react53.useRef({ ...readSize(), resizeKey: 0 });
+  const [size2, setSize] = import_react53.useState(initial2.current);
+  const sizeRef = import_react53.useRef(initial2.current);
   import_react53.useEffect(() => {
     if (!process.stdout.isTTY)
       return;
     const onResize = () => {
       const { columns, rows } = readSize();
-      setSize((prev) => {
-        if (prev.columns === columns && prev.rows === rows)
-          return prev;
-        return { columns, rows, resizeKey: prev.resizeKey + 1 };
-      });
+      const prev = sizeRef.current;
+      if (prev.columns === columns && prev.rows === rows)
+        return;
+      clearScreenAndScrollback();
+      const next = { columns, rows, resizeKey: prev.resizeKey + 1 };
+      sizeRef.current = next;
+      setSize(next);
     };
     process.stdout.on("resize", onResize);
     return () => {
@@ -70863,14 +70926,8 @@ function TaskLoop({ opts }) {
   const { exit } = use_app_default();
   const loop = useLoop(opts);
   const { isRawModeSupported } = use_stdin_default();
-  const { stdout } = use_stdout_default();
   const { resizeKey } = useTerminalSize();
   const bannerItem = import_react56.useRef({ id: "__banner__", kind: "banner" });
-  import_react56.useEffect(() => {
-    if (resizeKey === 0)
-      return;
-    stdout.write("\x1B[2J\x1B[3J\x1B[H");
-  }, [resizeKey, stdout]);
   const feedItems = import_react56.useMemo(() => [
     bannerItem.current,
     ...loop.logLines.map((e) => ({ id: e.id, kind: "entry", entry: e }))
@@ -92410,7 +92467,7 @@ var init_zod2 = __esm(() => {
 });
 
 // packages/workflow/src/schema.ts
-var MarkerSchema, GetIndicatorSchema, SetIndicatorSchema, IndicatorsSchema, ProjectSchema, CommandsSchema, BoundariesSchema, WorkflowConfigSchema;
+var MarkerSchema, GetIndicatorSchema, SetIndicatorSchema, IndicatorsSchema, ProjectSchema, CommandsSchema, DEFAULT_META_ONLY_FILES, BoundariesSchema, WorkflowConfigSchema;
 var init_schema = __esm(() => {
   init_zod2();
   MarkerSchema = exports_external2.object({
@@ -92421,7 +92478,7 @@ var init_schema = __esm(() => {
     filter: exports_external2.array(MarkerSchema).default([])
   });
   SetIndicatorSchema = exports_external2.union([exports_external2.array(MarkerSchema).min(1), MarkerSchema]);
-  IndicatorsSchema = exports_external2.object({
+  IndicatorsSchema = exports_external2.preprocess((v) => v == null ? {} : v, exports_external2.object({
     getTodo: GetIndicatorSchema.optional(),
     getInProgress: GetIndicatorSchema.optional(),
     getConflicted: GetIndicatorSchema.optional(),
@@ -92450,7 +92507,7 @@ var init_schema = __esm(() => {
         }
       }
     }
-  });
+  }));
   ProjectSchema = exports_external2.object({
     name: exports_external2.string().optional(),
     language: exports_external2.string().optional(),
@@ -92462,9 +92519,17 @@ var init_schema = __esm(() => {
     build: exports_external2.string().optional(),
     typecheck: exports_external2.string().optional()
   }).catchall(exports_external2.string()).default({});
+  DEFAULT_META_ONLY_FILES = [
+    "openspec/**",
+    ".ralph/**",
+    "**/agent-tasks.md",
+    "**/tasks.md",
+    "**/MANUAL_TESTING*.md"
+  ];
   BoundariesSchema = exports_external2.object({
-    never_touch: exports_external2.array(exports_external2.string()).default([])
-  }).strict().default({ never_touch: [] });
+    never_touch: exports_external2.array(exports_external2.string()).default([]),
+    meta_only_files: exports_external2.array(exports_external2.string()).default(DEFAULT_META_ONLY_FILES)
+  }).strict().default({ never_touch: [], meta_only_files: DEFAULT_META_ONLY_FILES });
   WorkflowConfigSchema = exports_external2.object({
     project: ProjectSchema,
     commands: CommandsSchema,
@@ -92501,20 +92566,20 @@ var init_schema = __esm(() => {
       assignee: exports_external2.string().optional(),
       postComments: exports_external2.boolean().default(true),
       updateEveryIterations: exports_external2.number().int().nonnegative().default(10),
-      mentionTrigger: exports_external2.boolean().default(false),
+      mentionTrigger: exports_external2.boolean().default(true),
       mentionHandle: exports_external2.string().default("@ralphy"),
-      codeReviewTrigger: exports_external2.boolean().default(false),
+      codeReviewTrigger: exports_external2.boolean().default(true),
       codeReviewStaleHours: exports_external2.number().nonnegative().default(24),
-      syncTasksToDescription: exports_external2.boolean().default(false),
+      syncTasksToComment: exports_external2.boolean().default(true),
       indicators: IndicatorsSchema.default({})
     }).strict().default({
       postComments: true,
       updateEveryIterations: 10,
-      mentionTrigger: false,
+      mentionTrigger: true,
       mentionHandle: "@ralphy",
-      codeReviewTrigger: false,
+      codeReviewTrigger: true,
       codeReviewStaleHours: 24,
-      syncTasksToDescription: false,
+      syncTasksToComment: true,
       indicators: {}
     }),
     github: exports_external2.object({
@@ -92573,70 +92638,71 @@ boundaries:
   never_touch:
     - "dist/**"
     - ".claude/worktrees/**"
-
+  # Files that count as "meta only" for the pre-PR substantive-diff guard.
+  # If every changed file matches one of these globs, the loop refuses to
+  # open the PR and respawns the worker \u2014 the actual implementation was
+  # lost (either deleted mid-loop or absorbed by a merge from base).
+  meta_only_files:
+    - "openspec/**"
+    - ".ralph/**"
+    - "**/agent-tasks.md"
+    - "**/tasks.md"
+    - "**/MANUAL_TESTING*.md"
+
+# \u2500\u2500\u2500 Scheduling \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 # How many tasks to run in parallel.
 concurrency: 1
-
 # Seconds between polls for new Linear issues (agent mode).
 pollIntervalSeconds: 60
+# Seconds to wait between loop iterations (throttle).
+iterationDelaySeconds: 0
 
-# Maximum iterations per task. 0 = unlimited.
+# \u2500\u2500\u2500 Per-task limits (0 = unlimited) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 maxIterationsPerTask: 0
-
-# Maximum cost in USD per task. 0 = unlimited.
 maxCostUsdPerTask: 0
-
-# Maximum wall-clock minutes per task. 0 = unlimited.
 maxRuntimeMinutesPerTask: 0
-
 # Stop a task after this many consecutive identical failures.
 maxConsecutiveFailuresPerTask: 5
 
-# Seconds to wait between loop iterations (throttle).
-iterationDelaySeconds: 0
-
+# \u2500\u2500\u2500 Engine \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+# Underlying engine: "claude" or "codex".
+engine: claude
+# Model tier: "haiku", "sonnet", or "opus".
+model: opus
 # Log the raw engine stream to stdout.
 logRawStream: false
-
 # Pass --verbose to the ralph task sub-process.
 taskVerbose: false
 
+# \u2500\u2500\u2500 Worktree \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 # Run each task in an isolated git worktree.
 useWorktree: false
-
 # Delete the worktree after a successful task.
 cleanupWorktreeOnSuccess: false
 
+# \u2500\u2500\u2500 Pull requests \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 # Open a pull request after a task succeeds.
 createPrOnSuccess: false
-
 # Base branch for pull requests.
 prBaseBranch: main
-
 # When true, stack dependent issues' PRs onto their blocker's open PR.
 stackPrsOnDependencies: false
-
 # Strategy used when GitHub auto-merge is enabled.
 autoMergeStrategy: squash
 
+# \u2500\u2500\u2500 CI auto-fix \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 # Let the agent attempt to fix CI failures after a PR is created.
 fixCiOnFailure: false
-
 # Maximum number of CI-fix attempts per task.
 maxCiFixAttempts: 5
-
 # Seconds between CI status polls.
 ciPollIntervalSeconds: 30
 
-# Underlying engine: "claude" or "codex".
-engine: claude
-
-# Model tier: "haiku", "sonnet", or "opus".
-model: opus
-
-# Pre-existing error check: gate the agent when the base branch is already broken.
-# When enabled, the agent runs these commands against the base branch HEAD before
-# scheduling new work; failures open a Linear ticket and pause new pickups.
+# \u2500\u2500\u2500 Base-branch health gate \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+# Pre-existing error check: gate the agent when the base branch is already
+# broken. When enabled, the agent runs these commands against the base
+# branch HEAD before scheduling new work; failures open a Linear ticket
+# and pause new pickups.
 preExistingErrorCheck:
   enabled: false
   # Commands to run against the base branch. When empty, falls back to commands.lint / commands.test.
@@ -92645,38 +92711,49 @@ preExistingErrorCheck:
   label: "ralph:pre-existing-error"
   outputCharLimit: 4000
 
+# \u2500\u2500\u2500 Linear integration \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 linear:
   # Linear team key (e.g. "ENG"). Omit to match all teams.
   # team: ENG
 
   # Post progress comments on the Linear issue while a task is running.
   postComments: true
-
   # Post a progress update every N iterations. 0 disables.
   updateEveryIterations: 10
 
   # Watch done-issue comments + linked GitHub PR comments for @ralphy mentions.
-  mentionTrigger: false
+  mentionTrigger: true
   mentionHandle: "@ralphy"
 
   # Watch open tracked PRs for unresolved review-thread comments.
-  codeReviewTrigger: false
+  codeReviewTrigger: true
   codeReviewStaleHours: 24
 
-  # Mirror the loop's tasks.md into the Linear issue description as a
-  # checklist between sentinel markers. Updates on worker launch, on the
-  # same cadence as updateEveryIterations, and on done-transition.
-  syncTasksToDescription: false
+  # Mirror the loop's tasks.md into a sticky Linear comment (always the
+  # last comment on the issue). Updates on worker launch, on the same
+  # cadence as updateEveryIterations, and on done-transition.
+  syncTasksToComment: true
 
   # Indicators map Ralph lifecycle events to Linear labels/statuses.
-  # Grouped by lifecycle: each get* is followed by the set*/clear* that
-  # mutates the same state, so the lifecycle reads top-to-bottom.
-  indicators: {}
-    # Todo -> In Progress
+  #
+  # Filter semantics (per indicator's \`filter:\` list):
+  #   \u2022 Entries of the SAME type (e.g. two \`status\` entries) are ORed
+  #     \u2014 the issue matches if any value matches.
+  #   \u2022 Entries of DIFFERENT types (one \`status\` + one \`label\`) are
+  #     ANDed \u2014 the issue must satisfy every type.
+  #   Example: a filter with two statuses + one label matches issues
+  #   where status \u2208 {A, B} AND label = L.
+  #
+  # Sections below group one state at a time; its get/set/clear sit
+  # adjacent so the lifecycle reads top-to-bottom.
+  indicators:
+    # \u2500\u2500 Todo (pickup trigger) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
     # getTodo:
     #   filter:
     #     - type: status
     #       value: Todo
+    #
+    # \u2500\u2500 In Progress \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
     # getInProgress:
     #   filter:
     #     - type: status
@@ -92685,7 +92762,7 @@ linear:
     #   type: status
     #   value: In Progress
     #
-    # # Done / review hand-off
+    # \u2500\u2500 Done \u2192 Review hand-off \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
     # setDone:
     #   type: status
     #   value: In Review
@@ -92697,7 +92774,7 @@ linear:
     #   type: label
     #   value: "ralph:review"
     #
-    # # Conflict lifecycle
+    # \u2500\u2500 Conflicted \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
     # getConflicted:
     #   filter:
     #     - type: label
@@ -92709,13 +92786,13 @@ linear:
     #   type: label
     #   value: "ralph:conflict"
     #
-    # # Auto-merge opt-in
+    # \u2500\u2500 Auto-merge (opt-in) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
     # getAutoMerge:
     #   filter:
     #     - type: label
     #       value: "ralph:auto-merge"
     #
-    # # Error quarantine
+    # \u2500\u2500 Error quarantine \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
     # setError:
     #   type: label
     #   value: "ralph:error"
@@ -93693,28 +93770,102 @@ async function fetchOpenIssues(apiKey, spec) {
     blockedByIds: (n.relations?.nodes ?? []).filter((r) => r.type === "blocked_by" && !DONE_STATE_TYPES.has(r.relatedIssue.state.type)).map((r) => r.relatedIssue.id)
   }));
 }
+function isRetryableStatus(status) {
+  return status >= 500 && status <= 599;
+}
+function parseRetryAfter(header) {
+  if (!header)
+    return;
+  const trimmed = header.trim();
+  if (!trimmed)
+    return;
+  const asNum = Number(trimmed);
+  if (Number.isFinite(asNum))
+    return Math.max(0, asNum * 1000);
+  const asDate = Date.parse(trimmed);
+  if (Number.isFinite(asDate))
+    return Math.max(0, asDate - Date.now());
+  return;
+}
+function backoffMs(attempt2) {
+  const base2 = 250 * 2 ** (attempt2 - 1);
+  const jitter = Math.floor(Math.random() * 100);
+  return base2 + jitter;
+}
+function isRateLimitedBody(body) {
+  if (typeof body !== "string" || body.length === 0)
+    return false;
+  return body.toLowerCase().includes("rate limit exceeded");
+}
+function isRateLimitedError(err) {
+  if (err === null || typeof err !== "object")
+    return false;
+  return err.rateLimited === true;
+}
+function formatLinearError(err) {
+  if (err === null || err === undefined)
+    return String(err);
+  if (typeof err !== "object")
+    return String(err);
+  const e = err;
+  const parts = [];
+  if (e.rateLimited)
+    parts.push("rate limited");
+  if (typeof e.status === "number")
+    parts.push(`HTTP ${e.status}`);
+  if (Array.isArray(e.messages) && e.messages.length > 0) {
+    parts.push(`graphql: ${e.messages.join("; ")}`);
+  }
+  if (typeof e.body === "string" && e.body.length > 0 && !e.rateLimited) {
+    const truncated = e.body.length > 200 ? `${e.body.slice(0, 200)}\u2026` : e.body;
+    parts.push(`body: ${truncated}`);
+  }
+  if (parts.length === 0) {
+    if (typeof e.message === "string" && e.message)
+      return e.message;
+    return String(err);
+  }
+  if (typeof e.message === "string" && e.message && !e.rateLimited)
+    parts.unshift(e.message);
+  return parts.join(" \u2014 ");
+}
 async function linearRequest(apiKey, query, variables) {
-  const res = await fetch(LINEAR_API, {
-    method: "POST",
-    headers: { "Content-Type": "application/json", Authorization: apiKey },
-    body: JSON.stringify({ query, variables })
-  });
-  if (!res.ok) {
-    const err = new Error("Linear API request failed");
-    err.status = res.status;
-    err.body = await res.text();
-    throw err;
-  }
-  const json2 = await res.json();
-  if (json2.errors?.length) {
-    const err = new Error("Linear API returned errors");
-    err.messages = json2.errors.map((e) => e.message);
-    throw err;
-  }
-  if (!json2.data) {
-    throw new Error("Linear API returned no data");
+  let lastHttpError;
+  for (let attempt2 = 1;attempt2 <= MAX_LINEAR_ATTEMPTS; attempt2++) {
+    const res = await fetch(LINEAR_API, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: apiKey },
+      body: JSON.stringify({ query, variables })
+    });
+    if (!res.ok) {
+      const err = new Error("Linear API request failed");
+      err.status = res.status;
+      err.body = await res.text();
+      if (res.status === 429 || isRateLimitedBody(err.body)) {
+        err.rateLimited = true;
+        throw err;
+      }
+      lastHttpError = err;
+      if (isRetryableStatus(res.status) && attempt2 < MAX_LINEAR_ATTEMPTS) {
+        const ra = parseRetryAfter(res.headers.get("Retry-After"));
+        const waitMs = Math.min(ra ?? backoffMs(attempt2), MAX_RETRY_AFTER_MS);
+        await linearRequestInternals.sleep(waitMs);
+        continue;
+      }
+      throw err;
+    }
+    const json2 = await res.json();
+    if (json2.errors?.length) {
+      const err = new Error("Linear API returned errors");
+      err.messages = json2.errors.map((e) => e.message);
+      throw err;
+    }
+    if (!json2.data) {
+      throw new Error("Linear API returned no data");
+    }
+    return json2.data;
   }
-  return json2.data;
+  throw lastHttpError ?? new Error("Linear API request failed");
 }
 async function addReactionToComment(apiKey, commentId, emoji3) {
   const mutation = `mutation Reaction($commentId: String!, $emoji: String!) {
@@ -93734,6 +93885,36 @@ async function addIssueComment(apiKey, issueId, body) {
     body
   });
 }
+async function createIssueComment(apiKey, issueId, body) {
+  const mutation = `mutation Comment($issueId: String!, $body: String!) {
+    commentCreate(input: { issueId: $issueId, body: $body }) {
+      success
+      comment { id }
+    }
+  }`;
+  const data = await linearRequest(apiKey, mutation, { issueId, body });
+  const id = data.commentCreate.comment?.id;
+  if (!id)
+    throw new Error("commentCreate returned no comment id");
+  return id;
+}
+async function updateIssueComment(apiKey, commentId, body) {
+  const mutation = `mutation UpdateComment($id: String!, $body: String!) {
+    commentUpdate(id: $id, input: { body: $body }) { success }
+  }`;
+  await linearRequest(apiKey, mutation, {
+    id: commentId,
+    body
+  });
+}
+async function deleteIssueComment(apiKey, commentId) {
+  const mutation = `mutation DeleteComment($id: String!) {
+    commentDelete(id: $id) { success }
+  }`;
+  await linearRequest(apiKey, mutation, {
+    id: commentId
+  });
+}
 async function fetchIssueComments(apiKey, issueId) {
   const query = `query Comments($id: String!) {
     issue(id: $id) {
@@ -93956,7 +94137,12 @@ async function removeLabelFromIssue(apiKey, issueId, labelId) {
     labelId
   });
 }
-var LINEAR_API = "https://api.linear.app/graphql", RALPHY_ATTACHMENT_TITLE_FILTER = "Ralphy", RALPHY_ATTACHMENT_TITLE = "Ralphy", BRANCH_LABEL_PREFIX = "ralph:branch:";
+var LINEAR_API = "https://api.linear.app/graphql", RALPHY_ATTACHMENT_TITLE_FILTER = "Ralphy", linearRequestInternals, MAX_LINEAR_ATTEMPTS = 3, MAX_RETRY_AFTER_MS = 2000, RALPHY_ATTACHMENT_TITLE = "Ralphy", BRANCH_LABEL_PREFIX = "ralph:branch:";
+var init_linear = __esm(() => {
+  linearRequestInternals = {
+    sleep: (ms) => Bun.sleep(ms)
+  };
+});
 
 // apps/agent/src/sort/compare.ts
 function chain(...comparators) {
@@ -93987,6 +94173,7 @@ function compareQueueEntries(getAutoMerge) {
 }
 var MODE_RANK;
 var init_queue_order = __esm(() => {
+  init_linear();
   MODE_RANK = {
     resume: 0,
     "conflict-fix": 1,
@@ -94428,6 +94615,15 @@ class AgentCoordinator {
     } catch {}
     return true;
   }
+  async notifySteeringAppended(changeName, message) {
+    if (!this.deps.onSteeringAppended)
+      return;
+    try {
+      await this.deps.onSteeringAppended(changeName, message);
+    } catch (err) {
+      this.deps.onLog(`! onSteeringAppended failed for ${changeName}: ${err.message}`, "yellow");
+    }
+  }
   async notifyExited(issue2, changeName, code, mode) {
     const ok = code === 0;
     if (this.deps.syncTasks && ok) {
@@ -94537,6 +94733,7 @@ var emptyPrStatus = () => ({ mergeable: 0, conflicted: 0, ciFailed: 0 }), emptyP
   prStatus: emptyPrStatus()
 });
 var init_coordinator = __esm(() => {
+  init_linear();
   init_queue_order();
   init_src();
 });
@@ -94905,11 +95102,49 @@ ${issue2.description.trim()}` : ""
   ].filter(Boolean).join(`
 `);
 }
+async function diffFilesAgainstBase(runner, cwd2, base2) {
+  let raw = "";
+  try {
+    const r = await runner.run(["git", "diff", "--name-only", `origin/${base2}...HEAD`], cwd2);
+    raw = r.stdout;
+  } catch {
+    try {
+      const r = await runner.run(["git", "diff", "--name-only", `${base2}...HEAD`], cwd2);
+      raw = r.stdout;
+    } catch {
+      return [];
+    }
+  }
+  return raw.split(`
+`).map((s) => s.trim()).filter(Boolean);
+}
+async function classifyDiffAgainstMeta(runner, cwd2, base2, metaOnlyFiles) {
+  const files = await diffFilesAgainstBase(runner, cwd2, base2);
+  if (files.length === 0 || metaOnlyFiles.length === 0) {
+    return { files, onlyMeta: false };
+  }
+  const violations = findBoundaryViolations(files, metaOnlyFiles);
+  const metaSet = new Set(violations.map((v) => v.file));
+  const onlyMeta = files.every((f2) => metaSet.has(f2.replace(/\\/g, "/")));
+  return { files, onlyMeta };
+}
 async function createPullRequest(input, runner) {
   const base2 = input.base ?? "main";
   const log2 = await runner.run(["git", "log", "--oneline", `${base2}..HEAD`, "--no-merges"], input.cwd);
   if (log2.stdout.trim() === "")
     return null;
+  const metaOnlyFiles = input.metaOnlyFiles ?? [];
+  if (metaOnlyFiles.length > 0) {
+    const classification = await classifyDiffAgainstMeta(runner, input.cwd, base2, metaOnlyFiles);
+    if (classification.onlyMeta && classification.files.length > 0) {
+      return {
+        url: null,
+        created: false,
+        blocked: "only-meta",
+        blockedFiles: classification.files
+      };
+    }
+  }
   await runner.run(["git", "push", "-u", "origin", input.branch], input.cwd);
   const existing = await runner.run([
     "gh",
@@ -94934,6 +95169,7 @@ async function createPullRequest(input, runner) {
 `).pop() ?? "";
   return { url: url2, created: true };
 }
+var init_pr = () => {};
 
 // apps/agent/src/agent/post-task.ts
 import { join as join20 } from "path";
@@ -95046,7 +95282,13 @@ async function createPrWithRetry(ctx, issue2) {
   while (true) {
     try {
       ctx.emit("pr-create", "git push + gh pr create");
-      pr = await createPullRequest({ cwd: ctx.cwd, branch: ctx.branch, issue: issue2, base: base2 }, ctx.cmd);
+      pr = await createPullRequest({
+        cwd: ctx.cwd,
+        branch: ctx.branch,
+        issue: issue2,
+        base: base2,
+        metaOnlyFiles: ctx.cfg.metaOnlyFiles ?? []
+      }, ctx.cmd);
       return { pr, gaveUp: false };
     } catch (err) {
       const e = err;
@@ -95312,49 +95554,97 @@ ${indented}${suffix}`, "yellow");
     }
     return PR_FAILED_EXIT;
   }
-  const { pr, gaveUp: prGaveUp } = await createPrWithRetry(ctx, issue2);
-  if (prGaveUp)
-    return PR_FAILED_EXIT;
+  const maxOuterAttempts = cfg.maxCiFixAttempts;
+  let onlyMetaAttempts = 0;
+  let pr = null;
+  while (true) {
+    const attempt2 = await createPrWithRetry(ctx, issue2);
+    if (attempt2.gaveUp)
+      return PR_FAILED_EXIT;
+    if (attempt2.pr?.blocked === "only-meta") {
+      onlyMetaAttempts += 1;
+      const files = attempt2.pr.blockedFiles ?? [];
+      emit("pr-only-meta", `${files.length} meta file(s)`);
+      log2(`! ${changeName}: branch diff against ${base2} contains only meta files \u2014 implementation appears lost. Refusing to open PR.`, "red");
+      for (const f2 of files)
+        log2(`    ${f2}`, "red");
+      if (onlyMetaAttempts > maxOuterAttempts) {
+        log2(`! exceeded ${maxOuterAttempts} only-meta recovery attempts for ${changeName} \u2014 giving up`, "red");
+        return PR_FAILED_EXIT;
+      }
+      const fileList = files.length > 0 ? files.map((f2) => `- ${f2}`).join(`
+`) : "(empty diff)";
+      const retryCode = await runWorkerWithFixTask(ctx, "Reapply lost implementation files", [
+        `The diff against \`${base2}\` contains only meta files`,
+        `(openspec/tasks.md and similar). The substantive implementation`,
+        `is missing from the branch \u2014 likely deleted by an earlier commit`,
+        `or absorbed by a merge from origin/${base2}.`,
+        "",
+        `Files currently in the diff:`,
+        fileList,
+        "",
+        `Re-apply the actual implementation work the change is supposed`,
+        `to ship. Inspect git history (\`git log ${base2}..HEAD\`) to see`,
+        `what was created earlier and lost, then restore those files`,
+        `(or reproduce the work). Commit the restored files so the next`,
+        `iteration's diff against \`${base2}\` contains real code, not`,
+        `just meta files.`
+      ].join(`
+`));
+      if (retryCode !== 0) {
+        log2(`! worker re-run after only-meta block exited code ${retryCode} \u2014 giving up`, "red");
+        return PR_FAILED_EXIT;
+      }
+      continue;
+    }
+    pr = attempt2.pr;
+    break;
+  }
   if (!pr) {
     log2(`  no commits ahead of ${base2} \u2014 skipping PR`, "gray");
     return 0;
   }
-  log2(`  ${pr.created ? "opened" : "found existing"} PR: ${pr.url}`, "green");
-  registerPr?.(changeName, pr.url);
+  const prUrl = pr.url;
+  if (!prUrl) {
+    log2(`! PR creation returned a null URL for ${changeName} \u2014 giving up`, "red");
+    return PR_FAILED_EXIT;
+  }
+  log2(`  ${pr.created ? "opened" : "found existing"} PR: ${prUrl}`, "green");
+  registerPr?.(changeName, prUrl);
   let manualMergePending = false;
   if (wantAutoMerge) {
     const fallbackEnabled = cfg.manualMergeWhenAutoMergeDisabled !== false;
-    const repoAllowsAutoMerge = await detectRepoAutoMergeAllowed(pr.url, cmd, cwd2, log2);
+    const repoAllowsAutoMerge = await detectRepoAutoMergeAllowed(prUrl, cmd, cwd2, log2);
     if (repoAllowsAutoMerge === false && fallbackEnabled) {
-      log2(`  repo has auto-merge disabled \u2014 will poll ${pr.url} and merge via gh pr merge once checks pass`, "yellow");
+      log2(`  repo has auto-merge disabled \u2014 will poll ${prUrl} and merge via gh pr merge once checks pass`, "yellow");
       manualMergePending = true;
     } else {
       try {
-        await cmd.run(["gh", "pr", "merge", pr.url, "--auto", `--${cfg.autoMergeStrategy}`], cwd2);
-        log2(`  enabled auto-merge (${cfg.autoMergeStrategy}) on ${pr.url}`, "green");
+        await cmd.run(["gh", "pr", "merge", prUrl, "--auto", `--${cfg.autoMergeStrategy}`], cwd2);
+        log2(`  enabled auto-merge (${cfg.autoMergeStrategy}) on ${prUrl}`, "green");
         emit("auto-merge-enabled", cfg.autoMergeStrategy);
       } catch (err) {
         const e = err;
         const detail = e.stderr?.trim() || e.message;
-        log2(`! failed to enable auto-merge on ${pr.url}: ${detail}`, "yellow");
+        log2(`! failed to enable auto-merge on ${prUrl}: ${detail}`, "yellow");
         if (fallbackEnabled && /auto[- ]merge/i.test(detail)) {
-          log2(`  falling back to manual merge after CI passes for ${pr.url}`, "yellow");
+          log2(`  falling back to manual merge after CI passes for ${prUrl}`, "yellow");
           manualMergePending = true;
         }
       }
     }
   }
-  const ciResult = await fixConflictsAndCiLoop(ctx, pr.url, wantFixCi, checkPrConflict);
+  const ciResult = await fixConflictsAndCiLoop(ctx, prUrl, wantFixCi, checkPrConflict);
   if (ciResult !== 0)
     return ciResult;
   if (manualMergePending) {
     try {
-      await cmd.run(["gh", "pr", "merge", pr.url, `--${cfg.autoMergeStrategy}`], cwd2);
-      log2(`  manually merged (${cfg.autoMergeStrategy}) ${pr.url}`, "green");
+      await cmd.run(["gh", "pr", "merge", prUrl, `--${cfg.autoMergeStrategy}`], cwd2);
+      log2(`  manually merged (${cfg.autoMergeStrategy}) ${prUrl}`, "green");
       emit("auto-merge-enabled", `manual:${cfg.autoMergeStrategy}`);
     } catch (err) {
       const e = err;
-      log2(`! manual merge failed for ${pr.url}: ${e.stderr?.trim() || e.message}`, "yellow");
+      log2(`! manual merge failed for ${prUrl}: ${e.stderr?.trim() || e.message}`, "yellow");
     }
   }
   return 0;
@@ -95455,6 +95745,8 @@ async function runPostTask(input, deps) {
 var CI_FAILED_EXIT = 70, PR_FAILED_EXIT = 71, repoAutoMergeCache;
 var init_post_task = __esm(() => {
   init_tasks_md();
+  init_linear();
+  init_pr();
   init_ci();
   init_worktree();
   repoAutoMergeCache = new Map;
@@ -95721,64 +96013,235 @@ function renderTasksBlock(tasksMd, meta3) {
   return out.join(`
 `);
 }
-function applyTasksBlock(existingDescription, block) {
-  const existing = existingDescription ?? "";
-  const startIdx = existing.indexOf(RALPHY_TASKS_START);
-  const endIdx = startIdx >= 0 ? existing.indexOf(RALPHY_TASKS_END, startIdx + RALPHY_TASKS_START.length) : -1;
-  if (startIdx >= 0 && endIdx >= 0) {
-    const before2 = existing.slice(0, startIdx);
-    const after2 = existing.slice(endIdx + RALPHY_TASKS_END.length);
-    return `${before2}${block}${after2}`;
-  }
-  if (existing.length === 0)
-    return block;
-  const trimmed = existing.replace(/\s+$/, "");
-  return `${trimmed}
+var RALPHY_TASKS_START = "<!-- ralphy:tasks:start -->", RALPHY_TASKS_END = "<!-- ralphy:tasks:end -->", MAX_CODE_BLOCK_BYTES;
+var init_linear_sync = __esm(() => {
+  MAX_CODE_BLOCK_BYTES = 2 * 1024;
+});
 
-${block}`;
+// apps/agent/src/agent/linear-sync/comment-sync.ts
+import { dirname as dirname7, join as join21 } from "path";
+import { mkdir as mkdir6 } from "fs/promises";
+async function readStateJson(statePath) {
+  const file2 = Bun.file(statePath);
+  if (!await file2.exists())
+    return null;
+  try {
+    return await file2.json();
+  } catch {
+    return null;
+  }
+}
+async function writeStateJson(statePath, state) {
+  await mkdir6(dirname7(statePath), { recursive: true });
+  await Bun.write(statePath, JSON.stringify(state, null, 2) + `
+`);
+}
+function readComments(state) {
+  const raw = state?.linearComments ?? {};
+  return {
+    planCommentId: raw?.planCommentId ?? null,
+    tasksCommentId: raw?.tasksCommentId ?? null,
+    planPostedAt: raw?.planPostedAt ?? null
+  };
 }
-async function syncTasksToLinearDescription(deps) {
-  const file2 = Bun.file(deps.tasksPath);
+async function patchComments(statePath, patch) {
+  const existing = await readStateJson(statePath) ?? {};
+  const current = readComments(existing);
+  const next = { ...current, ...patch };
+  await writeStateJson(statePath, { ...existing, linearComments: next });
+}
+function isCommentNotFoundError(err) {
+  if (!err)
+    return false;
+  const candidates = [];
+  const e = err;
+  if (Array.isArray(e.messages))
+    candidates.push(...e.messages);
+  if (typeof e.message === "string")
+    candidates.push(e.message);
+  const text = candidates.join(" ").toLowerCase();
+  return text.includes("not found") || text.includes("could not find") || text.includes("entity not found");
+}
+async function readTasksMd(changeDir, log2) {
+  const file2 = Bun.file(join21(changeDir, "tasks.md"));
   if (!await file2.exists()) {
-    deps.log(`  sync-tasks: tasks.md missing at ${deps.tasksPath}, skipping`, "gray");
+    log2(`  comment-sync: tasks.md missing in ${changeDir}, skipping`, "gray");
     return null;
   }
-  let tasksMd;
   try {
-    tasksMd = await file2.text();
+    return await file2.text();
   } catch (err) {
-    deps.log(`! sync-tasks: read failed for ${deps.tasksPath}: ${err.message}`, "yellow");
+    log2(`! comment-sync: read tasks.md failed: ${err.message}`, "yellow");
     return null;
   }
-  const block = renderTasksBlock(tasksMd, {
-    changeName: deps.changeName,
-    iteration: deps.iteration
-  });
-  if (block.length > MAX_BLOCK_BYTES) {
-    deps.log(`! sync-tasks: rendered block exceeds ${MAX_BLOCK_BYTES} bytes (${block.length}), skipping update`, "yellow");
+}
+function renderTasksCommentBody(tasksMd, changeName, iteration) {
+  return renderTasksBlock(tasksMd, { changeName, iteration });
+}
+async function postOrUpdateTasksComment(deps) {
+  const tasksMd = await readTasksMd(deps.changeDir, deps.log);
+  if (!tasksMd)
+    return null;
+  const body = renderTasksCommentBody(tasksMd, deps.changeName, deps.iteration);
+  const state = await readStateJson(deps.statePath);
+  const comments = readComments(state);
+  if (comments.tasksCommentId) {
+    try {
+      await deps.mutations.updateIssueComment(deps.apiKey, comments.tasksCommentId, body);
+      deps.log(`  comment-sync: updated tasks comment for ${deps.changeName}`, "gray");
+      return comments.tasksCommentId;
+    } catch (err) {
+      if (!isCommentNotFoundError(err)) {
+        deps.log(`! comment-sync: updateIssueComment failed: ${err.message}`, "yellow");
+        return null;
+      }
+      deps.log(`  comment-sync: tasks comment ${comments.tasksCommentId} not found \u2014 recreating`, "gray");
+    }
+  }
+  let newId;
+  try {
+    newId = await deps.mutations.createIssueComment(deps.apiKey, deps.issueId, body);
+  } catch (err) {
+    deps.log(`! comment-sync: createIssueComment failed: ${err.message}`, "yellow");
     return null;
   }
-  const next = applyTasksBlock(deps.currentDescription, block);
-  if (next === (deps.currentDescription ?? ""))
+  await patchComments(deps.statePath, { tasksCommentId: newId });
+  deps.log(`  comment-sync: created tasks comment for ${deps.changeName}`, "gray");
+  return newId;
+}
+function planningComplete(tasksMd) {
+  const lines = tasksMd.split(/\r?\n/);
+  let inPlanning = false;
+  let total = 0;
+  let unchecked = 0;
+  for (const line of lines) {
+    const h = /^##\s+(.+?)\s*$/.exec(line);
+    if (h) {
+      inPlanning = h[1].trim().toLowerCase() === "planning";
+      continue;
+    }
+    if (!inPlanning)
+      continue;
+    const m = /^\s*-\s+\[( |x|X)\]/.exec(line);
+    if (!m)
+      continue;
+    total += 1;
+    if (m[1] === " ")
+      unchecked += 1;
+  }
+  return { allChecked: total > 0 && unchecked === 0, total };
+}
+async function readFirstParagraph(path) {
+  const file2 = Bun.file(path);
+  if (!await file2.exists())
     return null;
+  const text = await file2.text();
+  const blocks = text.split(/\r?\n\s*\r?\n/).map((b) => b.trim()).filter((b) => b.length > 0 && !/^#\s/.test(b));
+  return blocks[0] ?? null;
+}
+async function readSection(path, heading) {
+  const file2 = Bun.file(path);
+  if (!await file2.exists())
+    return null;
+  const text = await file2.text();
+  const headingRe = new RegExp(`(^|\\n)##\\s+${heading}\\s*\\n`);
+  const m = headingRe.exec(text);
+  if (!m)
+    return null;
+  const start = m.index + m[0].length;
+  const rest2 = text.slice(start);
+  const next = /\n##\s+/.exec(rest2);
+  const body = next ? rest2.slice(0, next.index) : rest2;
+  return body.trim() || null;
+}
+async function postPlanCommentOnce(deps) {
+  const state = await readStateJson(deps.statePath);
+  const comments = readComments(state);
+  if (comments.planCommentId)
+    return null;
+  const tasksMd = await readTasksMd(deps.changeDir, deps.log);
+  if (!tasksMd)
+    return null;
+  const check2 = planningComplete(tasksMd);
+  if (!check2.allChecked)
+    return null;
+  const proposalPath = join21(deps.changeDir, "proposal.md");
+  const why = await readSection(proposalPath, "Why");
+  const whatChanges = await readSection(proposalPath, "What Changes");
+  if (!why && !whatChanges) {
+    deps.log(`  comment-sync: proposal.md has no Why/What Changes, skipping plan comment`, "gray");
+    return null;
+  }
+  const designSummary = await readFirstParagraph(join21(deps.changeDir, "design.md"));
+  const parts = [`### ${PLAN_COMMENT_TITLE} \u2014 \`${deps.changeName}\``];
+  if (why) {
+    parts.push("", "**Why**", "", why);
+  }
+  if (whatChanges) {
+    parts.push("", "**What Changes**", "", whatChanges);
+  }
+  if (designSummary) {
+    parts.push("", "**Design**", "", designSummary);
+  }
+  const body = parts.join(`
+`);
+  let id;
   try {
-    await deps.updateIssueDescription(deps.apiKey, deps.issueId, next);
-    deps.log(`  sync-tasks: updated Linear description for ${deps.changeName}`, "gray");
-    return next;
+    id = await deps.mutations.createIssueComment(deps.apiKey, deps.issueId, body);
   } catch (err) {
-    deps.log(`! sync-tasks: updateIssueDescription failed: ${err.message}`, "yellow");
+    deps.log(`! comment-sync: plan comment create failed: ${err.message}`, "yellow");
     return null;
   }
+  await patchComments(deps.statePath, {
+    planCommentId: id,
+    planPostedAt: new Date().toISOString()
+  });
+  deps.log(`  comment-sync: posted plan comment for ${deps.changeName}`, "gray");
+  return id;
 }
-var RALPHY_TASKS_START = "<!-- ralphy:tasks:start -->", RALPHY_TASKS_END = "<!-- ralphy:tasks:end -->", MAX_BLOCK_BYTES, MAX_CODE_BLOCK_BYTES;
-var init_linear_sync = __esm(() => {
-  MAX_BLOCK_BYTES = 60 * 1024;
-  MAX_CODE_BLOCK_BYTES = 2 * 1024;
+async function postSteeringAndRefreshTasks(deps) {
+  const firstLine = deps.message.split(/\r?\n/, 1)[0].trim() || deps.message.trim();
+  const steeringBody = `### ${STEERING_COMMENT_TITLE}
+
+${deps.message.trim()}`;
+  try {
+    await deps.mutations.createIssueComment(deps.apiKey, deps.issueId, steeringBody);
+    deps.log(`  comment-sync: posted steering comment (${firstLine})`, "gray");
+  } catch (err) {
+    deps.log(`! comment-sync: steering comment create failed: ${err.message}`, "yellow");
+  }
+  const state = await readStateJson(deps.statePath);
+  const comments = readComments(state);
+  if (comments.tasksCommentId) {
+    try {
+      await deps.mutations.deleteIssueComment(deps.apiKey, comments.tasksCommentId);
+      deps.log(`  comment-sync: deleted old tasks comment`, "gray");
+    } catch (err) {
+      if (!isCommentNotFoundError(err)) {
+        deps.log(`! comment-sync: deleteIssueComment failed: ${err.message}`, "yellow");
+      }
+    }
+    await patchComments(deps.statePath, { tasksCommentId: null });
+  }
+  await postOrUpdateTasksComment({
+    apiKey: deps.apiKey,
+    issueId: deps.issueId,
+    statePath: deps.statePath,
+    changeDir: deps.changeDir,
+    changeName: deps.changeName,
+    log: deps.log,
+    mutations: deps.mutations,
+    iteration: deps.iteration
+  });
+}
+var PLAN_COMMENT_TITLE = "\uD83D\uDCCB Ralph plan", STEERING_COMMENT_TITLE = "\uD83E\uDDED Ralph steering";
+var init_comment_sync = __esm(() => {
+  init_linear_sync();
 });
 
 // apps/agent/src/agent/wire.ts
-import { join as join21 } from "path";
-import { mkdir as mkdir6 } from "fs/promises";
+import { join as join22 } from "path";
+import { mkdir as mkdir7 } from "fs/promises";
 async function pickOpenPrUrlFromAttachments(urls, issueIdent, cmd, cwd2, onLog) {
   const candidates = urls.filter((url2) => GITHUB_PR_URL_RE.test(url2));
   let sawNonOpenPr = false;
@@ -95942,7 +96405,7 @@ function buildAgentCoordinator(input) {
     onWorkerOutput,
     onWorkerCmd
   } = input;
-  const logsDir = join21(projectRoot, ".ralph", "logs");
+  const logsDir = join22(projectRoot, ".ralph", "logs");
   const concurrency = args.concurrency || cfg.concurrency;
   const pollInterval = args.pollInterval || cfg.pollIntervalSeconds;
   const indicators = mergeIndicators(cfg.linear.indicators, args.indicators);
@@ -96065,6 +96528,7 @@ function buildAgentCoordinator(input) {
   const prUnavailable = new Map;
   const PR_UNAVAILABLE_TTL_MS = 10 * 60 * 1000;
   const stalePingedAt = new Map;
+  const lastHandledReviewActivity = new Map;
   const useWorktree = args.worktree || cfg.useWorktree;
   const scriptRunner = input.runners?.runScript ?? (async (cmd, cwd2) => {
     const proc = Bun.spawn({
@@ -96154,8 +96618,8 @@ function buildAgentCoordinator(input) {
     } else {
       changeName = changeNameForIssue(issue2);
       const wtLayout = projectLayout(workerCwd);
-      await mkdir6(wtLayout.changeDir(changeName), { recursive: true });
-      await mkdir6(wtLayout.taskStateDir(changeName), { recursive: true });
+      await mkdir7(wtLayout.changeDir(changeName), { recursive: true });
+      await mkdir7(wtLayout.taskStateDir(changeName), { recursive: true });
     }
     cwdByChange.set(changeName, workerCwd);
     statesDirByChange.set(changeName, scaffoldStatesDir);
@@ -96164,7 +96628,7 @@ function buildAgentCoordinator(input) {
       branchByChange.set(changeName, branch);
     if (mode === "review") {
       const wtLayout = projectLayout(workerCwd);
-      const tasksFile = join21(wtLayout.changeDir(changeName), AGENT_TASKS_FILENAME);
+      const tasksFile = join22(wtLayout.changeDir(changeName), AGENT_TASKS_FILENAME);
       let body;
       let heading;
       if (trigger) {
@@ -96189,7 +96653,7 @@ function buildAgentCoordinator(input) {
       await reactivateState2(wtLayout.stateFile(changeName), changeName);
     } else if (mode === "conflict-fix") {
       const wtLayout = projectLayout(workerCwd);
-      const tasksFile = join21(wtLayout.changeDir(changeName), AGENT_TASKS_FILENAME);
+      const tasksFile = join22(wtLayout.changeDir(changeName), AGENT_TASKS_FILENAME);
       const prUrl = prByChange.get(changeName);
       const body = [
         `The PR for this change has merge conflicts with \`${cfg.prBaseBranch}\`.`,
@@ -96269,7 +96733,7 @@ PR: ${prUrl}` : ""
     return c;
   }
   function defaultSpawn(changeName, cmd, cwd2, note) {
-    const logFilePath = join21(logsDir, `${changeName}.log`);
+    const logFilePath = join22(logsDir, `${changeName}.log`);
     const ANSI_RE2 = /\x1b(?:\[[0-9;]*[A-Za-z]|\][^\x07\x1b]*(?:\x07|\x1b\\)|.)/g;
     const BOX_ONLY_RE = /^[\s\u2500\u2502\u256D\u256E\u2570\u256F\u254C\u2504\u2501\u2503]+$/;
     const STATUS_BAR_LINE_RE = /^[\u280B\u2819\u2839\u2838\u283C\u2834\u2826\u2827\u2807\u280F\u2713\u2717]\s+iter\s+\d+/;
@@ -96328,7 +96792,7 @@ PR: ${prUrl}` : ""
   function spawnWorker(changeName) {
     const cwd2 = cwdByChange.get(changeName) ?? projectRoot;
     const injected = input.runners?.spawnWorker;
-    const missionTasksPath = join21(projectLayout(cwd2).changeDir(changeName), MISSION_TASKS_FILENAME);
+    const missionTasksPath = join22(projectLayout(cwd2).changeDir(changeName), MISSION_TASKS_FILENAME);
     const prevTasksPromise = (async () => {
       const f2 = Bun.file(missionTasksPath);
       return await f2.exists() ? await f2.text() : "";
@@ -96336,7 +96800,7 @@ PR: ${prUrl}` : ""
     let logFilePath;
     let handle;
     if (injected) {
-      logFilePath = join21(logsDir, `${changeName}.log`);
+      logFilePath = join22(logsDir, `${changeName}.log`);
       handle = injected(buildTaskCmdFor(changeName), cwd2);
     } else {
       const r = defaultSpawn(changeName, buildTaskCmdFor(changeName), cwd2, `spawn at ${new Date().toISOString()}`);
@@ -96396,6 +96860,7 @@ PR: ${prUrl}` : ""
           ignoreCiChecks: cfg.ignoreCiChecks,
           stackPrsOnDependencies: args.stackPrs || cfg.stackPrsOnDependencies,
           neverTouch: cfg.boundaries.never_touch,
+          metaOnlyFiles: cfg.boundaries.meta_only_files,
           manualMergeWhenAutoMergeDisabled: cfg.manualMergeWhenAutoMergeDisabled
         },
         respawnWorker: respawn
@@ -96608,17 +97073,32 @@ PR: ${prUrl}` : ""
     try {
       candidates = await fetchMentionScanIssues(apiKey, { team, assignee });
     } catch (err) {
-      onLog(`! mention scan: fetchMentionScanIssues failed: ${err.message}`, "yellow");
+      if (isRateLimitedError(err)) {
+        onLog(`! mention scan: rate limited, deferring rest of scan to next poll`, "yellow");
+        return [];
+      }
+      onLog(`! mention scan: fetchMentionScanIssues failed: ${formatLinearError(err)}`, "yellow");
       return [];
     }
     const out = [];
     const queued = new Set;
+    let rateLimitedLogged = false;
+    const logRateLimited = () => {
+      if (rateLimitedLogged)
+        return;
+      rateLimitedLogged = true;
+      onLog(`! mention scan: rate limited, deferring rest of scan to next poll`, "yellow");
+    };
     for (const issue2 of candidates) {
       let comments = [];
       try {
         comments = await fetchIssueComments(apiKey, issue2.id);
       } catch (err) {
-        onLog(`! mention scan: Linear comments failed for ${issue2.identifier}: ${err.message}`, "yellow");
+        if (isRateLimitedError(err)) {
+          logRateLimited();
+          break;
+        }
+        onLog(`! mention scan: Linear comments failed for ${issue2.identifier}: ${formatLinearError(err)}`, "yellow");
         continue;
       }
       const lastRalphPickup = findLastRalphPickupISO(comments);
@@ -96643,11 +97123,18 @@ PR: ${prUrl}` : ""
           try {
             await addReactionToComment(apiKey, c.id, "\uD83D\uDC40");
           } catch (err) {
-            onLog(`! mention scan: Linear reaction failed for ${issue2.identifier}: ${err.message}`, "yellow");
+            if (isRateLimitedError(err)) {
+              logRateLimited();
+              queued.add(issue2.id);
+              break;
+            }
+            onLog(`! mention scan: Linear reaction failed for ${issue2.identifier}: ${formatLinearError(err)}`, "yellow");
           }
           queued.add(issue2.id);
           break;
         }
+        if (rateLimitedLogged)
+          break;
         if (queued.has(issue2.id))
           continue;
       }
@@ -96677,7 +97164,7 @@ PR: ${prUrl}` : ""
             try {
               await addGithubReactionToComment({ owner, repo, kind: "issue" }, c.id, "\uD83D\uDC40");
             } catch (err) {
-              onLog(`! mention scan: GitHub reaction failed for ${prUrl}: ${err.message}`, "yellow");
+              onLog(`! mention scan: GitHub reaction failed for ${prUrl}: ${formatLinearError(err)}`, "yellow");
             }
           }
           queued.add(issue2.id);
@@ -96707,7 +97194,9 @@ PR: ${prUrl}` : ""
       const last2 = t.comments[t.comments.length - 1].createdAt;
       return last2 > acc ? last2 : acc;
     }, "");
-    if (!lastRalphPickup || newestReviewerActivity > lastRalphPickup) {
+    const lastHandled = lastHandledReviewActivity.get(prUrl) ?? null;
+    const effectiveLastHandled = lastRalphPickup && lastHandled ? lastRalphPickup > lastHandled ? lastRalphPickup : lastHandled : lastRalphPickup ?? lastHandled;
+    if (!effectiveLastHandled || newestReviewerActivity > effectiveLastHandled) {
       const body = unresolved.map((t) => {
         const head3 = t.path ? `_${t.path}${t.line ? `:${t.line}` : ""}_` : "_(general)_";
         const lines = t.comments.map((c) => `> **${c.author ?? "reviewer"}** (${c.createdAt})
@@ -96721,6 +97210,7 @@ PR: ${prUrl}` : ""
 ---
 
 `);
+      lastHandledReviewActivity.set(prUrl, newestReviewerActivity);
       return {
         source: "github-review",
         body,
@@ -96868,10 +97358,16 @@ PR: ${prUrl}` : ""
       const parsed = JSON.parse(res.stdout || "[]");
       return parsed;
     } catch (err) {
-      onLog(`! mention scan: gh comments failed for ${prUrl}: ${err.message}`, "yellow");
+      onLog(`! mention scan: gh comments failed for ${prUrl}: ${formatLinearError(err)}`, "yellow");
       return [];
     }
   }
+  const commentSyncEnabled = Boolean(cfg.linear.syncTasksToComment && apiKey);
+  const commentMutations = {
+    createIssueComment,
+    updateIssueComment,
+    deleteIssueComment
+  };
   const coord = new AgentCoordinator({
     fetchTodo: () => fetchByGet(indicators.getTodo, excludeFromTodo),
     fetchInProgress: () => fetchByGet(indicators.getInProgress, []),
@@ -96900,26 +97396,62 @@ PR: ${prUrl}` : ""
       const json2 = await file2.json();
       return json2.iteration ?? 0;
     },
-    ...cfg.linear.syncTasksToDescription && apiKey ? {
+    ...commentSyncEnabled ? {
       syncTasks: async (worker, iteration) => {
         const root = cwdByChange.get(worker.changeName) ?? projectRoot;
-        const tasksPath = join21(projectLayout(root).changeDir(worker.changeName), "tasks.md");
-        const cachedIssue = issueByChange.get(worker.changeName) ?? worker.issue;
-        const next = await syncTasksToLinearDescription({
+        const layout = projectLayout(root);
+        const changeDir = layout.changeDir(worker.changeName);
+        const statePath = layout.stateFile(worker.changeName);
+        await postPlanCommentOnce({
           apiKey,
           issueId: worker.issueId,
-          currentDescription: cachedIssue.description,
-          tasksPath,
+          statePath,
+          changeDir,
+          changeName: worker.changeName,
+          log: onLog,
+          mutations: commentMutations
+        });
+        await postOrUpdateTasksComment({
+          apiKey,
+          issueId: worker.issueId,
+          statePath,
+          changeDir,
           changeName: worker.changeName,
           iteration,
           log: onLog,
-          updateIssueDescription
+          mutations: commentMutations
         });
-        if (next !== null) {
-          const updated = { ...cachedIssue, description: next };
-          issueByChange.set(worker.changeName, updated);
-          worker.issue = updated;
+      },
+      onSteeringAppended: async (changeName, message) => {
+        const root = cwdByChange.get(changeName) ?? projectRoot;
+        const layout = projectLayout(root);
+        const changeDir = layout.changeDir(changeName);
+        const statePath = layout.stateFile(changeName);
+        const issue2 = issueByChange.get(changeName) ?? null;
+        const issueId = issue2?.id ?? null;
+        if (!issueId) {
+          onLog(`  comment-sync: no Linear issue cached for ${changeName}; skipping steering refresh`, "gray");
+          return;
         }
+        let iteration = 0;
+        try {
+          const f2 = Bun.file(statePath);
+          if (await f2.exists()) {
+            const json2 = await f2.json();
+            iteration = json2.iteration ?? 0;
+          }
+        } catch {}
+        await postSteeringAndRefreshTasks({
+          apiKey,
+          issueId,
+          statePath,
+          changeDir,
+          changeName,
+          iteration,
+          message,
+          log: onLog,
+          mutations: commentMutations
+        });
       }
     } : {}
   }, {
@@ -96988,7 +97520,7 @@ PR: ${prUrl}` : ""
     concurrency,
     pollInterval,
     getWorkerCwd: (changeName) => cwdByChange.get(changeName),
-    syncTasksEnabled: Boolean(cfg.linear.syncTasksToDescription && apiKey),
+    syncTasksEnabled: commentSyncEnabled,
     runBaselineGate: runBaselineGateOnce
   };
 }
@@ -97017,6 +97549,7 @@ var init_wire = __esm(() => {
   init_tasks_md();
   init_workflow();
   init_types2();
+  init_linear();
   init_coordinator();
   init_scaffold();
   init_worktree();
@@ -97024,7 +97557,7 @@ var init_wire = __esm(() => {
   init_post_task();
   init_gate();
   init_workflow();
-  init_linear_sync();
+  init_comment_sync();
   GITHUB_PR_URL_RE = /^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+/;
   bunGitRunner = {
     run: async (args, cwd2) => {
@@ -97143,21 +97676,26 @@ function readSize2() {
     rows: process.stdout.rows ?? 24
   };
 }
+function clearScreenAndScrollback2() {
+  if (process.stdout.isTTY)
+    process.stdout.write("\x1B[2J\x1B[3J\x1B[H");
+}
 function useTerminalSize2() {
-  const [size2, setSize] = import_react59.useState(() => ({
-    ...readSize2(),
-    resizeKey: 0
-  }));
+  const initial2 = import_react59.useRef({ ...readSize2(), resizeKey: 0 });
+  const [size2, setSize] = import_react59.useState(initial2.current);
+  const sizeRef = import_react59.useRef(initial2.current);
   import_react59.useEffect(() => {
     if (!process.stdout.isTTY)
       return;
     const onResize = () => {
       const { columns, rows } = readSize2();
-      setSize((prev) => {
-        if (prev.columns === columns && prev.rows === rows)
-          return prev;
-        return { columns, rows, resizeKey: prev.resizeKey + 1 };
-      });
+      const prev = sizeRef.current;
+      if (prev.columns === columns && prev.rows === rows)
+        return;
+      clearScreenAndScrollback2();
+      const next = { columns, rows, resizeKey: prev.resizeKey + 1 };
+      sizeRef.current = next;
+      setSize(next);
     };
     process.stdout.on("resize", onResize);
     return () => {
@@ -97347,7 +97885,7 @@ var init_SteeringField = __esm(async () => {
 });
 
 // apps/agent/src/components/AgentMode.tsx
-import { join as join22 } from "path";
+import { join as join23 } from "path";
 async function appendSteeringImpl(changeDir, message) {
   await runWithContext(createDefaultContext(), async () => {
     appendSteeringMessage(changeDir, message);
@@ -97598,19 +98136,13 @@ function AgentMode({
   loadConfig = loadRalphyConfig
 }) {
   const { exit } = use_app_default();
-  const { stdout } = use_stdout_default();
   const { isRawModeSupported } = use_stdin_default();
   const { columns, rows, resizeKey } = useTerminalSize2();
-  import_react61.useEffect(() => {
-    if (resizeKey === 0)
-      return;
-    stdout.write("\x1B[2J\x1B[3J\x1B[H");
-  }, [resizeKey, stdout]);
   const [logs, setLogs] = import_react61.useState([]);
   const [, setTick] = import_react61.useState(0);
   const [clock, setClock] = import_react61.useState(0);
   const [focusedIdx, setFocusedIdx] = import_react61.useState(0);
-  const [showPendingTasks, setShowPendingTasks] = import_react61.useState(true);
+  const [showPendingTasks, setShowPendingTasks] = import_react61.useState(false);
   const [showAllSubtasks, setShowAllSubtasks] = import_react61.useState(false);
   const coordRef = import_react61.useRef(null);
   const workerMetaRef = import_react61.useRef(new Map);
@@ -97808,7 +98340,7 @@ function AgentMode({
       (async () => {
         for (const [changeName, meta3] of workerMetaRef.current) {
           try {
-            const file2 = Bun.file(join22(meta3.statesDir, changeName, ".ralph-state.json"));
+            const file2 = Bun.file(join23(meta3.statesDir, changeName, ".ralph-state.json"));
             if (await file2.exists()) {
               const json2 = await file2.json();
               meta3.iter = json2.iteration ?? meta3.iter;
@@ -97818,9 +98350,9 @@ function AgentMode({
           }
           if (meta3.changeDir) {
             try {
-              const tasksFile = Bun.file(join22(meta3.changeDir, "tasks.md"));
-              const proposalFile = Bun.file(join22(meta3.changeDir, "proposal.md"));
-              const designFile = Bun.file(join22(meta3.changeDir, "design.md"));
+              const tasksFile = Bun.file(join23(meta3.changeDir, "tasks.md"));
+              const proposalFile = Bun.file(join23(meta3.changeDir, "proposal.md"));
+              const designFile = Bun.file(join23(meta3.changeDir, "design.md"));
               const [tasksText, proposalText, designText] = await Promise.all([
                 tasksFile.exists().then((ok) => ok ? tasksFile.text() : null),
                 proposalFile.exists().then((ok) => ok ? proposalFile.text() : null),
@@ -98651,11 +99183,14 @@ function AgentMode({
                     },
                     onSubmit: async (message) => {
                       try {
-                        await appendSteering(join22(tasksDir, w.changeName), message);
+                        await appendSteering(join23(tasksDir, w.changeName), message);
                       } catch (err) {
                         appendLog(`! steering append failed for ${w.changeName}: ${err.message}`, "red");
                         throw err;
                       }
+                      try {
+                        await coordRef.current?.notifySteeringAppended?.(w.changeName, message);
+                      } catch {}
                       const restarted = await coordRef.current?.restartWorker(w.changeName);
                       if (restarted) {
                         appendLog(`  ${w.changeName}: steering applied, restarting worker`, "cyan");
@@ -98855,7 +99390,7 @@ var exports_list = {};
 __export(exports_list, {
   runList: () => runList
 });
-import { join as join23 } from "path";
+import { join as join24 } from "path";
 function countTaskItems(content) {
   const checked = (content.match(/^- \[x\]/gm) ?? []).length;
   const unchecked = (content.match(/^- \[ \]/gm) ?? []).length;
@@ -98868,13 +99403,13 @@ function buildLocalRows(statesDir, projectRoot) {
   const sources = [{ dir: statesDir, label: "main" }];
   const worktreesRoot = worktreesDir2(projectRoot);
   for (const wt of storage.list(worktreesRoot)) {
-    sources.push({ dir: join23(worktreesRoot, wt, ".ralph", "tasks"), label: `wt:${wt}` });
+    sources.push({ dir: join24(worktreesRoot, wt, ".ralph", "tasks"), label: `wt:${wt}` });
   }
   for (const { dir, label } of sources) {
     for (const entry of storage.list(dir)) {
       if (seen.has(entry))
         continue;
-      const raw = storage.read(join23(dir, entry, ".ralph-state.json"));
+      const raw = storage.read(join24(dir, entry, ".ralph-state.json"));
       if (raw === null)
         continue;
       let state;
@@ -98889,7 +99424,7 @@ function buildLocalRows(statesDir, projectRoot) {
       const firstLine = promptRaw.split(`
 `).find((l) => l.trim() !== "") ?? "";
       let progress = "\u2014";
-      const tasksContent = storage.read(join23(dir, entry, "tasks.md"));
+      const tasksContent = storage.read(join24(dir, entry, "tasks.md"));
       if (tasksContent !== null) {
         const { checked, unchecked } = countTaskItems(tasksContent);
         const total = checked + unchecked;
@@ -99283,6 +99818,7 @@ var init_list = __esm(() => {
   init_types2();
   init_worktree();
   init_config();
+  init_linear();
   init_list_sort();
   localCmdRunner = {
     run: async (cmd, cwd2) => {
@@ -99305,8 +99841,8 @@ var exports_json_runner = {};
 __export(exports_json_runner, {
   runAgentJson: () => runAgentJson
 });
-import { join as join24 } from "path";
-import { mkdir as mkdir7 } from "fs/promises";
+import { join as join25 } from "path";
+import { mkdir as mkdir8 } from "fs/promises";
 import { homedir as homedir5 } from "os";
 function cleanOutputLine2(raw) {
   const clean = raw.replace(ANSI_STRIP_RE2, "").trim();
@@ -99330,7 +99866,7 @@ async function runAgentJson({
   statesDir,
   tasksDir
 }) {
-  await mkdir7(join24(homedir5(), ".ralph"), { recursive: true }).catch(() => {
+  await mkdir8(join25(homedir5(), ".ralph"), { recursive: true }).catch(() => {
     return;
   });
   const cfgPath = await ensureRalphyConfig(projectRoot);
@@ -99484,8 +100020,8 @@ var exports_src2 = {};
 __export(exports_src2, {
   main: () => main2
 });
-import { mkdir as mkdir8 } from "fs/promises";
-import { join as join25 } from "path";
+import { mkdir as mkdir9 } from "fs/promises";
+import { join as join26 } from "path";
 async function main2(argv) {
   if (argv.includes("--help") || argv.includes("-h")) {
     printHelp2();
@@ -99519,9 +100055,9 @@ async function main2(argv) {
     });
     return typeof process.exitCode === "number" ? process.exitCode : 0;
   }
-  await mkdir8(statesDir, { recursive: true });
-  await mkdir8(tasksDir, { recursive: true });
-  await mkdir8(join25(projectRoot, ".ralph"), { recursive: true });
+  await mkdir9(statesDir, { recursive: true });
+  await mkdir9(tasksDir, { recursive: true });
+  await mkdir9(join26(projectRoot, ".ralph"), { recursive: true });
   if (args.jsonOutput) {
     const { runAgentJson: runAgentJson2 } = await Promise.resolve().then(() => (init_json_runner(), exports_json_runner));
     await runAgentJson2({ args, projectRoot, statesDir, tasksDir });