session-orchestrator 5.11.0 → 5.13.0

package/scripts/lib/issue-budget-reconcile.mjs

@@ -261,8 +261,9 @@ export function reconcileIssueBudget({
  * Emit the reconciliation record to the repo's event ledger.
  *
  * Follows `_emitEvaluated` in `scripts/lib/express-path.mjs`: `events.mjs` is
- * imported LAZILY (a static import would pull `platform.mjs`, which walks the
- * filesystem at module load, into every consumer of this module), `repoRoot` is
+ * imported LAZILY (it is not needed by the verdict path; `platform.mjs` is
+ * already reached statically through `issue-budget.mjs`, which maps the
+ * counter-file root through it since #1729), `repoRoot` is
  * passed EXPLICITLY and a missing one SKIPS the emit rather than falling
  * through to the ambient `SO_PROJECT_DIR` — writing a synthetic record into the
  * operator's real fleet ledger is unrecoverable, a skipped record is not — and

package/scripts/lib/issue-budget.mjs

@@ -33,10 +33,11 @@ import { homedir } from 'node:os';
 import path from 'node:path';
 
 import { writeJsonAtomicSync } from './io.mjs';
+import { resolveEventsLedgerRoot } from './platform.mjs';
 import { resolveInstructionFile } from './common.mjs';
 import { _parseIssueBudget } from './config/issue-budget.mjs';
 import { parseStateMd } from './state-md/yaml-parser.mjs';
-import { resolveStateMdPath } from './state-md/frontmatter-mutators.mjs';
+import { resolveStateMdWriteTarget } from './state-md/frontmatter-mutators.mjs';
 
 /**
  * Legacy single-slot counter file, relative to the repo root.
@@ -192,8 +193,11 @@ export function resolveMaxPerSession(cfg, sessionType) {
  */
 export function readSessionTypeFromStateMd(repoRoot) {
   try {
-    const filePath = resolveStateMdPath(repoRoot);
-    if (!existsSync(filePath)) return null;
+    // #1636: the write side's ownership rule — another platform's STATE.md not
+    // proven to be this process's must not set THIS session's budget; it counts
+    // as absent (default budget). No warn line: this runs on every Bash call.
+    const { path: filePath, rejected } = resolveStateMdWriteTarget(repoRoot);
+    if (rejected || !existsSync(filePath)) return null;
     const parsed = parseStateMd(readFileSync(filePath, 'utf8'));
     const value = parsed?.frontmatter?.['session-type'];
     return typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
@@ -251,7 +255,27 @@ export function loadIssueBudgetConfig(repoRoot) {
  * @returns {string}
  */
 export function budgetStatePath(repoRoot, sessionId = null) {
-  return path.join(repoRoot, budgetStateRel(sessionId));
+  return path.join(budgetStateRoot(repoRoot), budgetStateRel(sessionId));
+}
+
+/**
+ * Root directory the runtime counter files live under (#1729). The PreToolUse
+ * hook charges at `CLAUDE_PROJECT_DIR` (usually the MAIN checkout) while
+ * session-end reconciles and reaps with the linked-worktree root; joining the
+ * raw root made the two sides open different files and report a false
+ * `no-ledger`. Mapping a linked worktree to its main checkout (the same
+ * resolver the event ledger uses) makes every reader and writer agree. Any
+ * other root (plain checkout, non-git dir, submodule) is returned resolved but
+ * otherwise unchanged. A non-string or blank root is passed through untouched
+ * so `path.join` keeps its previous behaviour instead of falling back to the
+ * ambient project dir.
+ *
+ * @param {string} repoRoot
+ * @returns {string}
+ */
+function budgetStateRoot(repoRoot) {
+  if (typeof repoRoot !== 'string' || repoRoot.trim() === '') return repoRoot;
+  return resolveEventsLedgerRoot(repoRoot);
 }
 
 /**
@@ -360,7 +384,9 @@ export function readBudgetState(repoRoot, sessionId) {
   // session has a file of its own.
   if (existsSync(ownFile)) return fresh;
 
-  return _readStateFile(path.join(repoRoot, BUDGET_STATE_REL), accountingSessionId) ?? fresh;
+  return (
+    _readStateFile(path.join(budgetStateRoot(repoRoot), BUDGET_STATE_REL), accountingSessionId) ?? fresh
+  );
 }
 
 /**
@@ -882,11 +908,14 @@ export function reapStaleBudgetFiles({
   const removed = [];
   const kept = [];
   try {
-    const dir = path.join(repoRoot, BUDGET_STATE_DIR_REL);
+    // Directory and own file from ONE mapped root (#1729): mapping only one of
+    // them would make the `file === ownFile` protection below never match.
+    const stateRoot = budgetStateRoot(repoRoot);
+    const dir = path.join(stateRoot, BUDGET_STATE_DIR_REL);
     const cutoff = now - maxAgeDays * 24 * 60 * 60 * 1000;
     const ownFile =
       typeof sessionId === 'string' && sessionId.length > 0
-        ? budgetStatePath(repoRoot, sessionId)
+        ? path.join(stateRoot, budgetStateRel(sessionId))
         : null;
 
     let names;

package/scripts/lib/learnings/evidence-candidates.mjs

@@ -0,0 +1,154 @@
+/**
+ * Explicit, private-audience candidate artifacts are advisory lookup hints.
+ * Only current local JSONL records enter the selector; artifact paths, scores
+ * and text never become records, executable commands or additional authority.
+ */
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { TextDecoder } from 'node:util';
+import { z } from 'zod';
+
+import { parseLearningsText } from './io.mjs';
+import { digestMultiBufferSha256 } from '../crypto-digest-utils.mjs';
+
+// At most 40 hints in a small local artifact. Revisit the byte ceiling only if
+// a valid 40-candidate producer payload demonstrably exceeds it.
+export const EVIDENCE_ARTIFACT_MAX_BYTES = 128 * 1024;
+
+const hash = z.string().regex(/^sha256:[0-9a-f]{64}$/);
+const repo = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/);
+const evidenceType = z.enum(['learning', 'skill', 'adr']);
+const retrievalMode = z.enum(['bm25', 'eg2', 'rrf']);
+const unique = (values) => new Set(values).size === values.length;
+const candidate = z.object({
+  evidence_type: evidenceType,
+  source_repo: repo,
+  source_record_id: z.string().min(1).max(200).optional(),
+  source_generation: hash.optional(),
+  source_path: z.string().min(1).regex(/^(?!\/)(?![A-Za-z]:)(?!.*(?:^|\/)\.\.(?:\/|$))(?!.*\\).+$/),
+  source_sha256: hash,
+  source_revision: z.string().min(1).max(64),
+  line_start: z.number().int().min(1),
+  line_end: z.number().int().min(1),
+  index_generation: hash,
+  modelspace: hash,
+  rank: z.number().int().min(1).max(40),
+}).strict().refine((value) => value.evidence_type === 'learning'
+  ? value.source_record_id !== undefined && value.source_generation !== undefined
+  : value.source_record_id === undefined && value.source_generation === undefined);
+
+/** Local boundary for urn:local-evidence:candidate-artifact:1. */
+export const evidenceCandidateSchema = z.object({
+  schema_version: z.literal(1),
+  status: z.enum(['ok', 'empty', 'disabled', 'stale', 'unavailable', 'unreadable', 'corrupt', 'modelspace_mismatch', 'error']),
+  query: z.object({
+    text: z.string().min(1).max(4000),
+    source_repos: z.array(repo).min(1).refine(unique),
+    audience: z.literal('private'),
+    evidence_types: z.array(evidenceType).min(1).refine(unique),
+  }).strict(),
+  freshness: z.object({
+    mode: z.literal('live_sources'),
+    checked_at: z.string().datetime({ offset: true }),
+  }).strict(),
+  generation: hash.nullable(),
+  source_generations: z.record(repo, hash),
+  retrieval: z.object({
+    requested: retrievalMode,
+    effective: retrievalMode,
+    fallback_reason: z.enum(['semantic_unconfigured', 'semantic_unavailable', 'semantic_failed', 'modelspace_mismatch', 'index_lexical_only']).optional(),
+  }).strict(),
+  candidates: z.array(candidate).max(40),
+}).strict().refine((value) => value.status === 'ok' || value.candidates.length === 0);
+
+/** Bounded regular-file read; a supplied FIFO must not hang a dispatch. */
+async function readArtifact(filePath) {
+  const handle = await open(filePath, constants.O_RDONLY | constants.O_NONBLOCK);
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.size > EVIDENCE_ARTIFACT_MAX_BYTES) throw new Error('invalid-artifact-file');
+    const buffer = Buffer.alloc(EVIDENCE_ARTIFACT_MAX_BYTES + 1);
+    let size = 0;
+    while (size < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, size, buffer.length - size, size);
+      if (bytesRead === 0) break;
+      size += bytesRead;
+    }
+    if (size > EVIDENCE_ARTIFACT_MAX_BYTES) throw new Error('artifact-too-large');
+    return JSON.parse(buffer.subarray(0, size).toString('utf8'));
+  } finally {
+    await handle.close();
+  }
+}
+
+/**
+ * Resolve hints against the explicitly supplied current repo's canonical store.
+ * Missing/stale/corrupt inputs return no additions, preserving the baseline.
+ * Diagnostics contain only statuses/counts, never artifact paths or query text.
+ */
+export async function readEvidenceCandidates({ artifactPath, sourceRepo, query, sourceBytes }) {
+  const result = (status, reason, entries = [], dropped = 0, retrieval) => ({
+    entries,
+    diagnostics: { status, ...(reason ? { reason } : {}), accepted: entries.length, dropped,
+      ...(retrieval ? { retrieval } : {}) },
+  });
+  if (!repo.safeParse(sourceRepo).success || typeof query !== 'string' || !query.trim() ||
+      query.length > 4000 || typeof artifactPath !== 'string' || !artifactPath) {
+    return result('corrupt', 'invalid_request');
+  }
+  let artifact;
+  try {
+    const parsed = evidenceCandidateSchema.safeParse(await readArtifact(artifactPath));
+    if (!parsed.success) return result('corrupt', 'invalid_artifact');
+    artifact = parsed.data;
+  } catch (error) {
+    if (error instanceof SyntaxError) return result('corrupt', 'invalid_artifact');
+    return result(error?.code === 'ENOENT' ? 'unavailable' : 'unreadable', 'artifact_read_failed');
+  }
+  if (artifact.query.text !== query || artifact.query.source_repos.length !== 1 ||
+      artifact.query.source_repos[0] !== sourceRepo) return result('corrupt', 'request_mismatch');
+  if (artifact.status !== 'ok') return result(artifact.status, 'provider_status', [], 0, artifact.retrieval);
+  if (artifact.generation === null) return result('corrupt', 'missing_generation');
+
+  // One source read supplies BOTH the baseline pool and these original records.
+  // A missing store is distinct from an existing, valid empty JSONL snapshot.
+  if (!Buffer.isBuffer(sourceBytes)) return result('unavailable', 'source_read_failed');
+  let sourceText;
+  try {
+    // ignoreBOM retains the BOM in the decoded text; the canonical parser
+    // removes it only from the first record, never from the generation hash.
+    sourceText = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(sourceBytes);
+  } catch {
+    return result('corrupt', 'source_utf8_invalid');
+  }
+  const snapshot = {
+    ...parseLearningsText(sourceText),
+    generation: `sha256:${digestMultiBufferSha256([sourceBytes])}`,
+  };
+  if (artifact.source_generations[sourceRepo] !== snapshot.generation) {
+    return result('stale', 'source_generation_mismatch');
+  }
+
+  const byId = new Map();
+  for (const entry of snapshot.entries) {
+    if (typeof entry.id !== 'string') continue;
+    // An ambiguous duplicate ID cannot identify one original record.
+    byId.set(entry.id, byId.has(entry.id) ? null : entry);
+  }
+  const entries = [];
+  const seen = new Set();
+  let dropped = 0;
+  for (const hint of artifact.candidates) {
+    const entry = byId.get(hint.source_record_id);
+    if (hint.evidence_type !== 'learning' || !artifact.query.evidence_types.includes('learning') ||
+        hint.source_repo !== sourceRepo || hint.source_generation !== snapshot.generation ||
+        hint.source_sha256 !== snapshot.generation || hint.index_generation !== artifact.generation ||
+        hint.line_end < hint.line_start || !entry || seen.has(hint.source_record_id)) {
+      dropped++;
+      continue;
+    }
+    seen.add(hint.source_record_id);
+    entries.push(entry);
+  }
+  return result('ok', undefined, entries, dropped, artifact.retrieval);
+}

package/scripts/lib/learnings/expiry-sweep.mjs

@@ -70,8 +70,15 @@
 import { constants as fsConstants, existsSync } from 'node:fs';
 import { mkdir, appendFile, copyFile } from 'node:fs/promises';
 import path from 'node:path';
-import { readLearnings, readLearningsSnapshot, rewriteLearnings, withLearningsLock } from './io.mjs';
+import {
+  appendInboxReceipts,
+  readLearnings,
+  readLearningsSnapshot,
+  rewriteLearnings,
+  withLearningsLock,
+} from './io.mjs';
 import { redactHomeDir } from '../common.mjs';
+import { assertStoreRoleUsable, isCanonicalStore, resolveStoreRole } from './store-role.mjs';
 
 /**
  * Thrown by {@link pruneLearnings} when `expectedGeneration` no longer matches
@@ -216,6 +223,26 @@ function reconcileKey(entry) {
  */
 export const ARCHIVE_REASONS = Object.freeze(['expired', 'pruned', 'superseded', 'merged']);
 
+/**
+ * Value of the additive `skipped` result field when an APPLY ran on a host
+ * whose learnings-store role is `inbox` (#1516).
+ */
+export const SKIPPED_STORE_ROLE_INBOX = 'store-role-inbox';
+
+/**
+ * True when an apply against `filePath` must not archive or rewrite (#1516):
+ * the canonical store on an `inbox`-role host. There `rewriteLearnings()`
+ * never touches the live store, so an archive append would record learnings
+ * that are still live. Dry runs are unaffected — they write nothing and keep
+ * reporting what a writer host would do.
+ *
+ * @param {unknown} filePath
+ * @returns {boolean}
+ */
+function isInboxRoleStore(filePath) {
+  return typeof filePath === 'string' && isCanonicalStore(filePath) && resolveStoreRole().role === 'inbox';
+}
+
 /** Reason -> the tombstone field that reason MUST carry. */
 const TOMBSTONE_FIELD = Object.freeze({
   superseded: '_superseded_by',
@@ -360,7 +387,7 @@ function resolveNowMs(now) {
  * @param {number} opts.nowMs
  * @param {boolean} opts.dryRun
  * @returns {Promise<{kept: number, archived: number, byReason: Record<string, number>,
- *   malformedField: {malformed?: number}}>}
+ *   malformedField: {malformed?: number}, skipped?: string}>}
  */
 async function archiveThenRewrite({
   filePath,
@@ -372,6 +399,21 @@ async function archiveThenRewrite({
   nowMs,
   dryRun,
 }) {
+  if (!dryRun && isInboxRoleStore(filePath)) {
+    // Inbox role (#1516): no archive line — the live store keeps every record,
+    // so archiving one would duplicate a live learning. The rewrite still runs:
+    // on this role it only appends the batch's NEW ids to the inbox (e.g. the
+    // session's fresh learnings from apply-session-learnings) and drops every
+    // update, removal and consolidation.
+    await rewriteLearnings(filePath, keep, { dryRun: false, malformedLines: malformed });
+    return {
+      kept: keep.length,
+      archived: 0,
+      byReason: {},
+      malformedField: malformedField(filePath, malformed, malformedLineNumbers),
+      skipped: SKIPPED_STORE_ROLE_INBOX,
+    };
+  }
   const byReason = countByReason(archiveBatch);
   const result = {
     kept: keep.length,
@@ -402,6 +444,18 @@ async function archiveThenRewrite({
         .join('\n') + '\n';
     await mkdir(path.dirname(archivePath), { recursive: true });
     await appendFile(archivePath, body, 'utf8');
+    // Inbox receipts (#1516) for archived ids that came from the inbox: the
+    // archive is not synced to the inbox host, so without a receipt the record
+    // turns visible there again. Written AFTER the archive append (a crash
+    // cannot leave a receipt for a record that is neither live nor archived)
+    // and BEFORE the rewrite. A crash between the archive append and this
+    // receipt still leaves an archived inbox record without one; the next
+    // writer rewriteLearnings() heals it (io.mjs `unreceiptedArchivedIds`).
+    // Both callers hold the store lock here, as appendInboxReceipts requires.
+    await appendInboxReceipts(
+      filePath,
+      archiveBatch.map(({ entry }) => entry?.id)
+    );
   }
 
   // Re-validates (cheap, idempotent) and snapshots a `.bak-<ISO>` backup of
@@ -431,16 +485,24 @@ async function archiveThenRewrite({
  *   malformed?: number}>} `malformed` is present only when the store held
  *   unparseable lines: their count. They are kept verbatim at the end of the
  *   rewritten store, never archived, and not counted in `scanned`/`kept`.
- *   Never throws on a missing store — returns the zeroed shape instead. Both
+ *   Never throws on a missing store — returns the zeroed shape instead. An
+ *   apply on an `inbox`-role host (#1516) reads and writes nothing and returns
+ *   the zeroed shape plus `skipped: 'store-role-inbox'`. Both
  *   `filePath` and `archivePath` are required; a missing/invalid `filePath`
  *   throws a plain `Error` (programmer error, not a runtime data condition).
+ * @throws {LearningsStoreRoleError} an apply on the canonical store while the
+ *   host's store role is invalid (#1516) — nothing archived or rewritten
  */
 export async function sweepExpiredLearnings(opts = {}) {
   const { filePath, dryRun = true } = opts;
+  // Fail-closed (#1516): an apply under an invalid store role refuses before
+  // the archive append — archived-but-live records would follow otherwise.
+  if (!dryRun && typeof filePath === 'string') assertStoreRoleUsable(filePath);
   // The read → rewrite runs under the store lock (#1447 point 8). A run that
   // cannot write takes no lock: a dry run, an absent store (zeroed shape, see
   // below), or an unusable `filePath` (the body owns that error).
-  if (dryRun || typeof filePath !== 'string' || !existsSync(filePath)) {
+  // An inbox-role apply (#1516) writes nothing either — no lock.
+  if (dryRun || typeof filePath !== 'string' || !existsSync(filePath) || isInboxRoleStore(filePath)) {
     return sweepExpiredLearningsUnlocked(opts);
   }
   return withLearningsLock(filePath, () => sweepExpiredLearningsUnlocked(opts));
@@ -464,6 +526,13 @@ async function sweepExpiredLearningsUnlocked({
     throw new Error('sweepExpiredLearnings: archivePath is required');
   }
 
+  if (!dryRun && isInboxRoleStore(filePath)) {
+    // Inbox role (#1516): an expiry sweep is a pure removal, which this host
+    // never performs on the live store — the writer host sweeps. Zeroed counts
+    // so no caller reads "archived N"; `skipped` names why.
+    return { scanned: 0, kept: 0, archived: 0, dryRun, archivePath, skipped: SKIPPED_STORE_ROLE_INBOX };
+  }
+
   if (!existsSync(filePath)) {
     return { scanned: 0, kept: 0, archived: 0, dryRun, archivePath };
   }
@@ -575,11 +644,18 @@ async function sweepExpiredLearningsUnlocked({
  *   byReason: Record<string, number>, dryRun: boolean, archivePath: string,
  *   malformed?: number}>} `malformed` as in {@link sweepExpiredLearnings}: the
  *   store's unparseable lines, kept verbatim — no caller generation can carry
- *   them, so they are never read as caller drops.
+ *   them, so they are never read as caller drops. On an `inbox`-role host
+ *   (#1516) an apply archives nothing (`archived: 0`, `byReason: {}`) and adds
+ *   `skipped: 'store-role-inbox'`; its rewrite only appends the next
+ *   generation's new ids to `learnings-inbox.jsonl`.
  * @throws {StoreGenerationMismatchError} when `expectedGeneration` is stale
+ * @throws {LearningsStoreRoleError} an apply on the canonical store while the
+ *   host's store role is invalid (#1516) — nothing archived or rewritten
  */
 export async function pruneLearnings(opts = {}) {
   const { filePath, dryRun = true } = opts;
+  // Fail-closed (#1516): refuse before the archive append, see sweepExpiredLearnings.
+  if (!dryRun && typeof filePath === 'string') assertStoreRoleUsable(filePath);
   // The read → archive → rewrite runs under the store lock (#1447 point 8): an
   // append landing after the read below would otherwise vanish in the rename
   // with no archive line. A dry run writes nothing and takes no lock; an
@@ -722,7 +798,7 @@ async function pruneLearningsUnlocked({
     dropped += 1;
   }
 
-  const { kept, archived, byReason, malformedField: malformedCount } = await archiveThenRewrite({
+  const { kept, archived, byReason, malformedField: malformedCount, skipped } = await archiveThenRewrite({
     filePath,
     archivePath,
     keep,
@@ -741,6 +817,7 @@ async function pruneLearningsUnlocked({
     dryRun,
     archivePath,
     ...malformedCount,
+    ...(skipped ? { skipped } : {}),
   };
 }
 
@@ -842,8 +919,12 @@ function dropSnapshotPath(filePath, nowMs) {
  *   remainingMalformed: number, recordBearing: number, dryRun: boolean, snapshot: string|null}>}
  *   `generation` is the store's as read; `chars` the line's full length, `preview` its first
  *   {@link DROP_PREVIEW_CHARS} characters with the home dir as `~`; `recordBearing` counts the
- *   dropped lines that held a readable record
+ *   dropped lines that held a readable record. On an `inbox`-role host (#1516)
+ *   an apply writes nothing: it returns the dry-run result (`dryRun: true`,
+ *   `snapshot: null`) plus `skipped: 'store-role-inbox'`
  * @throws {StoreGenerationMismatchError} the store is not at `expectedGeneration` — nothing written
+ * @throws {LearningsStoreRoleError} an apply on the canonical store while the
+ *   host's store role is invalid (#1516) — nothing written
  * @throws {MalformedLineRefusedError} a line is not unparseable, or (apply without
  *   `acceptEmbedded`) still holds a readable record — nothing written
  */
@@ -864,6 +945,17 @@ export async function dropMalformedLines({
   if (!dryRun && (typeof expectedGeneration !== 'string' || expectedGeneration.length === 0)) {
     throw new Error('dropMalformedLines: expectedGeneration is required to apply');
   }
+  // Fail-closed (#1516): refuse before the snapshot and the rewrite.
+  if (!dryRun) assertStoreRoleUsable(filePath);
+  if (!dryRun && isInboxRoleStore(filePath)) {
+    // Inbox role (#1516): the live store is never rewritten on this host, so
+    // no snapshot and no rewrite. The checks still run (dry), so a stale
+    // generation or a wrong line still throws; the result says nothing moved.
+    const probe = await dropMalformedLinesUnlocked({
+      filePath, lines, expectedGeneration, acceptEmbedded, dryRun: true, now,
+    });
+    return { ...probe, skipped: SKIPPED_STORE_ROLE_INBOX };
+  }
   const run = () => dropMalformedLinesUnlocked({ filePath, lines, expectedGeneration, acceptEmbedded, dryRun, now });
   // An absent store has no line to drop — the body refuses without a lock.
   return dryRun || !existsSync(filePath) ? run() : withLearningsLock(filePath, run);