@@ -9,6 +9,8 @@ For features with background jobs, polling, retries, cancellation, or shutdown:
 - Define the lifecycle states and ownership before implementation: pending, running, completed, failed, cancelled, stale, and closing.
 - Treat persisted state, in-memory jobs, subprocesses, HTTP requests, and rendered UI as separate state holders. Define how each transitions and settles.
 - Never apply a background response without proving it is still current. Use a generation, attempt ID, version, or guarded merge so older polling responses cannot overwrite newer actions.
+- When the local state has more than one version counter (for example a task's state version and its plan's review version), an in-flight action owns all of them, and applying its response requires every one to be unchanged. One counter does not cover writes that advance only another.
+- A current response may still move a record only along a transition allowed from the state the action was guarded for. Derive the new status from that state as well as the response; a response alone must never move a record out of a state that waits for a person.
 - Do not release a concurrency slot when cancellation is requested. Keep the job tracked until its underlying invocation or subprocess has terminated.
 - Do not let a retry replace a locally active job, even when its persisted lease has expired or wall-clock time changes.
 - Validate retry context against the current snapshot, plan revision, assignment, and referenced code. If any context is stale, disable retry and require a new request.
@@ -64,13 +66,21 @@ Every reproduced race requires a failing-before and passing-after regression. As
 
 - A bounded safety scan must fail closed when its limit is exceeded. Never truncate evidence and report the result as clear.
 - Align subprocess output limits with every payload the schema accepts, or tighten the upstream page and field bounds; valid bounded input must not fail only because the transport budget is smaller.
+- Pass text whose size follows user or agent input to a subprocess on stdin, never as an argument: the OS limits one argument's size and cannot pass a NUL, so valid bounded input can fail to spawn.
 - Exclude the subject of a duplicate or supersession check by stable identity only. A shared branch name or other mutable attribute does not prove two records are the same subject.
+- Exclude the subject's own records only in the states the exclusion is for. A check that skips its own open PR must still count its own merged PR, or its own close of the issue, as done.
 - Preserve repository identity with pull request numbers in cross-reference scans. Never resolve or exclude a repository-qualified reference by number alone.
+- When a relation can be added and removed (a manually linked PR, a label, an assignment), replay its add and remove events in order and count only its latest state. An add event alone does not prove the relation still holds.
 - After the final asynchronous external validation, re-read the local generation immediately before an irreversible action. A generation check performed before that await is insufficient.
+- Check an operation's source-state preconditions before any shortcut or early return that writes state or reports success, not only on the main path.
+- Honour a cancellation signal that is already aborted before the first durable write, not only after awaits: a path with no await otherwise writes after the caller cancelled.
 - Batch and briefly cache read-only status probes, and give the combined operation an overall deadline below the serving request timeout.
+- Count the subprocess shutdown grace periods (SIGTERM-to-SIGKILL wait, pipe drain) inside that overall deadline: the operation ends when its processes have settled, not when the abort fires.
+- After an external state change (ready, draft, close), read the record back and require the new state before recording success; a command that exits 0 does not prove the change applied.
 - Budget a multi-stage validation across all sequential stages; giving each stage the full request allowance does not create an overall deadline.
 - Preserve the distinction between an explicit unbound identity and missing or malformed authorization metadata. Missing or malformed identities must fail closed.
 - Validate every field used to classify an external record as clear, including enum values and required nullable fields. Partial records and malformed policy objects must fail closed.
+- Select every member the API documents for a union or enum you classify (for example every GraphQL `Closer` type). Fail closed only on types outside that list; a missing known member turns every result into a false unknown.
 - Validate coupled lifecycle fields as allowed combinations. A terminal-looking conclusion must not override an active or unknown status.
 - Treat a successful external command as the transition it actually performed. If it can enqueue or schedule work, model and verify that lifecycle before reporting the final action as complete.
 - For safety-critical API responses, require and validate every requested field before any early return, including terminal-success paths. Treat an omitted field differently from an explicit `null` allowed by the API contract.
@@ -86,21 +96,29 @@ Every reproduced race requires a failing-before and passing-after regression. As
 - When a durable external-action attempt is bound to an older snapshot, require approvals or evidence recorded against the replacement generation before another action, whether or not the prior outcome explicitly requested fresh review. A mismatch with the old context is not itself fresh review.
 - If the external lifecycle mechanism or mode changes between validation passes, abort before the irreversible command. Create durable lifecycle ownership from the final stable mode, never from an earlier observation.
 - When an irreversible command has an ambiguous timeout, cancellation, transport, or unknown outcome, retain durable in-flight ownership and reconcile external state before enabling retry. Only a confirmed refusal may become retryable failure.
+- Record in-flight ownership before the first external write of an operation, not before a later step: when a push moves an open PR's head, the refresh it belongs to is already in flight.
+- Order an operation's external writes so that any step the remote can definitely refuse comes before the writes that cannot be taken back. A refusal after a push or a description change leaves a half-updated record.
 - Correlate retry observations to the current attempt with an immutable external identity or event boundary, and fail closed when multiple post-boundary action sequences appear. Matching only the resource or commit identity can replay another attempt's terminal event.
+- When recovery looks for the result of an earlier attempt, recognise the identities of all earlier attempts, abandoned ones included. A result that appears after its attempt was abandoned must be adopted, not treated as foreign, or recovery can never settle.
+- Read an identity marker only from its reserved position (for example the first line of a description). Text around it may be agent-controlled, so a marker-shaped string elsewhere must never identify or disqualify a record.
+- When the external record is observed, correct the local copy of any field the operation owns (such as a draft flag) from it. A change that landed but whose confirmation was lost is otherwise never repaired, because the next run sees nothing left to change.
 - Make an idempotency key required at the API boundary for every replayable action, and look up its saved outcome before any other guard, including in-flight, validation and coordinator shutdown guards. The one exception is the server's HTTP 503 during shutdown, which applies nothing; the client must keep the key and resend it. Save every definite outcome under the key (refusals before admission too), keep the saved response current with the durable outcome it reports, and replay failures as failures with complete result fields. Only a passing, nothing-applied outcome (shutdown, abort, deadline, storage error) stays resendable.
 - When a refusal must also change durable state (for example, handing an expired task to a person), commit that change outside the refused transaction, together with the saved refusal. Never write it inside the transaction the refusal rolls back.
 
 ## Owned host and Docker resources
 
 - Treat the cleanup handle of an external resource (container, volume, network, temporary directory) as owned state. If removal fails, keep the handle, record it durably before its in-memory owner can be dropped (shutdown, crash, abandon, restart), and fail closed until removal is confirmed. Never delete the durable evidence before the final release report has been saved.
 - Give every subprocess an explicit allowlisted environment. Pass credentials only to the component that needs them, through a separate channel. Name-based scrubbing of an inherited environment is not isolation. Run Git with the repository's hardened invocation: no user or system config, no hooks, no lazy fetch, no network protocols.
+- Build that allowlist from each tool's documented credential and configuration channels on every supported platform (for example, the D-Bus session bus that a Linux keyring uses), and test that each is passed.
 - Treat paths read from a durable record or discovered on disk as untrusted. Before deleting, opening or probing one, validate its exact location and name, not only its basename, and never follow a link to it. Keep files that other local users must not plant or swap, such as lock files, in a directory only the current user can write. Write durable records through a unique temporary file opened exclusively, and delete it if the write fails.
 - Exclude other processes with an OS-level lock held for the owner's lifetime, keyed by the resource's stable identity rather than a path spelling. A PID liveness check never authorizes taking over a lock. Run shared one-time startup work single-flight under that lock, and keep the lock until the work has finished.
 
 ## Agent-controlled content
 
 - When a subprocess reports a problem only as a warning and carries on, decide pass or fail by what each message means for the result, not by whether anything was printed: fail on messages that mean it did less than it should (for example could not read a path), and let through messages about harmless input the agent controls. Test both a benign case and a failing case, and filter the output as it arrives so that no volume of benign messages can push a failure out of a bounded buffer.
 - Quote or escape agent-controlled text (file names, paths, branch names) wherever it lands in output that people or tools parse, such as diffs, notices, logs or reports, so it cannot forge that output's structure.
+- Neutralise issue references (`#N`, `GH-N`, `owner/repo#N`, issue URLs) in any text codeboost writes that can become a commit message, such as a PR title or description, and neutralise @-mentions in any of that text that is not fenced (a title). Code fences do not protect commit messages, and GitHub closes issues from closing keywords in default-branch commits.
+- Never spread a collection whose size follows unbounded input into function arguments (`Math.max(...runs)`); engines limit the argument count, so use a loop.
 - A hardened Git invocation must also keep Git out of nested repositories and populated submodules, whose own config and hooks are the agent's: pass `--ignore-submodules` on the command line (the config default does not bind plumbing or override `.gitmodules`), and never run Git with a nested repository as its working directory.
 - Decide a filesystem fact (whether a name exists, where a link resolves, what a path's entries are) on the file system that will serve it, not on a copy. A host that folds case or Unicode normalization, or decodes names as text, answers differently from the container's; check links and names inside the container, as its kernel resolves them, by raw bytes.
 - Never infer that agent-written content is unchanged from timestamps, sizes or an index's stat cache: not every write moves them (tmpfs, for one). Compare the content itself.
 
@@ -0,0 +1,85 @@
+import type { Plan } from './plan.ts';
+import { cutText as cut } from './text.ts';
+
+/** GitHub refuses a PR description longer than 65,536 characters; stay below it with room for the frame. */
+export const MAX_BODY = 60_000;
+export const MAX_TITLE = 200;
+const MAX_PROBLEMS = 20, MAX_PROBLEM = 2000;
+
+/**
+ * Plan text and open problems go inside fenced code blocks. GitHub does not act on closing keywords ("Fixes #12") or
+ * @-mentions inside code, so text from the plan or from agent output cannot close other issues or notify people.
+ * The fence is longer than any backtick run in the text, so the text cannot end the block. Control characters other
+ * than newline and tab (a NUL from agent output, say), and lone UTF-16 surrogates, become U+FFFD: GitHub may refuse
+ * them, and a refusal would repeat on every publish.
+ */
+export function fenced(text: string): string {
+  // A loop, not Math.max(...runs): plan text is not length-bounded, and spreading every run can overflow the stack.
+  let longest = 0;
+  for (const match of text.matchAll(/`+/g)) longest = Math.max(longest, match[0].length);
+  const fence = '`'.repeat(Math.max(3, longest + 1));
+  return `${fence}text\n${text.toWellFormed().replace(/\r\n?/g, '\n').replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, '\ufffd')}\n${fence}`;
+}
+
+/**
+ * GitHub also reads closing keywords ("Fixes #7") in commit messages on the default branch, fenced or not, and a squash
+ * or merge commit can carry the PR title and description. So every issue reference in plan text and problems is
+ * neutralised: `#7` becomes `＃7`, `GH-7` becomes `GH‑7` (non-breaking hyphen), and `/issues/7` or `/pull/7` in a URL gets a
+ * division slash. The text stays readable, and no merge method can close another issue through it.
+ */
+export function neutralizeReferences(text: string): string {
+  return text.replace(/#(?=\d)/g, '＃').replace(/\b(GH)-(?=\d)/gi, '$1‑').replace(/\/(issues|pull)\/(?=\d)/gi, '/$1∕');
+}
+
+function planText(plan: Plan, full: boolean): string {
+  return plan.items.map(item => {
+    const lines = [`${item.id}: ${item.title}`];
+    if (full) {
+      lines.push(`  Intent: ${item.intent}`);
+      for (const file of item.files) lines.push(`  ${file.kind} ${file.renamed_from ? `${file.renamed_from} -> ` : ''}${file.path}: ${file.change}`);
+      for (const check of item.acceptance) lines.push(`  ${check.type}: ${check.text}`);
+      if (item.depends_on.length) lines.push(`  After: ${item.depends_on.join(', ')}`);
+    }
+    return lines.join('\n');
+  }).join('\n\n');
+}
+const planTextSafe = (plan: Plan, full: boolean) => neutralizeReferences(planText(plan, full));
+
+/** A title is not fenced, so an @-mention in it would notify: `@name` becomes `＠name`. */
+export function neutralizeMentions(text: string): string {
+  return text.replace(/@(?=[A-Za-z0-9])/g, '＠');
+}
+
+/** Single line, no control characters, no issue references except its own, no mentions, bounded in UTF-16 units. */
+export function pullRequestTitle(plan: Plan): string {
+  const summary = neutralizeMentions(neutralizeReferences(plan.summary.toWellFormed().replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim())) || 'codeboost plan';
+  const suffix = ` (#${plan.issue})`;
+  return cut(summary, MAX_TITLE - suffix.length) + suffix;
+}
+
+/**
+ * The PR description: the marker that lets codeboost find the PR again, the issue link, and the plan. A needs-human
+ * draft also lists its open problems. When the full plan is too long, only item IDs and titles are listed.
+ */
+export function pullRequestBody(input: { plan: Plan; marker: string; problems?: readonly string[] }): string {
+  const { plan, marker } = input;
+  // The full problems stay in codeboost; the description shows a bounded summary of them.
+  const all = input.problems ?? [], shown = all.slice(0, MAX_PROBLEMS).map(problem => neutralizeReferences(cut(problem, MAX_PROBLEM)));
+  const problems = all.length > shown.length ? [...shown, `(${all.length - shown.length} more in codeboost)`] : shown;
+  const build = (full: boolean) => [
+    marker,
+    `Fixes #${plan.issue}`,
+    '',
+    `Opened by codeboost from plan revision r${plan.revision}. Review it one plan item at a time in codeboost.`,
+    ...(problems.length ? ['', '**Needs human.** These problems are still open:', '', fenced(problems.join('\n\n'))] : []),
+    '',
+    full ? '**Plan**' : '**Plan** (items only; the full plan is too long for this description)',
+    '',
+    fenced(planTextSafe(plan, full)),
+  ].join('\n');
+  const body = build(true);
+  if (body.length <= MAX_BODY) return body;
+  const short = build(false);
+  if (short.length <= MAX_BODY) return short;
+  throw new Error('The plan and its open problems are too long for a pull request description.');
+}
@@ -0,0 +1,7 @@
+/** Cut to at most `max` UTF-16 units (the unit every length bound here counts), never inside a surrogate pair. */
+export function cutText(text: string, max: number): string {
+  if (text.length <= max) return text;
+  let end = max - 1;
+  if (/[\ud800-\udbff]/.test(text[end - 1] ?? '')) end--;
+  return `${text.slice(0, end)}…`;
+}