session-orchestrator 5.2.0 → 5.4.0

package/skills/navigator/references/fleet-decisions.mjs

@@ -0,0 +1,231 @@
+/**
+ * skills/navigator/references/fleet-decisions.mjs
+ *
+ * Pure decision functions for the navigator's headless fleet: whether a new
+ * headless run may start on this host (slot gate), whether a target repo is
+ * already occupied by another session (busy gate), and which account the host
+ * should run on (account watch).
+ *
+ * Measurement lives elsewhere — `slot-check.sh` and `account-check.sh` in this
+ * directory collect the raw numbers and pipe them in here. This module reads
+ * no environment variables, no files and no clock except the `now` argument,
+ * so every rule below is testable with plain values.
+ *
+ * Shared principle: a value that could not be measured is never read as
+ * "free". Every gate fails closed on missing, NaN or non-number input; only
+ * an explicit `override: true` (an owner decision) bypasses a gate.
+ *
+ * Slot gate thresholds (free memory % from the OS pressure verdict):
+ *   free >= 50  → cap 4
+ *   free >= 35  → cap 3
+ *   otherwise   → cap 0
+ *   load1 > 40  → cap 0 regardless of memory
+ *   allowed     = runs < cap
+ *
+ * Busy gate: busy when any Codex rollout for the repo is younger than 30 min
+ * or any `session.lock` is younger than 6 h (counts measured by the caller).
+ *
+ * Account watch: usable = 5-hour and 7-day usage both below 97 %. Among usable
+ * rows the earliest 7-day reset within 3 days wins (tie-break lower 7-day
+ * usage); if none is that near, the lowest 7-day usage wins. The active row is
+ * kept when its reset lies within 1800 s of the target's, either side (same
+ * reset, no flapping). A reset date in the past is stale data and the row is
+ * skipped. Rows are identified by `slot` only — the alias never reaches the
+ * output (SEC-008).
+ *
+ * CLI: `node fleet-decisions.mjs slot|busy|account` reads one JSON document
+ * from stdin and prints the decision as one JSON line.
+ *   exit 0 — allowed / not busy / stay or switch
+ *   exit 1 — refused / busy / no usable account
+ *   exit 2 — unparseable input or unknown subcommand
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const FREE_PCT_CAP4 = 50;
+const FREE_PCT_CAP3 = 35;
+const LOAD1_MAX = 40;
+const USAGE_LIMIT_PCT = 97;
+const NEAR_RESET_MS = 3 * 24 * 60 * 60 * 1000;
+const RESET_TIE_MS = 1800 * 1000;
+
+/** @param {unknown} v @returns {v is number} */
+function isNum(v) {
+  return typeof v === 'number' && Number.isFinite(v);
+}
+
+// ---------------------------------------------------------------------------
+// Slot gate
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide whether one more headless run may start on this host.
+ *
+ * @param {{ freePct?: unknown, load1?: unknown, runs?: unknown, override?: unknown }} input
+ * @returns {{ allowed: boolean, cap: number, reason: string }}
+ */
+export function slotDecision({ freePct, load1, runs, override } = {}) {
+  const memOk = isNum(freePct);
+  const loadOk = isNum(load1);
+  let cap = 0;
+  if (memOk && loadOk) {
+    if (freePct >= FREE_PCT_CAP4) cap = 4;
+    else if (freePct >= FREE_PCT_CAP3) cap = 3;
+    if (load1 > LOAD1_MAX) cap = 0;
+  }
+  if (override === true) return { allowed: true, cap, reason: 'override' };
+
+  const ctx = `(free ${memOk ? `${freePct}%` : '?'}, load1 ${loadOk ? load1 : '?'})`;
+  if (!memOk) return { allowed: false, cap: 0, reason: `no slot: free memory not measurable ${ctx}` };
+  if (!loadOk) return { allowed: false, cap: 0, reason: `no slot: load1 not measurable ${ctx}` };
+  if (!isNum(runs) || !Number.isInteger(runs) || runs < 0) {
+    return { allowed: false, cap, reason: `no slot: run count not measurable ${ctx}` };
+  }
+  const allowed = runs < cap;
+  return { allowed, cap, reason: `${allowed ? 'slot free' : 'no slot'}: ${runs} runs, cap ${cap} ${ctx}` };
+}
+
+// ---------------------------------------------------------------------------
+// Busy gate
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide whether a repo is occupied by another session.
+ *
+ * @param {{ codexRolloutsFresh?: unknown, lockFresh?: unknown, override?: unknown }} input
+ * @returns {{ busy: boolean, reason: string }}
+ */
+export function busyDecision({ codexRolloutsFresh, lockFresh, override } = {}) {
+  if (override === true) return { busy: false, reason: 'override' };
+  const valid = (v) => isNum(v) && v >= 0;
+  if (!valid(codexRolloutsFresh) || !valid(lockFresh)) {
+    return { busy: true, reason: 'busy: occupancy not measurable (codex rollouts or session.lock count missing)' };
+  }
+  const counts = `${codexRolloutsFresh} codex rollouts (30 min), ${lockFresh} session.lock (6 h)`;
+  if (codexRolloutsFresh > 0 || lockFresh > 0) return { busy: true, reason: `busy: ${counts}` };
+  return { busy: false, reason: `free: ${counts}` };
+}
+
+// ---------------------------------------------------------------------------
+// Account watch
+// ---------------------------------------------------------------------------
+
+/**
+ * Reduce one raw account row to the fields the decision needs, or null when it
+ * is not measurable. Copies nothing else — in particular not the alias. Never
+ * throws: a hostile row (throwing getter, proxy) counts as not measurable.
+ *
+ * @param {unknown} r
+ * @param {number} nowMs
+ * @returns {{ id: string|number, active: boolean, p7: number, p5: number, resetMs: number } | null}
+ */
+function parseAccountRow(r, nowMs) {
+  try {
+    if (!r || typeof r !== 'object') return null;
+    const { slot, active, p7, p5, resetAt } = /** @type {Record<string, unknown>} */ (r);
+    const slotOk = (typeof slot === 'string' && slot !== '') || isNum(slot);
+    const resetMs = typeof resetAt === 'string' ? Date.parse(resetAt) : NaN;
+    if (!slotOk || !isNum(p7) || !isNum(p5) || !Number.isFinite(resetMs) || resetMs < nowMs) return null;
+    return { id: /** @type {string|number} */ (slot), active: active === true, p7, p5, resetMs };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pick the account the host should run on. Never throws; malformed rows
+ * (non-string/non-number slot, missing usage, unparseable or past reset) are
+ * skipped and counted in the reason. The output carries the slot only, never
+ * the alias (SEC-008).
+ *
+ * @param {Array<{ slot: unknown, alias?: string, active: boolean, p7: number|null, p5: number|null, resetAt: string|null }>} rows
+ * @param {Date|number} now
+ * @returns {{ action: 'stay'|'switch'|'none', target: string|number|null, reason: string }}
+ */
+export function chooseAccount(rows, now) {
+  const nowMs = now instanceof Date ? now.getTime() : Number(now);
+  if (!Number.isFinite(nowMs)) return { action: 'none', target: null, reason: 'no decision: now is not a valid time' };
+  const list = Array.isArray(rows) ? rows : [];
+
+  let skipped = 0;
+  const parsed = [];
+  for (const r of list) {
+    const row = parseAccountRow(r, nowMs);
+    if (row === null) skipped += 1;
+    else parsed.push(row);
+  }
+  const skipNote = skipped > 0 ? `; ${skipped} row(s) skipped without data` : '';
+
+  const usable = parsed.filter((r) => r.p5 < USAGE_LIMIT_PCT && r.p7 < USAGE_LIMIT_PCT);
+  const active = parsed.find((r) => r.active === true) ?? null;
+  const activeUsable = active !== null && usable.includes(active);
+
+  if (usable.length === 0) {
+    return { action: 'none', target: null, reason: `no usable account (all >= ${USAGE_LIMIT_PCT}% or without data)${skipNote}` };
+  }
+
+  const near = usable.filter((r) => r.resetMs - nowMs <= NEAR_RESET_MS);
+  let target;
+  if (near.length > 0) {
+    target = near.reduce((a, b) => (b.resetMs < a.resetMs || (b.resetMs === a.resetMs && b.p7 < a.p7) ? b : a));
+  } else {
+    target = usable.reduce((a, b) => (b.p7 < a.p7 ? b : a));
+  }
+
+  if (activeUsable && active !== target && Math.abs(active.resetMs - target.resetMs) <= RESET_TIE_MS) {
+    target = active;
+  }
+
+  const desc = (r) => `${r.id} (7d ${r.p7}%, reset in ${((r.resetMs - nowMs) / 86400000).toFixed(1)} d)`;
+  if (active === target) return { action: 'stay', target: target.id, reason: `stay on ${desc(target)}${skipNote}` };
+  return {
+    action: 'switch',
+    target: target.id,
+    reason: `switch ${active ? active.id : '-'} -> ${desc(target)}${skipNote}`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function runCli(argv) {
+  const mode = argv[2];
+  if (mode !== 'slot' && mode !== 'busy' && mode !== 'account') {
+    process.stderr.write('usage: node fleet-decisions.mjs slot|busy|account < input.json\n');
+    return 2;
+  }
+  let input;
+  try {
+    input = JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    process.stderr.write('fleet-decisions: stdin is not valid JSON\n');
+    return 2;
+  }
+  if (mode === 'slot' || mode === 'busy') {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+      process.stderr.write(`fleet-decisions: ${mode} expects one JSON object\n`);
+      return 2;
+    }
+    const d = mode === 'slot' ? slotDecision(input) : busyDecision(input);
+    process.stdout.write(`${JSON.stringify(d)}\n`);
+    return mode === 'slot' ? (d.allowed ? 0 : 1) : d.busy ? 1 : 0;
+  }
+  const rows = Array.isArray(input) ? input : input && Array.isArray(input.accounts) ? input.accounts : null;
+  if (!rows) {
+    process.stderr.write('fleet-decisions: account expects a JSON array or {"accounts": [...]}\n');
+    return 2;
+  }
+  const d = chooseAccount(rows, Date.now());
+  process.stdout.write(`${JSON.stringify(d)}\n`);
+  return d.action === 'none' ? 1 : 0;
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  process.exitCode = runCli(process.argv);
+}

package/skills/navigator/references/slot-check.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# slot-check.sh — measure the slot gate and the busy gate for one repo, decide via fleet-decisions.mjs.
+#
+# Usage: slot-check.sh <repo-path>
+#
+# Measures only; every rule lives in fleet-decisions.mjs next to this file.
+#   slot gate: free memory % (memory_pressure), 1-min load (vm.loadavg, integer),
+#              running headless runs (`timeout -k 60 <n>[smhd] claude -p` + `... codex exec`);
+#              anchored on the timeout wrapper because one Codex run spawns three processes matching `codex exec`
+#   busy gate: Codex rollouts for <repo-path> younger than 30 min, <repo-path>/.orchestrator/session.lock
+#              younger than 6 h
+# A value that cannot be measured is passed as null; the decision module fails closed on it.
+#
+# Env:
+#   NAVIGATOR_CODEX_HOME  Codex home directory (default: $HOME/.codex; empty/whitespace = unset)
+#   FLEET_SLOT_OVERRIDE=1 owner override for the slot gate
+#   FLEET_BUSY_OVERRIDE=1 owner override for the busy gate
+#
+# Exit: 0 both gates pass, 1 at least one gate refuses, 2 usage error.
+set -u
+
+if [ "$#" -ne 1 ] || [ -z "$1" ]; then
+  echo "usage: slot-check.sh <repo-path>" >&2
+  exit 2
+fi
+repo=${1%/}
+here=$(cd "$(dirname "$0")" && pwd)
+decide="$here/fleet-decisions.mjs"
+
+# Trim leading/trailing whitespace; a whitespace-only value counts as unset.
+trim() {
+  local v=$1
+  v=${v#"${v%%[![:space:]]*}"}
+  v=${v%"${v##*[![:space:]]}"}
+  printf '%s' "$v"
+}
+codex_home=$(trim "${NAVIGATOR_CODEX_HOME:-}")
+[ -n "$codex_home" ] || codex_home=$HOME/.codex
+
+# Rollouts record the cwd as the session saw it; match both the logical and the physical path.
+repo_abs=$(cd "$repo" 2>/dev/null && pwd)
+repo_phys=$(cd "$repo" 2>/dev/null && pwd -P)
+
+# Print the argument if it is a non-negative integer, else the JSON literal null.
+num_or_null() {
+  case "$1" in
+    ''|*[!0-9]*) printf 'null' ;;
+    *) printf '%s' "$1" ;;
+  esac
+}
+
+# --- slot gate measurements ---------------------------------------------------
+free_pct=$(memory_pressure 2>/dev/null | awk '/free percentage/{gsub("%","",$NF); print $NF}')
+load1=$(sysctl -n vm.loadavg 2>/dev/null | awk '{print int($2)}')
+# Count pgrep matches: rc 0 → count, rc 1 → 0 (no match), rc >= 2 → empty (not measurable).
+count_runs() {
+  local out rc
+  out=$(pgrep -f "$1")
+  rc=$?
+  case "$rc" in
+    0) printf '%s' "$out" | grep -c . ;;
+    1) printf '0' ;;
+    *) printf '' ;;
+  esac
+}
+runs=''
+if command -v pgrep >/dev/null 2>&1; then
+  claude_runs=$(count_runs '^timeout -k 60 [0-9]+[smhd]? claude -p')
+  codex_runs=$(count_runs '^timeout -k 60 [0-9]+[smhd]? codex exec')
+  if [ -n "$claude_runs" ] && [ -n "$codex_runs" ]; then
+    runs=$((claude_runs + codex_runs))
+  fi
+fi
+
+# --- busy gate measurements ---------------------------------------------------
+# Only the first line of each rollout is matched, as a fixed string; file content is never evaluated.
+if [ -z "$repo_abs" ] || [ -z "$repo_phys" ]; then
+  # Repo path not resolvable: both busy counts are unknown, the decision fails closed.
+  codex_fresh=''
+  lock_fresh=''
+else
+  codex_fresh=0
+  if [ -d "$codex_home/sessions" ]; then
+    codex_fresh=$(find "$codex_home/sessions" -name 'rollout-*.jsonl' -mmin -30 2>/dev/null |
+      while IFS= read -r f; do
+        head -1 "$f" 2>/dev/null |
+          grep -qF -e "\"cwd\":\"$repo_abs\"" -e "\"cwd\":\"$repo_phys\"" && echo x
+      done | wc -l | tr -d ' ')
+  fi
+  lock_fresh=$(find "$repo_abs/.orchestrator" -maxdepth 1 -name session.lock -mmin -360 2>/dev/null | wc -l | tr -d ' ')
+fi
+
+slot_override=false
+[ "${FLEET_SLOT_OVERRIDE:-0}" = 1 ] && slot_override=true
+busy_override=false
+[ "${FLEET_BUSY_OVERRIDE:-0}" = 1 ] && busy_override=true
+
+slot_json=$(printf '{"freePct":%s,"load1":%s,"runs":%s,"override":%s}' \
+  "$(num_or_null "$free_pct")" "$(num_or_null "$load1")" "$(num_or_null "$runs")" "$slot_override")
+busy_json=$(printf '{"codexRolloutsFresh":%s,"lockFresh":%s,"override":%s}' \
+  "$(num_or_null "$codex_fresh")" "$(num_or_null "$lock_fresh")" "$busy_override")
+
+slot_out=$(printf '%s' "$slot_json" | node "$decide" slot)
+slot_rc=$?
+busy_out=$(printf '%s' "$busy_json" | node "$decide" busy)
+busy_rc=$?
+
+echo "slot: $slot_out"
+echo "busy: $busy_out"
+
+if [ "$slot_rc" -ne 0 ] || [ "$busy_rc" -ne 0 ]; then
+  exit 1
+fi
+exit 0

package/skills/npm-publish/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: npm-publish
-user-invocable: true
+user-invocable: false
 model: sonnet
 description: Use when publishing this package to npm — a version release (npm publish), verifying the registry/pi.dev listing, or diagnosing npm auth failures (E403 2FA/token errors). Token-based flow via NPM_TOKEN in .env.local with a temp userconfig, the leakage gate before every publish, post-publish verification and marker/badge upkeep. Trigger on "publish to npm", "npm release", "E403 publish error".
 ---

package/skills/persona-panel/SKILL.md

@@ -184,8 +184,8 @@ Dispatch one Agent per persona from the active catalog set.
 
 **Model selection per persona:**
 - If `persona.model` is a full Claude model ID (`MODEL_ID_RE`): use it as-is.
-- If `persona.model` is `opus` or unset AND `persona.tier == 'domain-expert'`: override to
-  `claude-opus-4-7` (empirically validated — Opus finds real problems Sonnet misses; see vault
+- If `persona.model` is `opus` or unset AND `persona.tier == 'domain-expert'`: use the alias
+  `opus`, which tracks the current Opus — pin a full ID only for a named reproducibility need (empirically validated — Opus finds real problems Sonnet misses; see vault
   learning `[[persona-opus-finds-real-failing-cibadge]]`).
 - Otherwise: use the persona's declared model alias.
 

package/skills/persona-panel/persona-format.md

@@ -28,7 +28,7 @@ name: ai-expert
 schema_version: 1
 version: "2"
 role: "AI/ML domain expert — evaluates technical accuracy and implementation quality"
-model: claude-opus-4-7
+model: opus
 tier: domain-expert
 output_contract:
   type: object
@@ -59,7 +59,7 @@ evaluation_criteria:
 | `schema_version` | integer | Must be `1`. |
 | `version` | string | Non-empty string. Persona content version. Increment on any output-affecting change. Used in sidecar + trend-tracking (#459). |
 | `role` | string | Identity statement. Injected verbatim as prompt opener. Keep under 200 chars. |
-| `model` | string | Full model ID (`MODEL_ID_RE`) or alias (`inherit|sonnet|opus|haiku`). Validated at load time. Recommend `claude-opus-4-7` for `domain-expert` and `compliance` tiers (Opus finds real issues Sonnet misses — vault learning `[[persona-opus-finds-real-failing-cibadge]]`). |
+| `model` | string | Full model ID (`MODEL_ID_RE`) or alias (`inherit|sonnet|opus|haiku`). Validated at load time. Recommend the Opus tier via alias `opus` for `domain-expert` and `compliance` tiers (Opus finds real issues Sonnet misses — vault learning `[[persona-opus-finds-real-failing-cibadge]]`); the alias tracks the current Opus; pin a full model ID only for a named reproducibility need, and name the reason. |
 | `output_contract` | object | Inline JSON Schema Draft 2020-12. `$ref/$defs/allOf/anyOf` FORBIDDEN (H3). Must require `verdict` + `rationale`. AJV compile wrapped in 2s AbortSignal timeout. |
 | `evaluation_criteria` | array | Non-empty. Each string max 512 chars. Injected wrapped in `<persona-criteria>` delimiters (M1). Write as statements, not questions. |
 | `tier` | enum | `domain-expert` \| `buyer-persona` \| `auditor` \| `compliance` \| `reviewer` \| `custom`. Affects model selection (Phase 3). |

package/skills/persona-panel/presets/designer-lens.md

@@ -3,7 +3,7 @@ name: designer-lens
 schema_version: 1
 version: "1"
 role: "Designer lens — evaluates interaction flow, cognitive load, consistency, and accessibility"
-model: claude-opus-4-7
+model: opus
 tier: domain-expert
 evaluation_criteria:
   - "The interaction flow is legible on first encounter — a new user can predict what happens next without hidden state."

package/skills/persona-panel/presets/engineer-lens.md

@@ -3,7 +3,7 @@ name: engineer-lens
 schema_version: 1
 version: "1"
 role: "Engineer lens — evaluates feasibility, complexity, failure modes, and long-term maintainability"
-model: claude-opus-4-7
+model: opus
 tier: domain-expert
 evaluation_criteria:
   - "Failure modes are enumerated — what breaks under load, bad input, or partial failure, and how the system responds."

package/skills/persona-panel/presets/pm-lens.md

@@ -3,7 +3,7 @@ name: pm-lens
 schema_version: 1
 version: "1"
 role: "Product Manager lens — evaluates user value, outcome-metric clarity, and scope discipline"
-model: claude-opus-4-7
+model: opus
 tier: domain-expert
 evaluation_criteria:
   - "The change is tied to a specific, named user or business problem — not a solution in search of one."

package/skills/plan/mode-retro.md

@@ -236,10 +236,11 @@ If issues were created and a 5+-action Epic wrapper was used (see `SKILL.md` §
 
 ### 3.3 Update Learnings
 
-Append new patterns to `.orchestrator/metrics/learnings.jsonl`. Use the same JSONL schema as session-end writes (see session-end/SKILL.md for canonical field reference):
+Collect new patterns as learning objects in the same strict schema session-end uses (canonical field reference: `skills/session-end/learning-patterns.md` § 3.5a):
 
 ```json
 {
+  "schema_version": 1,
   "id": "<uuid-v4>",
   "type": "fragile-file|effective-sizing|recurring-issue|scope-guidance|deviation-pattern",
   "subject": "<what the learning is about>",
@@ -247,11 +248,25 @@ Append new patterns to `.orchestrator/metrics/learnings.jsonl`. Use the same JSO
   "evidence": "<supporting data>",
   "confidence": 0.5,
   "source_session": "retro-YYYY-MM-DD",
-  "created_at": "<ISO 8601>",
-  "expires_at": "<ISO 8601 + learning-expiry-days (default: 30)>"
+  "scope": "local",
+  "host_class": null,
+  "anonymized": false,
+  "file_paths": ["<repo-relative path(s) this learning applies to>"],
+  "created_at": "<ISO 8601>"
 }
 ```
 
+`scope` MUST be `local|private|public` — a file path goes in `file_paths`, never in `scope` (GH#69). `schema_version` is the integer `1`. Omit `expires_at`: the CLI derives it per `type` via `deriveExpiresAt()`.
+
+Write them **only** through `scripts/apply-session-learnings.mjs` (#1446) — never by hand, never with a shell redirect. Put `{"confidence_updates": [...], "new_learnings": [...]}` in a sidecar under `.orchestrator/tmp/` via the Write tool, preview, then apply. `--decay-rate 0` keeps a retro from applying the per-session passive decay a second time:
+
+```bash
+node scripts/apply-session-learnings.mjs --input .orchestrator/tmp/retro-learnings.json --decay-rate 0 --json
+node scripts/apply-session-learnings.mjs --input .orchestrator/tmp/retro-learnings.json --decay-rate 0 --apply --json
+```
+
+Exit `1` means a record failed validation (the message names its id) and nothing was written.
+
 Typical retro learning types:
 - `fragile-file` — hotspots correlating with failures or carryover
 - `effective-sizing` — wave/agent configs producing best completion rates
@@ -259,7 +274,7 @@ Typical retro learning types:
 - `scope-guidance` — session scope calibration insights
 - `deviation-pattern` — systematic plan deviations indicating planning gaps
 
-Before writing, check existing entries for matching `type` + `subject`. Confirm (+0.15 confidence, cap 1.0) or contradict (-0.2). New learnings start at 0.5.
+Before writing, check existing entries for matching `type` + `subject`. A match is not a new learning: list its `id` in `confidence_updates` with `"operation": "confirm"` (+0.15, cap 1.0) or `"contradict"` (-0.2) — the CLI applies both. New learnings start at 0.5.
 
 ### 3.4 Optional Baseline Update
 

package/skills/quality-gates/SKILL.md

@@ -71,9 +71,11 @@ as the session baseline for later comparison.
 
 **Script output schema (Baseline):**
 ```json
-{"variant": "baseline", "typecheck": {"status": "pass|fail|skip", "output": "string"}, "test": {"status": "pass|fail|skip", "output": "string"}}
+{"variant": "baseline", "typecheck": {"status": "pass|fail|skip"}, "test": {"status": "pass|fail|skip"}, "typecheck_output": "string", "test_output": "string"}
 ```
 
+In every variant, each command object that was actually spawned also carries its per-command kill ladder: `timed_out` (boolean), `kill_signals` (string[]) and `survivors` (pid[]). A skipped or stubbed command has none of the three keys (absent, never `false`/`[]`). `scripts/run-quality-gate.mjs` joins them into `orchestrator.quality_gate.{passed,failed}` (#1457). A run whose joined `timed_out` is `true` is recorded as `.failed` in every variant, although Baseline, Incremental and Per-File still exit 0 (#1459, decided 2026-10-01).
+
 ## Variant 2: Incremental
 
 **Used by:** wave-executor (after implementation waves)
@@ -91,8 +93,8 @@ Metrics output (for consuming skills to capture):
 {
   "variant": "incremental",
   "duration_seconds": null,
-  "typecheck": "pass|fail|skip",
-  "test": "pass|fail|skip",
+  "typecheck": {"status": "pass|fail|skip"},
+  "test": {"status": "pass|fail|skip"},
   "errors": []
 }
 ```
@@ -182,7 +184,7 @@ node "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/scripts/run-qual
 node "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/scripts/run-quality-gate.mjs" --variant per-file --config "$CONFIG" --files specific-file.ts
 ```
 
-The script handles graceful degradation (missing tools → skip), structured JSON output matching the schemas above, and proper exit codes (0=pass, 1=error, 2=gate-failed).
+The script handles graceful degradation (missing tools → skip), structured JSON output matching the schemas above, and proper exit codes (0=pass, 1=error, 2=gate-failed). Only Full Gate exits 2: the three reporting variants exit 0 after a failing or killed check, so their verdict is in the JSON envelope (a kill also turns the event into `.failed`; a plain failing check does not).
 
 ## Baseline Cache (#258)
 

package/skills/reconcile/SKILL.md

@@ -394,6 +394,17 @@ consolidation survives the next `/reconcile`:
   regenerates that learning as a standalone file on the next run.
 - **A merged file's `expires-at` is the EARLIEST of its parts**, never the
   latest: it must not outlive its shortest-lived content.
+- **An EXPIRED file no longer dedupes** (#1387): the provenance reader skips it
+  whole, so its learnings become re-proposable — fail-open on an unparseable
+  date. Two known limits, measured 2026-09-18: this is the on-disk half only
+  (79 of this repo's 92 provenance keys are ALSO sidecar-terminal, so just 13
+  return), and a file the sweep cannot split or cannot read
+  (`no-1to1-mapping`, `no-provenance-block`, `unreadable`, and since GH#70
+  `no-counter-sentence` — the fail-closed branch that touches such a file not
+  at all, deletion included; none in the live tree today, `skipped: []` over 7
+  files) that expires legitimately
+  re-proposes on every run with no mechanical exit. Detail:
+  `docs/rule-authoring.md` § Consolidated rules.
 - **A dropped learning must be STAMPED before deletion, or it regenerates.**
   `rm .claude/rules/<slug>.md` alone leaves `isProcessed()` false and no
   on-disk marker, so the engine re-proposes it. Stamp it terminal first with

package/skills/remote-offload/SKILL.md

@@ -28,12 +28,14 @@ Exit codes (`offload --help`, measured 2026-09-02): `0` ok · `1` usage/config
 
 ## 1. Decision rule — offload vs reduce
 
-The gate decides, not the coordinator. `applyOffloadDecision()` in `scripts/lib/wave-resource-gate.mjs` only fires when the resource verdict is already `reduce` or `coordinator-direct`, and only AFTER the HR-004 heavy-repo cap — a capped wave that offloads still respects the cap. It never probes the network; the coordinator supplies a readiness WITNESS:
+The gate decides, not the coordinator. `applyOffloadDecision()` in `scripts/lib/wave-resource-gate.mjs` fires when the resource verdict is `reduce` or `coordinator-direct` (and, with `offload-first: true`, on `proceed` as well — see below), and only AFTER the HR-004 heavy-repo cap — a capped wave that offloads still respects the cap. It never probes the network; the coordinator supplies a readiness WITNESS:
 
 - `opts.remoteReady` — `{ [alias]: boolean }`, built from the SessionStart banner line `Offload <alias>: ready=yes …`, or
 - `opts.probeFn` — an async `(alias) => boolean` fallback, consulted only for aliases `remoteReady` doesn't answer for (backed by `remoteDoctor()`, i.e. `offload doctor -H <alias> --brief` parsed by `parseDoctorLine()`).
 
-With neither supplied, no host counts as ready and the wave stays local — the gate fails toward local, never toward an unverified host. A role in `NEVER_FOREIGN_ROLES` (`scripts/lib/wave-executor/dispatch-common.mjs`: `impl-core`, `security-review`, `migration`, `release`, `secrets`) is never offloaded regardless of readiness.
+With neither supplied, no host counts as ready and the wave stays local — the gate fails toward local, never toward an unverified host. A role in `NEVER_FOREIGN_ROLES` (`scripts/lib/wave-executor/dispatch-common.mjs`: `impl-core`, `security-review`, `migration`, `release`, `secrets`, `incident`, `refactor-crosscut`) is never offloaded regardless of readiness.
+
+With `offload-first: true` in Session Config (#1465, default `false`) the placement arm also fires on `proceed`, so an offloadable role goes to a witnessed-ready host without waiting for local pressure. The witness stays mandatory — without `remoteReady`/`probeFn` nothing moves — and a wave that stays local carries a named reason (`offload-first: no ready host for '<role>' — staying local`, or `… no remote-hosts declared — staying local`).
 
 ## 2. What is declared where
 

package/skills/session-end/SKILL.md

@@ -151,23 +151,20 @@ discipline as `createSpiralCarryoverIssue`).
 
 > Gate: Only run if `persistence` is `true` in Session Config. Skip silently otherwise.
 
-After STATE.md is finalized with `status: completed` (Phase 3.4) and Recommendations are written (Phase 3.7a), release the distributed session-lock so the next session can acquire it cleanly:
+After STATE.md is finalized with `status: completed` (Phase 3.4) and Recommendations are written (Phase 3.7a), release the distributed session-lock with ONE verifying command:
 
-```javascript
-import { release } from 'scripts/lib/session-lock.mjs';
-// sessionId is the physical raw value established by session-start Phase 1.2
-// and stored in .orchestrator/session.lock `session_id`. It is not STATE.md
-// `session:` or `semantic_session_id`, both of which are attribution labels.
-const rawSessionId = sessionId;
-const result = release({ sessionId: rawSessionId, repoRoot: process.cwd() });
-// result.ok is always true unless a filesystem error occurred.
-// result.deleted === true  → lock file removed successfully.
-// result.deleted === false → lock was absent or had a different raw session_id.
+```bash
+node scripts/release-session-lock.mjs --session-id "<raw session_id>" --json
 ```
 
-If `result.deleted === false`, log `info: session-lock not released — already absent or raw session_id mismatch` and continue. An active lock whose raw id differs is ambiguous: do **not** retry release with an equal `semantic_session_id`, STATE.md `session`, or owner proof. Leave that live lock for its TTL/Reaper lifecycle.
+`--session-id` is the PHYSICAL raw value established by session-start Phase 1.2 and stored in `.orchestrator/session.lock` `session_id` — never STATE.md `session:` and never `semantic_session_id`, both of which are attribution labels.
+
+The command releases the lock only when that raw id owns it, emits the terminal `orchestrator.session.lock.released` breadcrumb, and then RE-READS the lock path: **exit 0 means the lock is provably gone.** It replaces the hand-executed `release()` this phase used to prescribe, which deleted the lock silently — the SessionEnd hook then found `status: 'absent'` and emitted nothing either, so a lock lifecycle ended with no terminal event at all (#1395: 5 `lock.acquired` against 0 `lock.released` in this repo). `outcome: "absent"` is a normal exit-0 result (idempotent re-run; nothing was released, so no event is written).
+
+A non-zero exit is a WARN, never a blocker — log `⚠ session-lock: <outcome>` and continue; the TTL provides automatic expiry for the next session:
 
-If `result.ok === false` (rare filesystem error), log `⚠ session-lock: release failed — <result.reason>` and continue. Do NOT block the close for a lock-release failure — the TTL provides automatic expiry for the next session.
+- **exit 1** — the lock is owned by a different raw session id, so nothing was touched. That is ambiguous by design: do **not** retry with an equal `semantic_session_id`, STATE.md `session`, or owner proof. Leave that live lock for its TTL/Reaper lifecycle.
+- **exit 2** — system error (unreadable/corrupt lock, owner-proof mismatch, the lock still present after release, or the breadcrumb could not be written).
 
 The lock is released here — AFTER all STATE.md writes are complete and BEFORE the commit is staged in Phase 4.1. This ordering ensures a clean handover when the current raw owner releases it: the lock file is absent from the working tree when the commit is assembled, so it is not accidentally staged.
 
@@ -260,7 +257,7 @@ swallow it with `|| true`.
 
 ## Phase 5: Issue Cleanup
 
-> Always runs. Closes resolved issues (stripping `status:*` labels first via `stripStatusLabels`, #308), updates partially-done issues, and in Step 3 FILES the Phase 1.65 gate's carry-list — the deferred `createSpiralCarryoverIssue` call for SPIRAL/FAILED items and the `markOpenQuestionAnsweredOnDisk` write live here, not in Phase 1.65 (atomicity). Step 3b folds non-exempt over-cap creations into one `[Backlog-Sammel]` collector under the `issue-budget` cap; discovery findings from Phase 1.5 are filed at the end. Full procedure: [`references/phase-5-issue-cleanup.md`](references/phase-5-issue-cleanup.md).
+> Always runs. Closes resolved issues via the single `node "$PLUGIN_ROOT/scripts/lib/issue-close-strip-labels.mjs" --close [--vcs gitlab|github] [-R <spec>] <id>...` CLI call (strips `status:*` labels, closes, then re-reads each id; a `closed: false` in its per-id JSON output is a finding, not done — #308), updates partially-done issues, and in Step 3 FILES the Phase 1.65 gate's carry-list — the deferred `createSpiralCarryoverIssue` call for SPIRAL/FAILED items and the `markOpenQuestionAnsweredOnDisk` write live here, not in Phase 1.65 (atomicity). Step 3b folds non-exempt over-cap creations into one `[Backlog-Sammel]` collector under the `issue-budget` cap; discovery findings from Phase 1.5 are filed at the end. Full procedure: [`references/phase-5-issue-cleanup.md`](references/phase-5-issue-cleanup.md).
 
 ## Phase 6: Final Report
 
@@ -280,7 +277,7 @@ Present to the user the **Session Summary**: Completed / Carried Over / Dropped
 | `references/phase-3-documentation-updates.md` | Phase 3 full procedural body — final heartbeat (#590-3), 3.0 Defensive Cleanup, 3.1 SSOT files, 3.2/3.2a docs + handover, 3.3 rules freshness, 3.4/3.4a STATE.md write + snapshot cleanup, 3.45 Telemetry Flush, 3.5/3.5a/3.6.x memory + learnings + tail dispatcher, 3.7/3.7a/3.7b/3.7c/3.7d metrics, recommendations, durable commit, vault board, session-eval |
 | `phase-3-2-docs-verification.md` | Phase 3.2 full procedural body — docs-tasks load, SESSION_START_REF, per-task loop, mode-gated report, Documentation Coverage block |
 | `learning-patterns.md` | Phases 3.5a + 3.6 extraction heuristics, confidence updates, passive decay, and JSONL write procedure |
-| `phase-3-6-tail.md` | Phase 3.6.x tail — detail procedures for the tail phases: 3.6.3 Memory-Proposals Collection (`collectProposals` + AUQ multiSelect + `promoteAndClear`, composing `writeApproved` + `clearProposalsJsonl` behind a mechanical write-before-clear guard, #828), **3.6.4 Expired-Learnings Sweep — MECHANICAL since 2026-09-09**: after `planTailPhases()`, call `runTailPhases({ repoRoot, plan })` from `scripts/lib/session-end/tail-runner.mjs` (delegating to `runExpiredSweep`) and report `result['3.6.4']` (`ran`, `scanned`, `archived`); the event `orchestrator.learnings.sweep_applied` is the proof it ran (Epic #723 B4), **3.6.5 Auto-Dream — RETIRED** and **3.6.7 Auto-Dialectic — RETIRED** (both replaced by the session-start `maintenance-due` probe, `checkMaintenanceDue` in `scripts/lib/maintenance-due-banner.mjs`; headings kept as two-line stubs because other docs cite them), 3.6.6 Skill-Applied Judge (#645 L3 — `runSkillJudge`, coordinator-writes), 3.6.8 Reconciliation Rule Proposals (#696 FA3 — `runReconcile` + AUQ + `writeApprovedRules`). Loaded on demand by the SKILL.md skip-plan dispatcher (#724) — only phases with `run: true` in the `planTailPhases()` plan execute |
+| `phase-3-6-tail.md` | Phase 3.6.x tail — detail procedures for the tail phases: 3.6.3 Memory-Proposals Collection (`collectProposals` + AUQ multiSelect + `promoteAndClear`, composing `writeApproved` + `clearProposalsJsonl` behind a mechanical write-before-clear guard, #828), **3.6.4 Expired-Learnings Sweep — MECHANICAL since 2026-09-09**: after `planTailPhases()`, call `runTailPhases({ repoRoot, plan })` from `scripts/lib/session-end/tail-runner.mjs` (delegating to `runExpiredSweep`) and report `result['3.6.4']` (`ran`, `scanned`, `archived`); the event `orchestrator.learnings.sweep_applied` is the proof it ran (Epic #723 B4), **3.6.5 Auto-Dream — RETIRED** and **3.6.7 Auto-Dialectic — RETIRED** (both replaced by the session-start `maintenance-due` probe, `checkMaintenanceDue` in `scripts/lib/maintenance-due-banner.mjs`; headings kept as two-line stubs because other docs cite them), 3.6.6 Skill-Applied Judge (#645 L3 — two calls, not one: `buildSkillEvidence` from `scripts/lib/skill-evidence-window.mjs` renders this session's transcript into the evidence window, then `runSkillJudge` judges it and the coordinator writes each judgment via `appendSkillJudgment`; on empty evidence text `runSkillJudge` returns `status: 'no-evidence'` and does NOT dispatch, #1399 — the exact call shape is in the sub-file, do not reconstruct it here), 3.6.8 Reconciliation Rule Proposals (#696 FA3 — `runReconcile` + AUQ + `writeApprovedRules`). Loaded on demand by the SKILL.md skip-plan dispatcher (#724) — only phases with `run: true` in the `planTailPhases()` plan execute |
 | `scripts/lib/session-end/phase-skip.mjs` | Phase 3.6.x tail skip-plan aggregator (#724) — `planTailPhases({repoRoot, config, sessionId, platform})` → `{plan, skippedReport}`; side-effect-free (reconcile/sweep via dry-run — no writes), never-throws (per-phase probe error fail-opens to `run: true`). Since 2026-09-09 it plans FOUR phases, not six: the 3.6.5 (auto-dream) and 3.6.7 (auto-dialectic) deciders were removed with those phases' retirement. Its APPLY half for 3.6.4 is `scripts/lib/session-end/tail-runner.mjs` (`runTailPhases`, `runExpiredSweep`) — the planner fails OPEN, the runner fails CLOSED |
 | `references/phase-3-documentation-updates.md` § 3.45 | Telemetry Flush (advisory, #844; MECHANICAL since #1138 — `hooks/on-session-end.mjs` calls `flush()` itself at the end of every teardown and emits an `orchestrator.telemetry.flush` breadcrumb, so this phase is the DESCRIPTION and the fallback, never the trigger; a coordinator that skips it changes nothing) — `flush()` from `scripts/lib/telemetry/sync.mjs` drains the host-local send-queue fire-and-forget; no config key (send-gate is `resolveConsent()` inside the module, fail-closed); skip when `persistence: false`; never-throw + ~3s-bounded, offline → bounded oldest-dropped queue, optional `Telemetry: sent/queued/gated` close-summary line, NEVER an error banner; runs late in the close after Phase 3.7 |
 | `session-metrics-write.md` | Phase 3.7 JSONL append, vault-mirror invocation, durable narrative mirror (`mirrorNarrative`, #675), and behavior matrix |
@@ -292,7 +289,7 @@ Present to the user the **Session Summary**: Completed / Carried Over / Dropped
 | (inline) Phase 4 | Commit & Push — stage individually (PSA-004), commit, push to origin, then the `github-mirror-push` block (4 states: not-a-repo / no `github` remote / pushed / push failed) |
 | `references/phase-4a-worktree-cleanup.md` | Phase 4a full procedural body — auto-promoted-worktree detection (`detectAutoPromotedWorktree`, marker-keyed since #1069), clean-check, clean auto-remove path, dirty 3-option AUQ (`Behalten`/`Löschen`/`Manuell`), PSA-003 + #490 ordering rationale |
 | `references/phase-4b-worktree-orphan-sweep.md` | Phase 4b full procedural body — `checkWorktreeOrphans()` read-only proposal set, the coordinator-rendered AUQ, opt-in `worktree-orphans.enabled` gate |
-| `references/phase-5-issue-cleanup.md` | Phase 5 full procedural body — close resolved issues (`stripStatusLabels`, #308), Step 3 filing of the Phase 1.65 carry-list incl. the deferred `createSpiralCarryoverIssue` and `markOpenQuestionAnsweredOnDisk`, Step 3b `[Backlog-Sammel]` overflow, discovery-issue creation |
+| `references/phase-5-issue-cleanup.md` | Phase 5 full procedural body — close resolved issues via `node "$PLUGIN_ROOT/scripts/lib/issue-close-strip-labels.mjs" --close` (strip `status:*` → close → re-read; `closed: false` is a finding, not done, #308), Step 3 filing of the Phase 1.65 carry-list incl. the deferred `createSpiralCarryoverIssue` and `markOpenQuestionAnsweredOnDisk`, Step 3b `[Backlog-Sammel]` overflow, discovery-issue creation |
 | `references/phase-5-issue-cleanup.md` § Step 3b.2 (issue-budget reconcile) | Phase 5 issue-budget cross-check — `reconcileIssueBudget({ repoRoot, record, sessionId, rawSessionId, config })` from `scripts/lib/issue-budget-reconcile.mjs` runs on the in-memory session record BEFORE it is appended to `sessions.jsonl`, `emitIssueBudgetReconciled` records `orchestrator.issue_budget.reconciled`, and `formatIssueBudgetReconcileWarn(result)` prints the verdict (`match` / `no-ledger` / `escaped` / `stale-record`) in the Final Report. Ordered AFTER the overflow drain (which resets `overflow[]`) and BEFORE `reapStaleBudgetFiles` (which must not remove the file being read) |
 | `references/session-summary-template.md` | Phase 6 Final Report — the full Session Summary template (Completed / Carried Over / Dropped at Handover Gate / New Issues / Unresolved Review Findings / Metrics incl. Docs Health + Custom Phases / Next Session Recommendations) plus the Test-delta and Documentation-Coverage anchors |
 

package/skills/session-end/discovery-scan.md

@@ -27,7 +27,7 @@ Agent({
   run_in_background: false
 })
 ```
-On Codex CLI / Cursor IDE: execute probes sequentially within the current context (no Agent dispatch).
+Use the native delegation tools actually exposed by the current runtime, following [Platform Tool Adaptation](../_shared/platform-tools.md). If the runtime exposes no suitable delegation tool, execute the probes sequentially within the current context.
 - Collect verified findings from the discovery output
 - Parse the discovery output for the **findings** array and **stats** object (see Parsing callout below)
 - Store the stats object for Phase 1.7 metrics collection (`discovery_stats` field)