session-orchestrator 5.1.0 → 5.3.0

package/scripts/lib/skill-evolution/candidate-intake.mjs

@@ -6,10 +6,18 @@
  *   1. `/evolve` learnings (`.orchestrator/metrics/learnings.jsonl` records)
  *   2. `claude-md-drift-check` output (`driftResult.errors[]`)
  *
- * This module is a PURE transform: it performs NO I/O. It never reads or writes
- * any file. Persistence and the `processed_at` / `superseded_by` lifecycle are
- * OWNED BY the sibling `idempotency.mjs` module — this module only emits the
- * raw candidates with those fields nulled out.
+ * This module WRITES nothing. Its only read is target resolution for the
+ * learnings feeder: at most one `git ls-files` per `extractCandidates` call
+ * (lazy — only when a learning survives the cheaper filters), plus a
+ * `realpathSync` containment check that applies with or without git. A
+ * learning becomes a candidate only when its extracted path resolves — symlinks
+ * followed — to a regular file inside the realpath of `repoRoot` that is also
+ * the ONE tracked file it names (tracking is skipped when git is unavailable);
+ * the kept `target_path` is the repo-relative form of that resolved file, so a
+ * bare basename becomes its full path and `scripts/../x.mjs` becomes `x.mjs`. Persistence and
+ * the `processed_at` / `superseded_by` lifecycle are OWNED BY the sibling
+ * `idempotency.mjs` module — this module only emits the raw candidates with
+ * those fields nulled out.
  *
  * The `id` field is a deterministic short hash of (source, target_path,
  * fingerprint), so the same input always yields the same id. That determinism
@@ -18,7 +26,10 @@
  * Part of Epic #643 → issue #647 (C2 auto-repair engine).
  */
 
+import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
+import { realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
 
 /**
  * @typedef {Object} RepairCandidate
@@ -96,6 +107,104 @@ function extractPath(text) {
   return match ? match[0] : null;
 }
 
+/**
+ * Build the target resolver for ONE extraction run. `PATH_RE` also admits bare
+ * basenames (`engine.mjs`, `mcp.json`) that exist nowhere at the repo root, so
+ * an extracted path is a claim, not a target, until it resolves here.
+ *
+ * Resolution is fail-closed — `null` drops the candidate. In BOTH modes the
+ * path is resolved with `realpathSync` (every symlink followed) and must land
+ * on a regular file inside `realpathSync(repoRoot)`; any resolution error
+ * drops it. The kept `target_path` is the repo-relative POSIX form of that
+ * RESOLVED path, so `scripts/../CLAUDE.md` and `CLAUDE.md` name one target
+ * (and mint one id). Containment follows `classifyTarget` in
+ * `blast-radius-classifier.mjs`, plus the realpath of the target itself.
+ *
+ * With git, the resolved path must additionally be a tracked file:
+ *   - a path containing `/` is resolved as given;
+ *   - a bare basename must match exactly ONE tracked file (zero = unresolvable,
+ *     two or more = ambiguous) and is resolved from that file's full path.
+ * A tracked symlink whose target lies outside the repo is therefore dropped.
+ *
+ * The tracked-file index is read lazily and at most once per resolver
+ * (`git ls-files -z` in `repoRoot`), so a run without a qualifying learning
+ * never spawns git. Without git (binary missing, not a repository) only the
+ * realpath containment applies — a bare basename then resolves only at the
+ * root, since nothing enumerates the tree.
+ *
+ * @param {string} repoRoot
+ * @returns {(extracted: string) => string|null}
+ */
+function makeTargetResolver(repoRoot) {
+  /** @type {{ tracked: Set<string>, byBasename: Map<string, string[]> }|null|undefined} */
+  let index; // undefined = not read yet, null = git unavailable
+
+  // Canonicalise the root once, as blast-radius-classifier does: a symlinked
+  // repoRoot (macOS /var → /private/var) must still anchor the escape check.
+  let root;
+  try {
+    root = realpathSync(path.resolve(repoRoot));
+  } catch {
+    root = path.resolve(repoRoot);
+  }
+
+  function readIndex() {
+    try {
+      const out = execFileSync('git', ['ls-files', '-z'], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        maxBuffer: 64 * 1024 * 1024,
+      });
+      const tracked = new Set(out.split('\0').filter(Boolean));
+      /** @type {Map<string, string[]>} */
+      const byBasename = new Map();
+      for (const file of tracked) {
+        const base = file.slice(file.lastIndexOf('/') + 1);
+        const list = byBasename.get(base);
+        if (list) list.push(file);
+        else byBasename.set(base, [file]);
+      }
+      return { tracked, byBasename };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Realpath-resolve `rel` against the canonical root.
+   * @param {string} rel
+   * @returns {string|null} repo-relative POSIX path of the regular file it
+   *   resolves to, or null when it escapes the root, is not a regular file, or
+   *   does not resolve at all.
+   */
+  function resolveInsideRoot(rel) {
+    let real;
+    try {
+      real = realpathSync(path.resolve(root, rel));
+      if (!statSync(real).isFile()) return null;
+    } catch {
+      return null;
+    }
+    const back = path.relative(root, real);
+    if (back === '' || back.startsWith('..') || path.isAbsolute(back)) return null;
+    return back.split(path.sep).join('/');
+  }
+
+  return (extracted) => {
+    if (index === undefined) index = readIndex();
+    if (index === null) return resolveInsideRoot(extracted);
+    let candidate = extracted;
+    if (!extracted.includes('/')) {
+      const matches = index.byBasename.get(extracted) ?? [];
+      if (matches.length !== 1) return null;
+      candidate = matches[0];
+    }
+    const resolved = resolveInsideRoot(candidate);
+    return resolved !== null && index.tracked.has(resolved) ? resolved : null;
+  };
+}
+
 /**
  * Map a single learning record to a RepairCandidate, or null when it fails any
  * actionable filter. learnings.jsonl records are NOT uniform — only `confidence`
@@ -104,9 +213,10 @@ function extractPath(text) {
  * @param {Record<string, unknown>} learning
  * @param {number} evidenceFloor
  * @param {string} nowIso
+ * @param {(extracted: string) => string|null} resolveTarget
  * @returns {RepairCandidate|null}
  */
-function learningToCandidate(learning, evidenceFloor, nowIso) {
+function learningToCandidate(learning, evidenceFloor, nowIso, resolveTarget) {
   if (!learning || typeof learning !== 'object') return null;
 
   // Filter 1: confidence gate.
@@ -123,13 +233,18 @@ function learningToCandidate(learning, evidenceFloor, nowIso) {
   const subject = typeof learning.subject === 'string' ? learning.subject : '';
   const insight = typeof learning.insight === 'string' ? learning.insight : '';
 
-  // Filter 2: resolvable target path from subject OR insight.
-  const targetPath = extractPath(subject) ?? extractPath(insight);
-  if (!targetPath) return null;
+  // Filter 2: a path-shaped token in subject OR insight.
+  const extracted = extractPath(subject) ?? extractPath(insight);
+  if (!extracted) return null;
 
   // Filter 3: insight must be prescriptive.
   if (!PRESCRIPTIVE_RE.test(insight)) return null;
 
+  // Filter 5: the token resolves to exactly one tracked file (last — it is the
+  // only filter that may spawn git).
+  const targetPath = resolveTarget(extracted);
+  if (!targetPath) return null;
+
   const source = 'evolve-learning';
   const sourceRef = typeof learning.id === 'string' && learning.id.length > 0
     ? learning.id
@@ -218,7 +333,9 @@ function driftErrorToCandidate(err, nowIso) {
 
 /**
  * Ingest the two repair-candidate feeders and return a normalised
- * `RepairCandidate[]`. Pure transform — performs no I/O.
+ * `RepairCandidate[]`. Writes nothing; learnings are resolved against the files
+ * tracked in `repoRoot` (see `makeTargetResolver`). Drift errors pass through
+ * unresolved — the checker reported them from a file it read.
  *
  * @param {Object} params
  * @param {Array<Record<string, unknown>>} [params.learnings] - `/evolve` learning records.
@@ -226,7 +343,10 @@ function driftErrorToCandidate(err, nowIso) {
  *        claude-md-drift-check output. Only `errors[]` are mapped; `warnings[]`
  *        are skipped. A null result, or a status of `skipped`/`skipped-mode-off`/
  *        undefined, emits zero drift candidates.
- * @param {string} [params.repoRoot] - repo root (accepted for caller symmetry; unused in the pure transform).
+ * @param {string} [params.repoRoot] - repo root learning targets must resolve in
+ *        (default `process.cwd()`). A learning is dropped unless its extracted
+ *        path realpath-resolves to a regular file inside this root that is
+ *        exactly one tracked file there (tracking skipped without git).
  * @param {number} [params.evidenceFloor=0.5] - minimum learning confidence to qualify.
  * @param {string} [params.now] - ISO timestamp for `created_at` + expiry checks (test determinism).
  * @returns {RepairCandidate[]}
@@ -234,13 +354,14 @@ function driftErrorToCandidate(err, nowIso) {
 export function extractCandidates({
   learnings,
   driftResult,
-  // eslint-disable-next-line no-unused-vars -- accepted for caller symmetry; pure transform does no path resolution
   repoRoot,
   evidenceFloor = 0.5,
   now,
 } = {}) {
   const nowIso = typeof now === 'string' && now.length > 0 ? now : new Date().toISOString();
   const floor = Number.isFinite(evidenceFloor) ? evidenceFloor : 0.5;
+  const root = typeof repoRoot === 'string' && repoRoot.length > 0 ? repoRoot : process.cwd();
+  const resolveTarget = makeTargetResolver(root);
 
   /** @type {RepairCandidate[]} */
   const candidates = [];
@@ -248,7 +369,7 @@ export function extractCandidates({
   // Feeder 1: /evolve learnings.
   if (Array.isArray(learnings)) {
     for (const learning of learnings) {
-      const candidate = learningToCandidate(learning, floor, nowIso);
+      const candidate = learningToCandidate(learning, floor, nowIso, resolveTarget);
       if (candidate) candidates.push(candidate);
     }
   }

package/scripts/lib/skill-evolution/engine.mjs

@@ -8,7 +8,7 @@
  * — the matrix is the load-bearing deliverable, not the file-write mechanics.
  *
  * COMPOSITION (the five siblings, all DI-injectable via `opts`):
- *   - candidate-intake.mjs       → extractCandidates    (pure transform)
+ *   - candidate-intake.mjs       → extractCandidates    (no writes; resolves targets against repoRoot)
  *   - idempotency.mjs            → mergeCandidates / markProcessed / isProcessed
  *                                   / loadCandidates    (store I/O + supersession)
  *   - blast-radius-classifier.mjs→ classifyTarget       (R5 posture/gate triple)
@@ -17,7 +17,7 @@
  *
  * PIPELINE:
  *   extractCandidates(learnings, driftResult)
- *     → mergeCandidates (persist + supersede)
+ *     → mergeCandidates (persist + supersede; skipped under dryRun)
  *     → for each NON-processed candidate:
  *         classify → decide per matrix → act
  *
@@ -583,7 +583,8 @@ async function finishOpenMr({ candidate, candidateId, targetPath, targetType, re
  * @param {Array<Record<string, unknown>>} [params.learnings] — `/evolve` learning records.
  * @param {{ status?: string, errors?: Array<Record<string, unknown>> }|null} [params.driftResult]
  *        claude-md-drift-check output.
- * @param {boolean} [params.dryRun=false] — when true, no mutation/MR/stamp; previews only.
+ * @param {boolean} [params.dryRun=false] — when true, no mutation/MR/stamp and no
+ *        candidate-store write (the skip is logged via `opts.log`); previews only.
  * @param {Object} [opts] — DI seams (all default to the real sibling functions).
  * @param {typeof realExtractCandidates} [opts.extractCandidates]
  * @param {typeof realMergeCandidates} [opts.mergeCandidates]
@@ -629,7 +630,7 @@ export async function runRepairEngine(
   const outcomes = [];
   const summary = { autonomousApplied: 0, mrsOpened: 0, advisories: 0, blocked: 0, total: 0 };
 
-  // --- Pipeline step 1 — intake (pure transform) ---------------------------
+  // --- Pipeline step 1 — intake (no writes; repoRoot anchors target resolution)
   let candidates;
   try {
     candidates = seams.extractCandidates({
@@ -650,11 +651,19 @@ export async function runRepairEngine(
   }
 
   // --- Pipeline step 2 — merge (persist + supersede) -----------------------
-  try {
-    seams.mergeCandidates({ candidates, repoRoot });
-  } catch (err) {
-    seams.log('error', `engine: mergeCandidates threw — ${err?.message ?? err}`);
-    // Persistence failure is non-fatal: continue with the in-memory candidates.
+  // A dry run previews from the in-memory candidates and never writes the store.
+  if (dryRun === true) {
+    seams.log(
+      'info',
+      `engine: dry-run — candidate store write skipped (${candidates.length} candidate(s) not persisted)`,
+    );
+  } else {
+    try {
+      seams.mergeCandidates({ candidates, repoRoot });
+    } catch (err) {
+      seams.log('error', `engine: mergeCandidates threw — ${err?.message ?? err}`);
+      // Persistence failure is non-fatal: continue with the in-memory candidates.
+    }
   }
 
   // --- Pipeline step 3 — per-candidate classify → decide → act -------------

package/scripts/lib/skill-judge.mjs

@@ -31,6 +31,7 @@
  *  - estimateInputTokens(str)          — char-count/4 heuristic
  *  - checkBudget(estimated, budget)    — verdict for the budget gate
  *  - buildJudgePrompt(skills, tail, nonce) — pure prompt assembly (untrusted-data fence)
+ *  - evidenceBudgetChars(skills, budget)   — characters left for evidence after the prompt frame
  *  - parseJudgeResponse(text)          — extract one fenced ```json block, validate, drop malformed
  */
 
@@ -54,6 +55,9 @@ export const DEFAULT_BUDGET = Object.freeze({ input: 8000, output: 4000 });
 /** Industry-standard heuristic: ~4 chars per token for English prose. */
 const CHARS_PER_TOKEN = 4;
 
+/** Hex length of the per-call untrusted-data nonce (`randomBytes(16)` → 32 hex). */
+const NONCE_HEX_LENGTH = 32;
+
 // ---------------------------------------------------------------------------
 // Pure-function gates
 // ---------------------------------------------------------------------------
@@ -182,6 +186,25 @@ export function buildJudgePrompt(selectedSkills, transcriptTail, nonce) {
   ].join('\n');
 }
 
+/**
+ * How many characters of evidence fit inside `budget.input` for THIS judged set.
+ *
+ * The caller must not have to guess: the prompt frame is MEASURED by building
+ * the very prompt that will be sent with an empty fence, so the answer tracks
+ * every future edit to `buildJudgePrompt` automatically. The nonce is
+ * length-accurate (`NONCE_HEX_LENGTH`) rather than the real random value, since
+ * only its length affects the frame.
+ *
+ * @param {string[]} selectedSkills — the judged set (its JSON is part of the frame)
+ * @param {{input?: number}} [budget]
+ * @returns {number} characters available for `evidence.text` (never negative)
+ */
+export function evidenceBudgetChars(selectedSkills = [], budget = DEFAULT_BUDGET) {
+  const maxInput = typeof budget?.input === 'number' ? budget.input : DEFAULT_BUDGET.input;
+  const frame = buildJudgePrompt(selectedSkills, '', 'f'.repeat(NONCE_HEX_LENGTH)).length;
+  return Math.max(0, maxInput * CHARS_PER_TOKEN - frame);
+}
+
 /**
  * Parse the judge response into validated judgment records. Extracts the FIRST
  * fenced ```json block, JSON.parses it, and validates each entry against
@@ -253,7 +276,7 @@ export function parseJudgeResponse(text) {
 
 /**
  * @typedef {Object} JudgeResult
- * @property {'ok' | 'empty-input' | 'budget-exceeded'} status
+ * @property {'ok' | 'empty-input' | 'no-evidence' | 'budget-exceeded'} status
  * @property {Array<{skill: string, applied: string, completed: string, confidence: number}>} judgments
  * @property {{input_tokens?: number, output_tokens?: number, estimated_input?: number}} [usage]
  * @property {string} [skipped_reason]
@@ -269,6 +292,7 @@ export function parseJudgeResponse(text) {
  *
  * Control flow (matches the ratified #645 L3 contract):
  *   - empty selectedSkills → {status:'empty-input', judgments:[]} (no dispatch).
+ *   - empty evidence text  → {status:'no-evidence', judgments:[]} (no dispatch, #1399).
  *   - budget exceeded     → {status:'budget-exceeded', judgments:[]} (no dispatch,
  *                            NOT truncated — mirrors dialectic-deriver).
  *   - else → dispatch → parse → {status:'ok', judgments, usage}.
@@ -277,7 +301,8 @@ export function parseJudgeResponse(text) {
  * @param {(args: {model: string, prompt: string, maxTokens: number}) => Promise<{text: string, usage?: {input_tokens?: number, output_tokens?: number}}>} opts.dispatchAgent — REQUIRED, injected DI boundary
  * @param {string} [opts.repoRoot]
  * @param {string|null} [opts.sessionId]
- * @param {string} [opts.transcriptTail]
+ * @param {{text?: string}} [opts.evidence] — preferred input; `buildSkillEvidence()` output (#1399)
+ * @param {string} [opts.transcriptTail] — legacy raw-string input; used when `evidence` is absent
  * @param {string[]} [opts.selectedSkills]
  * @param {'haiku'|'sonnet'|'opus'} [opts.model='haiku']
  * @param {{input: number, output: number}} [opts.budget]
@@ -293,6 +318,7 @@ export async function runSkillJudge({
   // `_`-prefixed names so the contract keys stay documented without tripping no-unused-vars.
   repoRoot: _repoRoot,
   sessionId: _sessionId,
+  evidence,
   transcriptTail = '',
   selectedSkills = [],
   model = 'haiku',
@@ -313,8 +339,24 @@ export async function runSkillJudge({
     return { status: 'empty-input', judgments: [], skipped_reason: 'no-selected-skills' };
   }
 
+  // Gate 2b (#1399): empty evidence — do NOT dispatch. Measured 2026-09-19 at
+  // `8f15f77b`: a prompt whose fence is empty is 1387 chars = 346 estimated
+  // tokens, so the budget gate below waves it through and the judge is asked to
+  // rule on a transcript it was never shown. An advisory verdict from no
+  // evidence is worse than no verdict — it looks exactly like a real one in
+  // `skill-judgments.jsonl`.
+  const evidenceText =
+    typeof evidence?.text === 'string' && evidence.text.trim()
+      ? evidence.text
+      : typeof transcriptTail === 'string'
+        ? transcriptTail
+        : '';
+  if (!evidenceText.trim()) {
+    return { status: 'no-evidence', judgments: [], skipped_reason: 'empty-transcript-evidence' };
+  }
+
   const nonce = randomNonce();
-  const prompt = buildJudgePrompt(skills, transcriptTail, nonce);
+  const prompt = buildJudgePrompt(skills, evidenceText, nonce);
 
   // Gate 3: budget — fail-fast BEFORE dispatch when the prompt would exceed it.
   const estimatedInput = estimateInputTokens(prompt);

package/scripts/lib/state-md.mjs

@@ -10,13 +10,15 @@
  * @see scripts/lib/state-md/mission-status.mjs      parseMissionStatus, parseMissionStatusStrict, MISSION_STATUS_VALUES, writeMissionStatus, setMissionStatus, setMissionStatusDetailed, readMissionStatus, recoverFrontmatterMissionStatusDetailed, writeMissionStatusOnDisk, setMissionStatusOnDisk
  * @see scripts/lib/state-md/recommendations.mjs     parseRecommendations
  *
- * Plus ONE small non-re-export surface: the `session-profile` frontmatter
- * accessors at the bottom of this file (see their docblock for why they are
- * composed here rather than added as a fourth mutator module).
+ * Plus TWO small non-re-export surfaces at the bottom of this file (each with
+ * its own docblock explaining why it is composed here rather than added as a
+ * fourth mutator module): the `session-profile` frontmatter accessors, and the
+ * `started_at` / `session-id` frontmatter SOURCES (#1368).
  */
 
 import { parseStateMd as _parseStateMd } from './state-md/yaml-parser.mjs';
 import { updateFrontmatterFields as _updateFrontmatterFields } from './state-md/frontmatter-mutators.mjs';
+import { readLock as _readLock } from './session-lock.mjs';
 
 export { parseStateMd, serializeStateMd } from './state-md/yaml-parser.mjs';
 
@@ -140,3 +142,82 @@ export function setSessionProfile(contents, profile) {
     [SESSION_PROFILE_FIELD]: profile === null ? null : profile.trim(),
   });
 }
+
+// ---------------------------------------------------------------------------
+// STATE.md frontmatter SOURCES (#1368) — `started_at` / `session-id`.
+//
+// These two helpers exist because the frontmatter they feed is written by the
+// coordinator LLM from prose, and prose with no named source gets written from
+// `new Date()` at WRITE time. `started_at` then names the moment STATE.md was
+// created, not the moment the session began — measured 2026-09-13: 48 minutes
+// apart. Every other producer of that timestamp (the lock's own `started_at`,
+// `orchestrator.session.lock.acquired`, `orchestrator.session.started`) agrees
+// within 1 ms, because all three descend from `buildLock()`. So the lock is
+// the source, and these functions are how the template cites it.
+//
+// They live in this barrel rather than in `state-md/`: the barrel is the
+// documented entry point for STATE.md work, and the edge barrel → session-lock
+// already exists (state-md/frontmatter-mutators.mjs imports `withStateMdLock`
+// from it), so no cycle is created — session-lock.mjs imports nothing from
+// this module or its submodules.
+// ---------------------------------------------------------------------------
+
+/**
+ * The canonical `started_at` for a STATE.md written during THIS session.
+ *
+ * Returns the live lock's `started_at`, normalised to ISO-8601 UTC ("Z"), so
+ * STATE.md, the lock, both lock events and the ledger all name the SAME
+ * instant. Falls back to `new Date().toISOString()` ONLY when no usable lock
+ * exists — a missing lock means `persistence: false`, a lock that could not be
+ * acquired, or a corrupt lock file, and in all three the writer has no better
+ * source than the present moment. The fallback is deliberately silent: it is a
+ * degradation of PRECISION, not a failure.
+ *
+ * Never throws.
+ *
+ * @param {{ repoRoot?: string }} [opts]
+ * @returns {string} ISO-8601 UTC timestamp.
+ */
+export function resolveSessionStartedAt({ repoRoot } = {}) {
+  try {
+    const lock = _readLock({ repoRoot });
+    const raw = lock?.started_at;
+    if (typeof raw === 'string' && raw.length > 0) {
+      const ms = Date.parse(raw);
+      if (Number.isFinite(ms)) return new Date(ms).toISOString();
+    }
+  } catch {
+    /* readLock is no-throw by contract; the contract is not ours to trust */
+  }
+  return new Date().toISOString();
+}
+
+/**
+ * The session ids a STATE.md writer may stamp into frontmatter: `session-id`
+ * (the RAW/native harness id) and `session` (the semantic attribution label),
+ * both read from the live lock.
+ *
+ * Both fields are `null` when no usable lock exists — ABSENCE IS NEVER
+ * COERCED, and a writer must then OMIT the key rather than write a
+ * placeholder. Neither id grants ownership of anything (see
+ * `skills/_shared/state-ownership.md`); `session-id` exists so `/close`'s #429
+ * pre-check can join STATE.md to sessions.jsonl on a native identity instead
+ * of falling through to the label + timestamp path.
+ *
+ * Never throws.
+ *
+ * @param {{ repoRoot?: string }} [opts]
+ * @returns {{ session_id: string|null, semantic_session_id: string|null }}
+ */
+export function resolveSessionIds({ repoRoot } = {}) {
+  const pick = (value) => (typeof value === 'string' && value.trim().length > 0 ? value.trim() : null);
+  try {
+    const lock = _readLock({ repoRoot });
+    return {
+      session_id: pick(lock?.session_id),
+      semantic_session_id: pick(lock?.semantic_session_id),
+    };
+  } catch {
+    return { session_id: null, semantic_session_id: null };
+  }
+}

package/scripts/lib/sunset/walker.mjs

@@ -39,9 +39,10 @@
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { normalizeSkillInvocation } from '../skill-invocations-schema.mjs';
 import { normalizeSkillJudgment } from '../skill-judgments-schema.mjs';
+import { isMainModule } from '../is-main-module.mjs';
+import { userInvocableSkills } from '../user-invocable-skills.mjs';
 
 // ---------------------------------------------------------------------------
 // Named threshold constants
@@ -602,6 +603,16 @@ export function staticReferenceScan(repoRoot, { kind, name }) {
  * Parse commands/*.md for the skill each command invokes. Recognises the
  * conventional `skills/<name>/SKILL.md` reference inside a command file.
  *
+ * NOTE since the 2026-09-16 command→skill fold (#1370): this linkage now covers
+ * almost nothing. `commands/` holds two files (`session`, `templates-ack`), so
+ * `skillToCommands` is near-empty by construction — the operator entry point for
+ * every other slash command is an explicit `user-invocable: true` in the skill's
+ * own frontmatter, not a command file pointing at it. `runSunsetWalk` therefore
+ * threads that flag alongside this linkage, and `classifyItem` treats the two as
+ * equivalent evidence of "an operator can invoke this directly". Without that, 26
+ * live slash commands would have been demoted the day their command file was
+ * deleted, for a reason that is a rename, not a disuse signal.
+ *
  * @param {string} repoRoot
  * @returns {{commandToSkill: Map<string,string|null>, skillToCommands: Map<string,string[]>}}
  */
@@ -772,6 +783,11 @@ export function classifyItem({
   const strictRefs = staticRefs.strictRefs;
   const nonBoilerplateRefs = staticRefs.nonBoilerplateRefs;
   const invokedByCommands = linkage?.invokedByCommands ?? [];
+  // #1370 fold: an explicit `user-invocable: true` in SKILL.md frontmatter is the
+  // post-fold form of "an operator invokes this directly" — the same evidence a
+  // command file used to carry. Default false so older callers/tests that do not
+  // thread it behave exactly as before.
+  const userInvocable = linkage?.userInvocable === true;
   const invokesSkill = linkage?.invokesSkill ?? null;
   // When a command invokes a skill, the caller passes whether that skill is
   // present on disk. Default-true so callers that don't thread the surface set
@@ -786,6 +802,7 @@ export function classifyItem({
     proseRefs,
     nonBoilerplateRefs,
     invokedByCommands,
+    userInvocable,
     invokesSkill,
     invokedSkillExists,
     lowConfidence,
@@ -842,6 +859,10 @@ export function classifyItem({
     active = true;
     reasons.push(`skill invoked by command(s): ${invokedByCommands.join(', ')}`);
   }
+  if (kind === 'skill' && userInvocable) {
+    active = true;
+    reasons.push('skill is an operator-facing slash command (user-invocable: true)');
+  }
   if (kind === 'command' && invokesSkill && invokedSkillExists) {
     active = true;
     reasons.push(`command invokes live skill: ${invokesSkill}`);
@@ -878,7 +899,10 @@ export function classifyItem({
 
   // --- Demote (near-zero) — skills & commands (agents handled above) ---------
   const lonelySkill =
-    kind === 'skill' && nonBoilerplateRefs <= 1 && invokedByCommands.length === 0;
+    kind === 'skill' &&
+    nonBoilerplateRefs <= 1 &&
+    invokedByCommands.length === 0 &&
+    !userInvocable;
   const lonelyCommand =
     kind === 'command' && !invokesSkill && nonBoilerplateRefs <= 1;
   if (lonelySkill || lonelyCommand) {
@@ -942,6 +966,9 @@ export function runSunsetWalk(repoRoot, opts = {}) {
   // classification below behaves byte-for-byte identically to the L1-only path.
   const skillJudgments = readSkillJudgmentCounts(judgmentsPath, { windowDays, now: nowMs });
   const linkage = commandSkillLinkage(repoRoot);
+  // Post-#1370 replacement for the command→skill linkage as an operator-entry
+  // signal (see commandSkillLinkage's note). Read once per walk, not per skill.
+  const userInvocableSet = new Set(userInvocableSkills(repoRoot));
   const coverageDays = dispatch.coverageDays;
   const lowConfidence = coverageDays < windowDays;
 
@@ -967,7 +994,7 @@ export function runSunsetWalk(repoRoot, opts = {}) {
           name,
           dispatch: skillDispatch,
           static: staticRefs,
-          linkage: { invokedByCommands },
+          linkage: { invokedByCommands, userInvocable: userInvocableSet.has(name) },
           windowDays,
           coverageDays,
           judge,
@@ -1192,7 +1219,7 @@ function main(argv) {
 }
 
 // Import-safe main-guard.
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+if (isMainModule(import.meta.url)) {
   const code = main(process.argv.slice(2));
   process.exit(code);
 }

package/scripts/lib/tail-window.mjs

@@ -0,0 +1,56 @@
+/**
+ * tail-window.mjs — the ONE bounded tail-window reader for append-only JSONL
+ * ledgers and transcripts (#1272).
+ *
+ * Five call sites used to carry their own copy of this byte-window primitive,
+ * and one of them (hooks/subagent-telemetry.mjs) ignored the returned read
+ * length and decoded a whole `allocUnsafe` buffer — on a short read that is
+ * uninitialised memory handed to JSON.parse. This module owns ONLY the byte
+ * window; every caller keeps its own error mapping (null / [] / discriminated
+ * result / throw) and its own line logic.
+ *
+ * Ceiling: the whole window is held in memory at once and decoded in one pass
+ * — fine for the windows in use today (64 KiB .. 1 MiB). Revisit if a caller
+ * needs a window above ~16 MiB: stream backwards in chunks instead.
+ */
+
+import fs from 'node:fs';
+
+/**
+ * Read the last `maxBytes` of `file` as UTF-8.
+ *
+ * `cut` is true when the window did not start at byte 0 — the first line of
+ * `text` is then (or may be) a fragment of a record, possibly starting inside
+ * a multi-byte UTF-8 sequence, and callers that parse lines should drop it.
+ * Loops until the window is filled or the file reports EOF, so a short read
+ * never leaves undecoded buffer bytes in `text`.
+ *
+ * THROWS on any fs error (ENOENT, EACCES, …) — mapping the failure is the
+ * caller's decision.
+ *
+ * @param {string} file
+ * @param {number} maxBytes  window size in bytes (> 0)
+ * @returns {{ text: string, cut: boolean, size: number }}  `size` is the file size at open time
+ */
+export function readTailWindow(file, maxBytes) {
+  const fd = fs.openSync(file, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    const want = Math.min(size, maxBytes);
+    const start = size - want;
+    const buf = Buffer.allocUnsafe(want);
+    let read = 0;
+    while (read < want) {
+      const n = fs.readSync(fd, buf, read, want - read, start + read);
+      if (n <= 0) break;
+      read += n;
+    }
+    return { text: buf.subarray(0, read).toString('utf8'), cut: start > 0, size };
+  } finally {
+    try {
+      fs.closeSync(fd);
+    } catch {
+      /* best-effort */
+    }
+  }
+}