session-orchestrator 3.16.0

package/scripts/lib/backlog-scan.mjs

@@ -0,0 +1,179 @@
+/**
+ * backlog-scan.mjs — VCS backlog signal source for Mode-Selector (Phase B-3, issue #293).
+ *
+ * Provides `scanBacklog({limit, vcs})` returning structured counts derived from the
+ * project's open-issue list via `glab` (GitLab) or `gh` (GitHub). The result is fed
+ * into `signals.backlog` consumed by `selectMode` in `mode-selector.mjs`.
+ *
+ * Design contract:
+ *  - Pure structural counts, never raw issue objects (keeps the selector pure).
+ *  - Module-level cache keyed on (vcs, limit) — one VCS round-trip per session.
+ *  - Graceful degradation: missing CLI / non-zero exit / parse failure → null.
+ *    Never throws to the caller.
+ *
+ * Stale threshold: 30 days since `updated_at`.
+ *
+ * Dependencies:
+ *  - VCS detection follows `skills/gitlab-ops/SKILL.md` (origin URL contains "github.com" → gh, else glab).
+ */
+
+import { spawnSync } from 'node:child_process';
+
+export const STALE_THRESHOLD_DAYS = 30;
+
+/** Module-level cache. Keyed by JSON.stringify({vcs, limit}). */
+const _cache = new Map();
+
+/**
+ * Detect the VCS for the current working directory by inspecting the origin URL.
+ * Returns 'github' | 'gitlab' | null. Never throws.
+ *
+ * @returns {'github'|'gitlab'|null}
+ */
+export function detectVcs() {
+  try {
+    const r = spawnSync('git', ['remote', 'get-url', 'origin'], { encoding: 'utf8' });
+    if (r.status !== 0) return null;
+    const url = String(r.stdout || '').trim();
+    if (!url) return null;
+    return url.includes('github.com') ? 'github' : 'gitlab';
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run a CLI command and parse stdout as JSON. Returns null on any failure
+ * (binary missing, non-zero exit, empty stdout, unparsable JSON, non-array).
+ * spawnSync sets `r.status = null` and `r.error.code = 'ENOENT'` when the
+ * binary is absent — the `r.status !== 0` check covers that path.
+ *
+ * @param {string} bin
+ * @param {string[]} args
+ * @returns {Array|null}
+ */
+function runJson(bin, args) {
+  try {
+    const r = spawnSync(bin, args, { encoding: 'utf8' });
+    if (r.status !== 0) return null;
+    const out = String(r.stdout || '').trim();
+    if (!out) return null;
+    const parsed = JSON.parse(out);
+    return Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compute days elapsed between an ISO-8601 timestamp and `now`.
+ * Returns Infinity if the input is unparsable so unparsable dates never count
+ * as "fresh".
+ *
+ * @param {string|undefined|null} iso
+ * @param {number} nowMs
+ * @returns {number}
+ */
+function ageDays(iso, nowMs) {
+  if (!iso || typeof iso !== 'string') return Infinity;
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return Infinity;
+  return (nowMs - t) / 86_400_000;
+}
+
+/**
+ * Aggregate a list of issue records into the structural backlog summary.
+ *
+ * Issue shape requirements (tolerant — missing fields are skipped):
+ *  - `labels`: array of strings OR array of {name: string} objects
+ *  - `updated_at` (glab) or `updatedAt` (gh): ISO-8601 timestamp
+ *
+ * @param {Array<object>} issues
+ * @param {number} nowMs — injected for tests
+ * @returns {{criticalCount: number, highCount: number, staleCount: number, byLabel: Record<string, number>, total: number}}
+ */
+export function summarizeIssues(issues, nowMs = Date.now()) {
+  let criticalCount = 0;
+  let highCount = 0;
+  let staleCount = 0;
+  const byLabel = {};
+
+  for (const issue of issues) {
+    if (!issue || typeof issue !== 'object') continue;
+
+    const rawLabels = Array.isArray(issue.labels) ? issue.labels : [];
+    const labelNames = rawLabels
+      .map((l) => (typeof l === 'string' ? l : l && typeof l === 'object' ? l.name : null))
+      .filter((n) => typeof n === 'string' && n.length > 0);
+
+    for (const name of labelNames) {
+      byLabel[name] = (byLabel[name] || 0) + 1;
+      if (name === 'priority:critical') criticalCount += 1;
+      else if (name === 'priority:high') highCount += 1;
+    }
+
+    const updated = issue.updated_at || issue.updatedAt || null;
+    if (ageDays(updated, nowMs) > STALE_THRESHOLD_DAYS) staleCount += 1;
+  }
+
+  return {
+    criticalCount,
+    highCount,
+    staleCount,
+    byLabel,
+    total: issues.length,
+  };
+}
+
+/**
+ * Scan the project's open backlog and return a structural summary suitable for
+ * `signals.backlog`. Caches the result per (vcs, limit) within the running process.
+ *
+ * Returns null on any of:
+ *  - VCS cannot be detected (no git origin)
+ *  - CLI binary missing (`glab` for gitlab, `gh` for github)
+ *  - CLI exits non-zero or produces unparsable output
+ *
+ * Never throws.
+ *
+ * @param {{limit?: number, vcs?: 'github'|'gitlab'|null, nowMs?: number}} [opts]
+ * @returns {Promise<null | {criticalCount: number, highCount: number, staleCount: number, byLabel: Record<string, number>, total: number, vcs: string, limit: number}>}
+ */
+export async function scanBacklog(opts = {}) {
+  const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : 50;
+  // Distinguish "user did not pass vcs" (auto-detect) from "user explicitly passed
+  // null" (degrade). 'vcs' in opts catches the explicit-null path so callers can
+  // force the no-vcs branch in tests without monkey-patching detectVcs.
+  const vcs = 'vcs' in opts ? opts.vcs : detectVcs();
+  const nowMs = typeof opts.nowMs === 'number' ? opts.nowMs : Date.now();
+
+  if (vcs !== 'github' && vcs !== 'gitlab') return null;
+
+  const cacheKey = JSON.stringify({ vcs, limit });
+  if (_cache.has(cacheKey)) return _cache.get(cacheKey);
+
+  const bin = vcs === 'github' ? 'gh' : 'glab';
+  const args =
+    vcs === 'github'
+      ? ['issue', 'list', '--limit', String(limit), '--json', 'number,labels,updatedAt,state']
+      : ['issue', 'list', '--per-page', String(limit), '--output', 'json'];
+
+  const issues = runJson(bin, args);
+  if (issues === null) {
+    _cache.set(cacheKey, null);
+    return null;
+  }
+
+  const summary = summarizeIssues(issues, nowMs);
+  const result = { ...summary, vcs, limit };
+  _cache.set(cacheKey, result);
+  return result;
+}
+
+/**
+ * Test/coordinator helper: clear the in-process cache. Not part of the
+ * production surface but exported so tests don't need to reload the module.
+ */
+export function clearBacklogCache() {
+  _cache.clear();
+}

package/scripts/lib/bootstrap-lock-freshness.mjs

@@ -0,0 +1,260 @@
+/**
+ * bootstrap-lock-freshness.mjs — #186 / #290 / #203
+ * Validates .orchestrator/bootstrap.lock freshness + plugin-version drift.
+ *
+ * Plain-JS validation — no Zod dependency.
+ * Never throws. Never mutates input.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Milliseconds in one day — extracted for readability + testability (#203). */
+export const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/**
+ * Minimal single-level YAML parser for .orchestrator/bootstrap.lock.
+ * Returns an object with all key:value pairs found. Unknown fields are
+ * preserved. Comment lines and blank lines are ignored. Values are trimmed.
+ *
+ * @returns {Record<string, string>}
+ */
+export function parseBootstrapLock(contents) {
+  if (typeof contents !== 'string') return {};
+
+  const result = {};
+  for (const raw of contents.split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const value = line.slice(colonIdx + 1).trim();
+    if (key) result[key] = value;
+  }
+  return result;
+}
+
+/**
+ * Reads the plugin version from package.json at the given plugin root.
+ * Returns null if the file is absent or unparseable — never throws.
+ *
+ * @param {string} pluginRoot  Absolute path to the session-orchestrator plugin root.
+ * @returns {string|null}
+ */
+export function readPluginVersionFromPackageJson(pluginRoot) {
+  try {
+    const pkgPath = join(pluginRoot, 'package.json');
+    const raw = readFileSync(pkgPath, 'utf8');
+    const pkg = JSON.parse(raw);
+    return typeof pkg.version === 'string' ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Classifies a version mismatch severity between two semver strings.
+ *
+ * Rules (#290):
+ *   - major component differs → 'alert'
+ *   - minor or patch only differs → 'info'
+ *   - either string is not parseable semver → 'warn' (safe fallback)
+ *
+ * @param {string} lockVer    Version string from bootstrap.lock.
+ * @param {string} currentVer Current plugin version.
+ * @returns {'info'|'warn'|'alert'}
+ */
+export function classifyVersionMismatch(lockVer, currentVer) {
+  // Simple semver: split on '.' and compare the major component.
+  const parse = (v) => v.match(/^(\d+)\.(\d+)\.(\d+)/);
+  const lm = parse(lockVer);
+  const cm = parse(currentVer);
+  if (!lm || !cm) return 'warn'; // not parseable — safe fallback
+  if (lm[1] !== cm[1]) return 'alert'; // major mismatch
+  return 'info'; // minor or patch only
+}
+
+/**
+ * Checks .orchestrator/bootstrap.lock for freshness and plugin-version drift.
+ *
+ * Tiered severity:
+ *   info  — ageDays < 30 AND (no version mismatch OR patch/minor-only mismatch)
+ *   warn  — ageDays 30..89 OR non-parseable version mismatch
+ *   alert — ageDays >= 90 OR bootstrappedAt unparseable OR lock missing
+ *           OR major plugin-version mismatch
+ *
+ * Legacy lock support: if `bootstrapped-at` is absent, falls back to
+ * `timestamp` (present in all pre-#186 locks). If both absent, severity=alert.
+ *
+ * Backward compat (#290): if the lock file predates the `plugin-version` field,
+ * a soft informational message is added to details but severity is NOT raised.
+ *
+ * Refresh awareness (#57): `refreshed-at` / `refreshed-plugin-version`
+ * (written by `scripts/lib/bootstrap-lock-refresh.mjs`) take precedence over
+ * `bootstrapped-at`/`timestamp` and `plugin-version` respectively when present
+ * — a refresh resets the freshness clock and acknowledges the current plugin
+ * version without disturbing the lock's original bootstrap provenance
+ * (`details.bootstrappedAt`/`details.pluginVersion` always report the
+ * ORIGINAL values, unchanged by a refresh).
+ *
+ * `details.reason` names the single highest-severity contributor driving the
+ * returned severity: `'missing-repoRoot' | 'missing' | 'read-error' |
+ * 'stale-age' | 'unparseable-timestamp' | 'version-mismatch-major' |
+ * 'version-mismatch-unparseable' | null` (null when severity is `'info'`).
+ * When both age and version-drift would independently raise severity, the
+ * higher-ranked contributor wins (alert > warn > info); a tie is broken in
+ * favor of the age reason.
+ *
+ * @param {{repoRoot: string, currentPluginVersion?: string, now?: number}} opts
+ * @returns {{ok: boolean, severity: 'info'|'warn'|'alert', message: string, details: object}}
+ */
+export function checkBootstrapLockFreshness({
+  repoRoot,
+  currentPluginVersion,
+  now = Date.now(),
+} = {}) {
+  if (!repoRoot) {
+    return {
+      ok: false,
+      severity: 'alert',
+      message: 'bootstrap.lock: repoRoot not provided',
+      details: { reason: 'missing-repoRoot' },
+    };
+  }
+
+  const lockPath = join(repoRoot, '.orchestrator', 'bootstrap.lock');
+
+  if (!existsSync(lockPath)) {
+    return {
+      ok: false,
+      severity: 'alert',
+      message: 'bootstrap.lock missing',
+      details: { reason: 'missing' },
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = parseBootstrapLock(readFileSync(lockPath, 'utf8'));
+  } catch {
+    return {
+      ok: false,
+      severity: 'alert',
+      message: 'bootstrap.lock: failed to read file',
+      details: { reason: 'read-error' },
+    };
+  }
+
+  // Fall back to legacy `timestamp` field for pre-#186 locks. `bootstrappedAt`
+  // and `pluginVersion` report the ORIGINAL bootstrap provenance and are never
+  // overwritten by a later refresh (#57 provenance-honesty guarantee).
+  const bootstrappedAt = parsed['bootstrapped-at'] || parsed['timestamp'] || null;
+  const pluginVersion = parsed['plugin-version'] || null;
+
+  // #57 — refresh-writer fields (scripts/lib/bootstrap-lock-refresh.mjs).
+  // Raw, possibly null; absent on every pre-#57 lock and on any lock that has
+  // never been refreshed.
+  const refreshedAt = parsed['refreshed-at'] || null;
+  const refreshedPluginVersion = parsed['refreshed-plugin-version'] || null;
+
+  // Age-source precedence (#57): refreshed-at → bootstrapped-at → timestamp.
+  // A refresh resets the freshness clock without touching bootstrappedAt.
+  const ageSourceAt = refreshedAt || bootstrappedAt;
+
+  let ageDays = null;
+  if (ageSourceAt) {
+    const ts = Date.parse(ageSourceAt);
+    if (!Number.isNaN(ts)) {
+      ageDays = Math.floor((now - ts) / MS_PER_DAY);
+    }
+  }
+
+  // Version-drift source precedence (#57): refreshed-plugin-version → plugin-version.
+  // A refresh acknowledges the current plugin version without touching pluginVersion.
+  const effectivePluginVersion = refreshedPluginVersion || pluginVersion;
+
+  // Backward compat (#290): lock predates plugin-version field — soft signal only.
+  // #57: a refresh that stamps refreshed-plugin-version resolves this (the
+  // effective version is now comparable), so this check uses the same
+  // refreshed-plugin-version → plugin-version precedence as the mismatch check.
+  const legacyLockNoPluinVersion =
+    typeof currentPluginVersion === 'string' && effectivePluginVersion === null;
+
+  let versionMismatch = false;
+  let versionMismatchSeverity = null; // 'info' | 'warn' | 'alert' — null when no mismatch
+
+  if (
+    typeof currentPluginVersion === 'string' &&
+    typeof effectivePluginVersion === 'string' &&
+    effectivePluginVersion !== currentPluginVersion
+  ) {
+    versionMismatch = true;
+    versionMismatchSeverity = classifyVersionMismatch(effectivePluginVersion, currentPluginVersion);
+  }
+
+  let severity = 'info';
+
+  // #57 — reason-aware tiering. `reason` names the single HIGHEST-severity
+  // contributor (age vs. version-drift) so downstream prose can recommend the
+  // right remediation instead of always pointing at --retroactive. Rank:
+  // alert=2, warn=1, info=0, none=-1. `considerReason` only replaces the
+  // current pick on a STRICT rank increase, so calling the age contributor
+  // before the version contributor implements "tie → age reason".
+  let reason = null;
+  let reasonRank = -1;
+  const rank = (s) => (s === 'alert' ? 2 : s === 'warn' ? 1 : s === 'info' ? 0 : -1);
+  const considerReason = (candidateSeverity, candidateReason) => {
+    const r = rank(candidateSeverity);
+    if (r > reasonRank) {
+      reasonRank = r;
+      reason = candidateReason;
+    }
+  };
+
+  // Age-based escalation.
+  if (ageDays !== null && ageDays >= 30) {
+    severity = 'warn';
+    considerReason('warn', 'stale-age');
+  }
+  if (ageDays !== null && ageDays >= 90) {
+    severity = 'alert';
+    considerReason('alert', 'stale-age');
+  }
+  if (ageDays === null) {
+    severity = 'alert';
+    considerReason('alert', 'unparseable-timestamp');
+  }
+
+  // Version-mismatch escalation (only when mismatch detected).
+  if (versionMismatch && versionMismatchSeverity === 'warn') {
+    if (severity === 'info') severity = 'warn';
+    considerReason('warn', 'version-mismatch-unparseable');
+  }
+  if (versionMismatch && versionMismatchSeverity === 'alert') {
+    severity = 'alert';
+    considerReason('alert', 'version-mismatch-major');
+  }
+  // 'info'-classified mismatches (minor/patch) do NOT raise severity beyond
+  // whatever age already determined, and do not contribute a reason.
+
+  return {
+    ok: severity === 'info',
+    severity,
+    message: `bootstrap.lock: age=${ageDays ?? 'unknown'}d, plugin-version=${pluginVersion ?? 'unknown'} (current=${currentPluginVersion ?? 'unknown'})`,
+    details: {
+      ageDays,
+      pluginVersion,
+      currentPluginVersion: currentPluginVersion ?? null,
+      bootstrappedAt,
+      refreshedAt,
+      refreshedPluginVersion,
+      versionMismatch,
+      versionMismatchSeverity,
+      legacyLock: legacyLockNoPluinVersion
+        ? 'lock predates plugin-version field; consider /bootstrap --refresh-lock to stamp a current plugin-version reference'
+        : null,
+      reason,
+    },
+  };
+}

package/scripts/lib/bootstrap-lock-refresh.mjs

@@ -0,0 +1,186 @@
+/**
+ * bootstrap-lock-refresh.mjs — #57
+ * Provenance-honest `.orchestrator/bootstrap.lock` refresh writer.
+ *
+ * `checkBootstrapLockFreshness()` (bootstrap-lock-freshness.mjs) can only ever
+ * *diagnose* a stale/drifted lock — it is read-only by design. Before #57 the
+ * only remediation the surrounding prose offered was `/bootstrap --retroactive`,
+ * which is a no-op once the lock already has valid `version`/`tier` fields
+ * (see the Retroactive Flow's idempotency guard in `skills/bootstrap/SKILL.md`)
+ * — the operator would re-run the recommended command and see nothing change.
+ *
+ * `refreshBootstrapLock()` closes that gap: it acknowledges the current
+ * plugin version and resets the freshness clock by appending/updating exactly
+ * two fields — `refreshed-at` and `refreshed-plugin-version` — while leaving
+ * every other line of the lock file byte-identical. The ORIGINAL bootstrap
+ * provenance (`bootstrapped-at`/`timestamp`, `plugin-version`, `tier`,
+ * `archetype`, `source`, …) is never rewritten. This is the load-bearing
+ * guarantee: a refresh is an acknowledgement, not a re-bootstrap.
+ *
+ * Plain-JS — no Zod dependency. Never throws; every failure path returns a
+ * structured `{ ok: false, reason, message }` object. Never fabricates a lock
+ * — a missing or structurally invalid lock is refused, not synthesized.
+ */
+
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { parseBootstrapLock } from './bootstrap-lock-freshness.mjs';
+
+const PRECONDITION_MESSAGE_SUFFIX =
+  'run /bootstrap or /bootstrap --retroactive first.';
+
+/**
+ * Locate the (trimmed, comment-skipping) line index for a given top-level
+ * lock key, mirroring {@link parseBootstrapLock}'s own key-extraction rules
+ * so upsert targets the same line parseBootstrapLock would report for `key`.
+ *
+ * @param {string[]} lines
+ * @param {string} key
+ * @returns {number} 0-based index, or -1 when not found.
+ */
+function findKeyLineIndex(lines, key) {
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const colonIdx = trimmed.indexOf(':');
+    if (colonIdx === -1) continue;
+    if (trimmed.slice(0, colonIdx).trim() === key) return i;
+  }
+  return -1;
+}
+
+/**
+ * Replace the line for `key` in place, or append a new `key: value` line
+ * when absent. Mutates `lines` in place; every other line is left untouched.
+ *
+ * @param {string[]} lines
+ * @param {string} key
+ * @param {string} value
+ */
+function upsertKeyLine(lines, key, value) {
+  const formatted = `${key}: ${value}`;
+  const idx = findKeyLineIndex(lines, key);
+  if (idx === -1) {
+    lines.push(formatted);
+  } else {
+    lines[idx] = formatted;
+  }
+}
+
+/**
+ * Strip CR/LF from a value before it is composed into an upserted `key:
+ * value` lock line — defense-in-depth: a malformed `currentPluginVersion`
+ * (or, symmetrically, the generated ISO timestamp) containing an embedded
+ * newline could otherwise inject an arbitrary forged `key: value` line into
+ * the lock file via {@link upsertKeyLine}. Never throws; non-string input is
+ * returned unchanged (callers already guard the string check).
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function sanitizeLockValue(value) {
+  return typeof value === 'string' ? value.replace(/[\r\n]/g, '') : value;
+}
+
+/**
+ * Atomically write `content` to `filePath` via tmp-file + renameSync — the
+ * same crash-safe pattern used by `scripts/lib/io.mjs#writeJsonAtomicSync`
+ * and `scripts/lib/session-lock.mjs`, adapted for raw (non-JSON) text.
+ *
+ * @param {string} filePath
+ * @param {string} content
+ */
+function writeTextAtomicSync(filePath, content) {
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true });
+  const tmpSuffix = randomBytes(6).toString('hex');
+  const tmpFile = join(dir, `.bootstrap-lock-refresh.${tmpSuffix}.tmp`);
+  writeFileSync(tmpFile, content, { encoding: 'utf8' });
+  renameSync(tmpFile, filePath);
+}
+
+/**
+ * Refreshes `.orchestrator/bootstrap.lock` in place: acknowledges the current
+ * plugin version and resets the freshness clock without disturbing the
+ * lock's original bootstrap provenance.
+ *
+ * Precondition: the lock must exist and parse with non-empty `version` and
+ * `tier` fields. A missing or structurally invalid lock is refused — this
+ * function never fabricates a lock (that is `/bootstrap` or
+ * `/bootstrap --retroactive`'s job, not this one's).
+ *
+ * Write contract (provenance honesty, #57): every line of the existing lock
+ * is preserved byte-for-byte EXCEPT the `refreshed-at` line (always written)
+ * and the `refreshed-plugin-version` line (written only when
+ * `currentPluginVersion` is a non-empty string). Re-running twice replaces
+ * those two lines in place — it never duplicates them (idempotent).
+ *
+ * @param {{repoRoot: string, currentPluginVersion?: string, now?: number}} opts
+ * @returns {{ok: true, path: string, refreshedAt: string, refreshedPluginVersion: string|null}
+ *          | {ok: false, reason: 'missing-or-invalid', message: string}}
+ */
+export function refreshBootstrapLock({ repoRoot, currentPluginVersion, now = Date.now() } = {}) {
+  if (!repoRoot) {
+    return {
+      ok: false,
+      reason: 'missing-or-invalid',
+      message: `bootstrap.lock: repoRoot not provided — ${PRECONDITION_MESSAGE_SUFFIX}`,
+    };
+  }
+
+  const lockPath = join(repoRoot, '.orchestrator', 'bootstrap.lock');
+
+  if (!existsSync(lockPath)) {
+    return {
+      ok: false,
+      reason: 'missing-or-invalid',
+      message: `bootstrap.lock missing — ${PRECONDITION_MESSAGE_SUFFIX}`,
+    };
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(lockPath, 'utf8');
+  } catch {
+    return {
+      ok: false,
+      reason: 'missing-or-invalid',
+      message: `bootstrap.lock: failed to read file — ${PRECONDITION_MESSAGE_SUFFIX}`,
+    };
+  }
+
+  const parsed = parseBootstrapLock(raw);
+  if (!parsed['version'] || !parsed['tier']) {
+    return {
+      ok: false,
+      reason: 'missing-or-invalid',
+      message: `bootstrap.lock: missing required version/tier fields — ${PRECONDITION_MESSAGE_SUFFIX}`,
+    };
+  }
+
+  const hadTrailingNewline = raw.endsWith('\n');
+  const lines = raw.split('\n');
+  if (hadTrailingNewline) lines.pop(); // drop the implicit empty tail element from split()
+
+  const refreshedAt = sanitizeLockValue(new Date(now).toISOString());
+  const refreshedPluginVersion =
+    typeof currentPluginVersion === 'string' && currentPluginVersion.length > 0
+      ? sanitizeLockValue(currentPluginVersion)
+      : null;
+
+  upsertKeyLine(lines, 'refreshed-at', refreshedAt);
+  if (refreshedPluginVersion !== null) {
+    upsertKeyLine(lines, 'refreshed-plugin-version', refreshedPluginVersion);
+  }
+
+  const newContent = lines.join('\n') + (hadTrailingNewline ? '\n' : '');
+  writeTextAtomicSync(lockPath, newContent);
+
+  return {
+    ok: true,
+    path: lockPath,
+    refreshedAt,
+    refreshedPluginVersion,
+  };
+}