session-orchestrator 3.24.0 → 4.0.0

package/scripts/lib/quality-gate.mjs

@@ -67,7 +67,7 @@ import { fileURLToPath } from 'node:url';
 import { emitEvent, sessionAttribution } from './events.mjs';
 import { admitSuiteCounts, extractTestCounts } from './gates/gate-helpers.mjs';
 import { redactDiagnosticsBundle } from './quality-gate/diagnostics.mjs';
-import { readLock } from './session-lock.mjs';
+import { readProcessLocalSessionIds } from './session-identity/own-session.mjs';
 
 export { redactDiagnosticsBundle } from './quality-gate/diagnostics.mjs';
 
@@ -114,30 +114,99 @@ function resolveRepoRoot(explicit) {
 }
 
 /**
- * Load default commands from Session Config via `scripts/parse-config.mjs`.
- * Returns a partial object — keys that fail to resolve are simply absent
- * (the caller falls through to DEFAULT_COMMANDS for those).
+ * Closed set of `degraded` reasons for {@link loadCommandsFromSessionConfigDetailed}.
+ *
+ * Its own enum, deliberately not shared with `ci-status-banner.mjs`'s
+ * `DEGRADED_REASONS`: the members below are exactly the three ways THIS
+ * config-read can fail, and an enum whose members are not exhaustively
+ * reachable cannot be switched on exhaustively.
+ *
+ *   - `script-missing` — `scripts/parse-config.mjs` is not on disk.
+ *   - `spawn-failed`   — the subprocess exited non-zero, timed out, or wrote
+ *                        nothing to stdout.
+ *   - `parse-error`    — stdout was not parseable JSON (or the read threw).
+ */
+export const CONFIG_READ_DEGRADED_REASONS = Object.freeze([
+  'script-missing',
+  'spawn-failed',
+  'parse-error',
+]);
+
+/**
+ * Does `repoRoot` carry a Session Config file at all?
+ *
+ * Mirrors the file-name precedence `scripts/parse-config.mjs::resolveConfigFile`
+ * uses (`SO_CONFIG_FILE` → `CLAUDE.md` → `AGENTS.md`) but NOT its upward
+ * project-root walk — see the ceiling note at the call site.
+ *
+ * @param {string} repoRoot
+ * @returns {boolean}
+ */
+function sessionConfigFileExists(repoRoot) {
+  try {
+    const soConfigFile = process.env.SO_CONFIG_FILE;
+    if (soConfigFile && existsSync(join(repoRoot, soConfigFile))) return true;
+    return existsSync(join(repoRoot, 'CLAUDE.md')) || existsSync(join(repoRoot, 'AGENTS.md'));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Load default commands from Session Config via `scripts/parse-config.mjs`,
+ * distinguishing "the config declares no `*-command` keys" from "the config
+ * could not be read at all".
+ *
+ * Both cases yield `commands: {}` — that half is unchanged, and every command
+ * resolution keeps falling through to DEFAULT_COMMANDS exactly as before. What
+ * is new is the second channel: on failure the result also carries a
+ * `degraded` reason from {@link CONFIG_READ_DEGRADED_REASONS}. Without it,
+ * `checkQgCommandDrift` reported "no drift" for a config it never managed to
+ * read — a silent all-clear derived from an absent measurement (#1031's
+ * failure class, one consumer over).
+ *
+ * `degraded` is OMITTED, not set to null, on the success path, so a strict
+ * `toEqual({commands: {…}})` pin holds for every readable config.
  *
  * Never throws.
  *
  * @param {string} repoRoot
- * @returns {{lint?: string, typecheck?: string, test?: string}}
+ * @returns {{commands: {lint?: string, typecheck?: string, test?: string},
+ *            degraded?: 'script-missing'|'spawn-failed'|'parse-error'}}
  */
-export function loadCommandsFromSessionConfig(repoRoot) {
+export function loadCommandsFromSessionConfigDetailed(repoRoot) {
   try {
     const scriptPath = join(
       dirname(fileURLToPath(import.meta.url)),
       '..',
       'parse-config.mjs',
     );
-    if (!existsSync(scriptPath)) return {};
+    if (!existsSync(scriptPath)) return { commands: {}, degraded: 'script-missing' };
     const result = spawnSync('node', [scriptPath], {
       cwd: repoRoot,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
       timeout: 10_000,
     });
-    if (result.status !== 0 || !result.stdout) return {};
+    if (result.status !== 0 || !result.stdout) {
+      // `parse-config.mjs` exits 1 for EVERY failure, including the benign
+      // "this repo has no CLAUDE.md / AGENTS.md at all" — measured 2026-09-05
+      // in an empty tmp dir: stderr `CLAUDE.md or AGENTS.md required`, exit 1.
+      // A repo with no Session Config has no `*-command` value that could
+      // drift, so reporting that as a failed READ would fire a warning on every
+      // such repo (`.claude/rules/host-resources.md` § HR-101 — a warning class
+      // that is usually present is a broken instrument).
+      //
+      // Ceiling (BV-004): `parse-config.mjs` resolves its config via
+      // `findProjectRoot(cwd)` walking UPWARD, this check looks only at
+      // `repoRoot` itself. For a `repoRoot` nested below the project root the
+      // two disagree — and the disagreement resolves toward SILENCE (no
+      // `degraded`), i.e. the pre-#1031 behaviour, never toward a false alarm.
+      // Revisit if a caller starts passing sub-directory roots.
+      return sessionConfigFileExists(repoRoot)
+        ? { commands: {}, degraded: 'spawn-failed' }
+        : { commands: {} };
+    }
     const cfg = JSON.parse(result.stdout);
     const out = {};
     if (typeof cfg['lint-command'] === 'string' && cfg['lint-command'].trim()) {
@@ -149,12 +218,30 @@ export function loadCommandsFromSessionConfig(repoRoot) {
     if (typeof cfg['test-command'] === 'string' && cfg['test-command'].trim()) {
       out.test = cfg['test-command'];
     }
-    return out;
+    return { commands: out };
   } catch {
-    return {};
+    return { commands: {}, degraded: 'parse-error' };
   }
 }
 
+/**
+ * Load default commands from Session Config via `scripts/parse-config.mjs`.
+ * Returns a partial object — keys that fail to resolve are simply absent
+ * (the caller falls through to DEFAULT_COMMANDS for those).
+ *
+ * Thin wrapper over {@link loadCommandsFromSessionConfigDetailed}; byte-identical
+ * return value for every input, including every failure path. Callers that need
+ * to tell a failed read from an empty config use the detailed variant.
+ *
+ * Never throws.
+ *
+ * @param {string} repoRoot
+ * @returns {{lint?: string, typecheck?: string, test?: string}}
+ */
+export function loadCommandsFromSessionConfig(repoRoot) {
+  return loadCommandsFromSessionConfigDetailed(repoRoot).commands;
+}
+
 /**
  * Resolve the three gate commands. Precedence: override > session config > defaults.
  *
@@ -420,44 +507,32 @@ function listChangedFiles(repoRoot, ref) {
  * The id-space THIS process belongs to, for comparison against a repo-global
  * file that any session in the working copy may have written.
  *
- * Two sources, both read rather than invented — this deliberately adds no third
- * way of answering "who am I" (`scripts/lib/lock-reaper.mjs` takes the id from
- * its caller; `scripts/lib/peer-discovery.mjs` reads `readLock()`):
- *
- *   1. `CLAUDE_CODE_SESSION_ID` — the only PER-PROCESS source, and therefore
- *      the only one a foreign session cannot spoof by writing a file. Measured
- *      2026-08-23 inside a dispatched wave agent: present, and equal to the
- *      coordinator's `current-session.json` `session_id` (a child session
- *      inherits the parent's id, which is what makes it usable here).
- *      `scripts/lib/spiral-carryover.mjs` reads the same variable, under the
- *      same measured premise.
- *   2. `session.lock` `session_id` / `semantic_session_id` — a repo-global
- *      FALLBACK for harnesses that export no session env var. Weaker on
- *      purpose: the lock is one more shared file in the same working copy, so
- *      it can name a peer rather than us. It is used only when (1) is absent,
- *      where the alternative is no check at all.
+ * Process-local witnesses ONLY (`CLAUDE_CODE_SESSION_ID`, via
+ * {@link readProcessLocalSessionIds}) — the `session.lock` fallback this
+ * function used to carry is deliberately GONE, not merely deprioritised.
+ * `session.lock` is a repo-GLOBAL artefact any session in the working copy
+ * can hold; unioning or falling back to it made a shared resource stand in
+ * for a process-local identity, which is exactly the #1194 hazard class
+ * (`.claude/rules/host-resources.md` § HR-102 — "a better signal REPLACES a
+ * worse one, it does not merely suppress it"). Concretely for this module
+ * (#1205): without the env var, a process that is NOT the lock holder used to
+ * silently adopt the lock holder's id as its own, so a `current-session.json`
+ * written by that same holder passed the ownership check by construction.
+ * `readProcessLocalSessionIds()` (`./session-identity/own-session.mjs`) is
+ * the shared, already-hardened implementation of this exact question — see
+ * its JSDoc for the full lock/STATE.md exclusion rationale.
+ *
+ * An empty result is not a mismatch: {@link classifyCurrentSessionOwnership}
+ * treats an empty `ownIds` as `'unknown'`, never `'foreign'`, so
+ * `corrective_context` is kept — the existing fail-open contract from #1058,
+ * unchanged by this fix.
  *
- * @param {string} repoRoot
  * @returns {Set<string>} possibly empty — an empty set means "identity
  *   unresolvable", which the classifier below treats as `unknown`, never as a
  *   mismatch.
  */
-function readOwnSessionIds(repoRoot) {
-  const ids = new Set();
-  // `.trim()` first: a whitespace-only env var is truthy and would otherwise
-  // enter the set as a phantom id (`development.md` § env-var whitespace trap).
-  const fromEnv = (process.env.CLAUDE_CODE_SESSION_ID || '').trim();
-  if (fromEnv) ids.add(fromEnv);
-  if (ids.size === 0) {
-    try {
-      const lock = readLock({ repoRoot });
-      for (const key of ['session_id', 'semantic_session_id']) {
-        const value = typeof lock?.[key] === 'string' ? lock[key].trim() : '';
-        if (value) ids.add(value);
-      }
-    } catch { /* readLock never throws, but the contract is not ours to trust */ }
-  }
-  return ids;
+function readOwnSessionIds() {
+  return new Set(readProcessLocalSessionIds({ env: process.env, hookInput: null }));
 }
 
 /**
@@ -534,7 +609,8 @@ function readCorrectiveContext(repoRoot) {
     if (!existsSync(p)) return [];
     const raw = readFileSync(p, 'utf8');
     const parsed = JSON.parse(raw);
-    const { verdict, fileIds } = classifyCurrentSessionOwnership(parsed, readOwnSessionIds(repoRoot));
+    const ownIds = readOwnSessionIds();
+    const { verdict, fileIds } = classifyCurrentSessionOwnership(parsed, ownIds);
     if (verdict === 'foreign') {
       process.stderr.write(
         `⚠️  quality-gate: .orchestrator/current-session.json belongs to another session ` +
@@ -543,6 +619,19 @@ function readCorrectiveContext(repoRoot) {
       );
       return [];
     }
+    // The fail-open half of `verdict === 'unknown'`: the file DOES name an id,
+    // but this process has no process-local witness of its own (ownIds is
+    // empty — no `CLAUDE_CODE_SESSION_ID`, e.g. Codex/Cursor). Ownership is
+    // unprovable, so the content is kept per the #1058 contract — but silently
+    // is the wrong word for that: make the fail-open visible on stderr rather
+    // than indistinguishable from a verified 'own' match.
+    if (verdict === 'unknown' && fileIds.length > 0 && ownIds.size === 0) {
+      process.stderr.write(
+        '⚠ quality-gate: cannot verify ownership of .orchestrator/current-session.json ' +
+        '(no process-local session id — CLAUDE_CODE_SESSION_ID unset); keeping corrective_context ' +
+        `from session ${fileIds.join(', ')} UNVERIFIED\n`,
+      );
+    }
     const arr = Array.isArray(parsed?.corrective_context) ? parsed.corrective_context : [];
     return arr.slice(-CORRECTIVE_CONTEXT_TAIL);
   } catch {

package/scripts/lib/reconcile/emitter.mjs

@@ -172,18 +172,37 @@ const GLOB_METACHAR_RE = /[*?[\]{}()]|[!@+](?=\()/;
  * {@link UNSAFE_PATH_QUOTE_RE}). Results are deduped, order-preserving on
  * first occurrence.
  *
+ * #1153 P13: skipping used to be entirely silent, so a learning whose ONLY
+ * `file_paths` entry was unusable produced the generic "no activation axis"
+ * rejection with nothing naming WHY the axis was empty. Every skipped entry is
+ * therefore recorded into the optional `dropped` sink (value + one-word
+ * reason), which {@link formatDroppedFilePaths} renders into that rejection
+ * reason. The sink is an out-parameter rather than a changed return type so
+ * every existing caller stays byte-identical.
+ *
  * @param {string[]} filePaths
+ * @param {{value: string, reason: string}[]} [dropped] - out-param sink
  * @returns {string[]}
  */
-function globsFromFilePaths(filePaths) {
+function globsFromFilePaths(filePaths, dropped) {
   const out = [];
   const seen = new Set();
   for (const raw of filePaths) {
     if (typeof raw !== 'string' || raw === '') continue;
-    if (GLOB_METACHAR_RE.test(raw)) continue;
+    if (GLOB_METACHAR_RE.test(raw)) {
+      dropped?.push({ value: raw, reason: 'glob-metachar' });
+      continue;
+    }
     // #1015: frontmatter-structure guard. Skipping (never escaping) keeps this
     // idempotent and non-overlapping with the renderer's sanitiser.
-    if (CONTROL_CHARS_TEST_RE.test(raw) || UNSAFE_PATH_QUOTE_RE.test(raw)) continue;
+    if (CONTROL_CHARS_TEST_RE.test(raw)) {
+      dropped?.push({ value: raw, reason: 'control-char' });
+      continue;
+    }
+    if (UNSAFE_PATH_QUOTE_RE.test(raw)) {
+      dropped?.push({ value: raw, reason: 'quote' });
+      continue;
+    }
     const normalized = raw.replace(/\\/g, '/');
     const dir = dirname(normalized);
     const pattern = dir === '.' ? normalized : `${dir}/**`;
@@ -195,6 +214,42 @@ function globsFromFilePaths(filePaths) {
   return out;
 }
 
+/** Max chars of a single dropped `file_paths` value in a rejection reason. */
+const DROPPED_VALUE_MAX = 60;
+
+/**
+ * Render the `dropped` sink of {@link globsFromFilePaths} into a suffix for the
+ * never-always-on rejection reason (#1153 P13).
+ *
+ * The reason string is OPERATOR-VISIBLE (engine.mjs forwards it verbatim into
+ * `reason: emit/render error: …` and from there into the candidates ledger), so
+ * a hostile `file_paths` entry must not be able to inject newlines or ANSI into
+ * it. Each value is therefore `JSON.stringify`-escaped — which turns every
+ * control char into a `\uXXXX` literal — and then hard-truncated to
+ * {@link DROPPED_VALUE_MAX} chars, with any trailing partial backslash escape
+ * removed so the cut cannot end mid-sequence.
+ *
+ * @param {{value: string, reason: string}[]} dropped
+ * @returns {string} `''` when nothing was dropped, else a ` — dropped …` suffix
+ */
+function formatDroppedFilePaths(dropped) {
+  if (!Array.isArray(dropped) || dropped.length === 0) return '';
+  const rendered = dropped.map(({ value, reason }) => {
+    const escaped = JSON.stringify(String(value));
+    const clipped =
+      escaped.length <= DROPPED_VALUE_MAX
+        ? escaped
+        // A `\uXXXX` escape is 6 chars, so the cut can land at FIVE distinct
+        // depths inside one — and `/\\+$/` only ever caught the shallowest
+        // (`\`). Measured at DROPPED_VALUE_MAX=60 with a NUL at offsets 53..56:
+        // the old form left `\u000`, `\u00`, `\u0` and `\u` standing. Strip the
+        // backslash together with up to three hex digits of a partial `u`-escape.
+        : `${escaped.slice(0, DROPPED_VALUE_MAX - 1).replace(/\\(u[0-9a-fA-F]{0,3})?$/, '')}…`;
+    return `${clipped} (${reason})`;
+  });
+  return ` — dropped file_paths: ${dropped.length} (${rendered.join(', ')})`;
+}
+
 /**
  * Build a single-line, frontmatter-safe description from a learning.
  *
@@ -320,7 +375,8 @@ export function toActivationMetadata(learning, { ruleExpiryDays, now, minRuleDay
   }
 
   const filePaths = Array.isArray(learning.file_paths) ? learning.file_paths : [];
-  const globs = globsFromFilePaths(filePaths);
+  const droppedFilePaths = [];
+  const globs = globsFromFilePaths(filePaths, droppedFilePaths);
 
   // #1015: `host_class` is copied straight into an UNQUOTED `host-class:`
   // frontmatter line by the renderer, so its SHAPE is load-bearing. Reject a
@@ -358,16 +414,22 @@ export function toActivationMetadata(learning, { ruleExpiryDays, now, minRuleDay
   // The brandmauer: an auto-generated rule must carry ≥1 activation axis. If we
   // could derive neither a glob nor a host-class, refuse — never emit always-on.
   if (globs.length === 0 && hostClass === undefined) {
+    // #1153 P13: name the entries that were silently skipped on the way here —
+    // otherwise "no activation axis" is indistinguishable from "no file_paths
+    // at all", and the operator has no way to see that a malformed record (not
+    // an empty one) caused the rejection.
+    const droppedSuffix = formatDroppedFilePaths(droppedFilePaths);
     if (hostClassDroppedByType) {
       throw new Error(
         `emitter: host_class ${JSON.stringify(learning.host_class)} is present and well-formed, but type ` +
           `${JSON.stringify(learning.type)} is not host-specific (#1090 — host-class is only copied through for ` +
           `${[...HOST_SPECIFIC_TYPES].join(', ')}) — refusing to emit always-on auto-generated rule ` +
-          '(never-always-on invariant); no other activation axis (globs) is available either.',
+          `(never-always-on invariant); no other activation axis (globs) is available either.${droppedSuffix}`,
       );
     }
     throw new Error(
-      'emitter: no activation axis (globs/host-class) — refusing to emit always-on auto-generated rule (never-always-on invariant)',
+      'emitter: no activation axis (globs/host-class) — refusing to emit always-on auto-generated rule ' +
+        `(never-always-on invariant)${droppedSuffix}`,
     );
   }
 

package/scripts/lib/reconcile/engine.mjs

@@ -160,8 +160,10 @@ function zeroedResult(error) {
 /**
  * Default learnings loader — read + parse `<repoRoot>/.orchestrator/metrics/learnings.jsonl`
  * line-by-line, migrate/normalize records through the learnings schema SSOT,
- * and skip blank/malformed lines. A missing file yields `[]`. Never throws (a
- * read error degrades to `[]`).
+ * and skip blank/malformed lines. A missing file (ENOENT) yields `[]`
+ * silently; an unreadable one (EACCES/EISDIR/…) yields `[]` with a stderr
+ * WARN (#1210 — ENOENT and other read failures are different facts, same
+ * split as `sessions-canonical.mjs` `readCanonicalSessions`).
  *
  * @param {string|undefined} repoRoot
  * @returns {Array<Record<string, unknown>>}
@@ -175,8 +177,15 @@ function defaultLoadLearnings(repoRoot) {
   let raw;
   try {
     raw = readFileSync(absPath, 'utf8');
-  } catch {
-    return []; // ENOENT or any read error → empty corpus.
+  } catch (err) {
+    if (!err || err.code !== 'ENOENT') {
+      process.stderr.write(
+        `⚠ defaultLoadLearnings: cannot read ${absPath} ` +
+          `(${err?.code ?? '?'}: ${err?.message ?? String(err)}) — ` +
+          'treating as EMPTY, counts below are floors\n',
+      );
+    }
+    return [];
   }
 
   /** @type {Array<Record<string, unknown>>} */

package/scripts/lib/reconcile/idempotency.mjs

@@ -391,7 +391,14 @@ export function mergeCandidates({ candidates, repoRoot, storePath } = {}) {
  * @param {number} [params.fallbackConfidence] - used only when no existing record is found.
  * @param {string} [params.repoRoot]
  * @param {string} [params.storePath]
- * @returns {{ written: boolean, stamped: ReconcileCandidate|null }}
+ * @returns {{ written: boolean, stamped: ReconcileCandidate|null, alreadyProcessed?: boolean }}
+ *   `stamped` is the record as PERSISTED (read back out of `mergeCandidates`'s
+ *   merged array), never the one this call merely proposed — when a prior
+ *   terminal verdict wins the dedupe, the two differ and only the former is
+ *   true. `alreadyProcessed: true` marks exactly that case; `written` stays
+ *   `true` there, because the store holds the intended terminal state and
+ *   `written: false` means a WRITE FAILURE to the one production caller
+ *   (`writer.mjs`, which turns it into an operator-visible error).
  */
 export function markCandidateProcessed({
   learningKey,
@@ -419,6 +426,7 @@ export function markCandidateProcessed({
     stamped = { ...found, processed_at: stampAt, outcome: typeof outcome === 'string' ? outcome : (found.outcome ?? null) };
   } else {
     const slug = typeof fallbackSlug === 'string' ? fallbackSlug : '';
+    const finalOutcome = typeof outcome === 'string' ? outcome : null;
     stamped = buildCandidate({
       id:
         typeof fallbackCandidateId === 'string' && fallbackCandidateId.length > 0
@@ -426,15 +434,40 @@ export function markCandidateProcessed({
           : makeCandidateId(learningKey, slug),
       learningKey,
       slug,
-      status: 'proposed',
+      // A minted record is TERMINAL from birth (`processed_at` is set two lines
+      // below), so `status` must agree with `outcome` instead of always saying
+      // `'proposed'` — a record reading `status:'proposed'` while carrying
+      // `outcome:'rejected'` is self-contradictory and misreads as a live
+      // proposal to anything that renders `status`. The vocabulary is exactly
+      // the two members of the ReconcileCandidate typedef; nothing new is
+      // invented here: `'rejected'` for the operator-rejection outcome
+      // (writer.mjs, issue #1042), `'proposed'` for the accepted outcomes
+      // (`'written'` / `'already-on-disk'`), where the proposal stood.
+      status: finalOutcome === 'rejected' ? 'rejected' : 'proposed',
       reason: 'stamped without a prior sidecar record',
       confidence: typeof fallbackConfidence === 'number' ? fallbackConfidence : 0,
       createdAt: stampAt,
     });
     stamped.processed_at = stampAt;
-    stamped.outcome = typeof outcome === 'string' ? outcome : null;
+    stamped.outcome = finalOutcome;
   }
 
   const result = mergeCandidates({ candidates: [stamped], repoRoot, storePath });
-  return { written: result.written === true, stamped };
+
+  // Report what is PERSISTED, not what we asked for. `mergeCandidates`'s dedupe
+  // rule keeps an already-terminal existing record and DROPS the incoming one,
+  // so when `found` was already processed the store still holds the OLD
+  // `processed_at`/`outcome` — returning our freshly-built `stamped` would tell
+  // the caller a verdict that is nowhere on disk. `merged` IS the array that was
+  // just written, so reading the record back out of it is the honest answer.
+  const persisted = result.merged.find((rec) => rec && rec.learning_key === learningKey);
+  return {
+    written: result.written === true,
+    stamped: persisted ?? stamped,
+    // `true` iff a prior terminal verdict won and this call changed nothing on
+    // disk. `written` deliberately stays `true` in that case: the store IS in
+    // the intended terminal state, and writer.mjs treats `written:false` as a
+    // stamp FAILURE worth an operator-visible error.
+    alreadyProcessed: isTerminal(found),
+  };
 }

package/scripts/lib/reconcile/writer.mjs

@@ -457,26 +457,37 @@ function frontmatterRefusalReason(content) {
  * not yet mature enough — silently, and with no way back short of editing the
  * sidecar by hand.
  *
- * The discriminator is the rendered `content`: `engine.mjs` pushes its own
- * rejections as `{learningKey, type, reason, status:'rejected'}` — they never
- * reach the renderer, so they never carry `content`/`slug`/`path` — while the
- * proposals the operator declines are full `ReconcileProposal` records whose
- * `content` is the very rule text the AUQ showed him.
- *
- * CEILING (BV-004): this reads an implicit signal, not an explicit marker,
- * because the one production caller (`skills/session-end/phase-3-6-tail.md`
- * step 6/7) concatenates engine rejections and operator-declined proposals into
- * ONE `rejected` array and marks neither. Revisit if that caller starts passing
- * rendered content on engine-side rejections, or if it gains an explicit
- * operator-rejection flag — then key on the flag instead.
- *
- * @param {WriterRejectedItem & {content?: unknown, learningKey?: unknown}} item
+ * PRIMARY discriminator (#1153 P15): the explicit `operatorRejected: true`
+ * flag that `skills/session-end/phase-3-6-tail.md` step 6 stamps on every
+ * proposal the operator left unselected before concatenating it into the one
+ * `rejected` array. `engine.mjs` pushes its own rejections as
+ * `{learningKey, type, reason, status:'rejected'}` and never sets the flag, so
+ * the two shapes are now distinguishable by a marker rather than by inference.
+ *
+ * FALLBACK (@deprecated — remove once no supported skill body predates the P15
+ * stamp): when the flag is absent, fall back to the old implicit signal — the
+ * rendered `content`. Engine rejections never reach the renderer, so they never
+ * carry `content`/`slug`/`path`, while an operator-declined proposal is a full
+ * `ReconcileProposal` whose `content` is the rule text the AUQ showed him. The
+ * fallback exists because the skill prose and this module ship together but
+ * consumer repos may pin an OLDER `phase-3-6-tail.md` that emits no flag;
+ * dropping it immediately would silently stop stamping their operator
+ * rejections terminal (the exact #1042 bug). REMOVAL TRIGGER: the next major
+ * release in which no supported consumer ships a pre-P15 skill body.
+ *
+ * Either way the decision stays conservative in the same direction: a false
+ * negative costs nothing (the learning is re-proposed next run); a false
+ * positive would permanently suppress a learning that was only capped.
+ *
+ * @param {WriterRejectedItem & {content?: unknown, learningKey?: unknown, operatorRejected?: unknown}} item
  * @returns {boolean}
  */
 function isOperatorRejection(item) {
   if (!item || typeof item !== 'object') return false;
-  if (typeof item.content !== 'string' || item.content.length === 0) return false;
-  return typeof item.learningKey === 'string' && item.learningKey.length > 0;
+  if (typeof item.learningKey !== 'string' || item.learningKey.length === 0) return false;
+  if (item.operatorRejected === true) return true;
+  // @deprecated fallback — pre-P15 skill bodies emit no flag; see above.
+  return typeof item.content === 'string' && item.content.length > 0;
 }
 
 // ---------------------------------------------------------------------------
@@ -663,8 +674,12 @@ export async function writeApprovedRules({
             repoRoot,
           });
           if (!stampResult.written) {
+            // Same discrimination as the rejected path below (identical shape,
+            // identical reader): an already-terminal record is not a lost stamp.
             errors.push(
-              `sidecar-stamp failed for "${item.path ?? item.slug}" (learningKey=${item.learningKey}) — rule file was written but the idempotency sidecar was not updated`,
+              stampResult.alreadyProcessed
+                ? `sidecar-stamp for "${item.path ?? item.slug}" (learningKey=${item.learningKey}) wrote nothing — a prior terminal verdict is already on disk, so the rule file landed and the candidate stays terminal`
+                : `sidecar-stamp failed for "${item.path ?? item.slug}" (learningKey=${item.learningKey}) — rule file was written but the idempotency sidecar was not updated`,
             );
           }
         }
@@ -724,8 +739,15 @@ export async function writeApprovedRules({
                   repoRoot,
                 });
                 if (!stampResult.written) {
+                  // `alreadyProcessed` distinguishes the two failures that look
+                  // identical from `written:false` alone. When a PRIOR terminal
+                  // verdict is already on disk, the re-proposal warning is
+                  // simply false — the sidecar holds the state we wanted — and
+                  // telling the operator otherwise sends him after a non-bug.
                   errors.push(
-                    `sidecar-stamp failed for rejected "${item.learningKey}" — the rejection was archived but the idempotency sidecar was not updated, so a later run may re-propose it`,
+                    stampResult.alreadyProcessed
+                      ? `sidecar-stamp for rejected "${item.learningKey}" wrote nothing — a prior terminal verdict is already on disk, so the rejection is recorded and it will NOT be re-proposed`
+                      : `sidecar-stamp failed for rejected "${item.learningKey}" — the rejection was archived but the idempotency sidecar was not updated, so a later run may re-propose it`,
                   );
                 }
               }