instar 1.3.196 → 1.3.198

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.196",
+  "version": "1.3.198",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/scripts/validate-retro-harvest.mjs

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+/**
+ * validate-retro-harvest.mjs — the schema validator for Apprenticeship Step 0
+ * retro-harvest artifacts (`apprenticeship-retro-harvest/v1`).
+ *
+ * Per APPRENTICESHIP-STEP0-RETRO-HARVEST-SPEC.md §9, this is the structural
+ * SIGNAL — not the authority. It checks the artifact's SHAPE deterministically;
+ * the LLM fidelity review (recorded in frontmatter) is the AUTHORITY for whether
+ * the harvest is faithful. (Signal vs Authority / The Body and the Mind.)
+ *
+ * Two layers:
+ *   - validateRetroHarvest(text, opts)  — PURE, offline, unit-tested. Structure,
+ *     reconciliation, redaction backstop, path safety, completeness, scope rules.
+ *   - checkLiveLedger(frontmatter, fetchImpl) — OPTIONAL live cross-check that
+ *     seeded ids resolve in the running ledger. Network; run by the integration
+ *     test / `--check-live`, never by the pure unit path.
+ *
+ * CLI:  node scripts/validate-retro-harvest.mjs <artifact.md> [--prior] [--check-live]
+ *   exit 0 = valid, exit 1 = invalid (errors to stderr).
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import yaml from 'js-yaml';
+
+export const SCHEMA_ID = 'apprenticeship-retro-harvest/v1';
+export const INSTANCE_TYPES = ['mentorship', 'apprenticeship'];
+export const SCOPE_MODES = ['full', 'incremental'];
+export const COMPLETENESS = ['complete', 'partial-accepted'];
+export const FIDELITY_VERDICTS = ['faithful', 'partial', 'rejected'];
+export const HARVEST_DIR = 'docs/apprenticeship/retro-harvests';
+
+/** Scrubbers Step 0 trusts. A missing/unknown/failed scrub refuses the artifact (§7). */
+export const APPROVED_SCRUBBERS = ['correction-scrub', 'instar-pii-scrub'];
+
+/** Evidence-pointer URI schemes (§6). */
+export const POINTER_PATTERNS = {
+  ledger: /^ledger:[0-9a-f-]{6,}$/i,            // validator-resolvable
+  pr: /^pr:\d+$/,                                // validator-resolvable
+  thread: /^thread:\d+#[\w.-]+$/,               // immutable msg locator; fidelity-review-only
+  memory: /^memory:[a-z0-9_-]+@[0-9a-f]{6,}#[\w.-]+$/i, // slug@hash#anchor; fidelity-review-only
+};
+
+/** Secret-shaped strings the backstop rejects (§7). A LIMITED backstop, not a scrub. */
+const SECRET_PATTERNS = [
+  { name: 'bearer-token', re: /\bBearer\s+[A-Za-z0-9._-]{8,}/ },
+  { name: 'tunnel-sig', re: /[?&]sig=[0-9a-f]{16,}/i },
+  { name: 'long-hex-blob', re: /\b[0-9a-f]{40,}\b/i },
+  { name: 'long-base64-blob', re: /\b[A-Za-z0-9+/]{50,}={0,2}\b/ },
+  { name: 'email', re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/ },
+];
+
+/**
+ * Split a markdown doc into { frontmatter (parsed), body (string) }.
+ * Throws if there is no `---`-delimited YAML frontmatter.
+ */
+export function parseArtifact(text) {
+  const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(text);
+  if (!m) throw new Error('no YAML frontmatter (--- … ---) found');
+  const frontmatter = yaml.load(m[1]) || {};
+  return { frontmatter, body: m[2] || '' };
+}
+
+/** Count top-level `- ` bullet items directly under a `## <heading>` section. */
+export function countSectionItems(body, heading) {
+  const lines = body.split('\n');
+  let inSection = false;
+  let count = 0;
+  const headingRe = new RegExp('^##\\s+' + heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i');
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) inSection = headingRe.test(line);
+    else if (inSection && /^-\s+\S/.test(line)) count++;
+  }
+  return count;
+}
+
+/** True when the body contains a secret-shaped string (returns the matched pattern name or null). */
+export function findSecret(body) {
+  for (const { name, re } of SECRET_PATTERNS) {
+    if (re.test(body)) return name;
+  }
+  return null;
+}
+
+/**
+ * Resolve + confine an artifact path to HARVEST_DIR. Returns the safe relative
+ * path or throws on traversal / bad component (§6 security).
+ */
+export function safeArtifactPath(from, to, instanceType) {
+  for (const [k, v] of Object.entries({ from, to, instanceType })) {
+    if (typeof v !== 'string' || !/^[a-z0-9-]+$/.test(v)) {
+      throw new Error(`unsafe path component ${k}="${v}" (must match ^[a-z0-9-]+$)`);
+    }
+  }
+  const rel = `${HARVEST_DIR}/${from}-to-${to}-${instanceType}.md`;
+  const resolved = path.normalize(rel);
+  if (resolved.includes('..') || !resolved.startsWith(HARVEST_DIR + path.sep) && !resolved.startsWith(HARVEST_DIR + '/')) {
+    throw new Error(`path escapes ${HARVEST_DIR}: ${resolved}`);
+  }
+  return rel;
+}
+
+/**
+ * PURE structural validation of a retro-harvest artifact.
+ * @param {string} text - full artifact markdown
+ * @param {{ priorHarvestExists?: boolean }} [opts]
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateRetroHarvest(text, opts = {}) {
+  const errors = [];
+  const priorHarvestExists = !!opts.priorHarvestExists;
+
+  let parsed;
+  try {
+    parsed = parseArtifact(text);
+  } catch (e) {
+    return { valid: false, errors: [`parse: ${e.message}`] };
+  }
+  const { frontmatter: fm, body } = parsed;
+
+  // --- schema id
+  if (fm.schema !== SCHEMA_ID) errors.push(`schema must be "${SCHEMA_ID}" (got "${fm.schema}")`);
+
+  // --- required scalar fields
+  for (const f of ['instanceType', 'from', 'to', 'framework', 'harvestedAt', 'scopeMode', 'completeness']) {
+    if (fm[f] == null || fm[f] === '') errors.push(`missing required field: ${f}`);
+  }
+  if (fm.instanceType && !INSTANCE_TYPES.includes(fm.instanceType))
+    errors.push(`instanceType must be one of ${INSTANCE_TYPES.join('|')}`);
+  if (fm.scopeMode && !SCOPE_MODES.includes(fm.scopeMode))
+    errors.push(`scopeMode must be one of ${SCOPE_MODES.join('|')}`);
+  if (fm.completeness && !COMPLETENESS.includes(fm.completeness))
+    errors.push(`completeness must be one of ${COMPLETENESS.join('|')}`);
+
+  // --- path safety on the identity components
+  if (fm.from && fm.to && fm.instanceType) {
+    try { safeArtifactPath(fm.from, fm.to, fm.instanceType); }
+    catch (e) { errors.push(`path: ${e.message}`); }
+  }
+
+  // --- scope rule: first harvest (no prior baseline) MUST be full (§8)
+  if (fm.scopeMode === 'incremental' && !priorHarvestExists)
+    errors.push('scopeMode "incremental" requires a prior harvest baseline; the first harvest must be "full"');
+
+  // --- sourcesCovered: coverage EXTENT, not bare booleans (§8)
+  const sc = fm.sourcesCovered;
+  if (!sc || typeof sc !== 'object') {
+    errors.push('missing sourcesCovered');
+  } else {
+    if (!sc.ledger || typeof sc.ledger.issueCount !== 'number')
+      errors.push('sourcesCovered.ledger must carry { read, issueCount }');
+    if (!sc.playbook || typeof sc.playbook.entryCount !== 'number')
+      errors.push('sourcesCovered.playbook must carry { read, entryCount }');
+    if (!Array.isArray(sc.threads))
+      errors.push('sourcesCovered.threads must be an array of { id, messagesRead, truncated }');
+    else for (const t of sc.threads) {
+      if (typeof t.messagesRead !== 'number' || typeof t.truncated !== 'boolean')
+        errors.push(`sourcesCovered.threads[${t && t.id}] needs numeric messagesRead + boolean truncated (coverage extent, not presence)`);
+    }
+  }
+
+  // --- completeness vs truncation (§8): complete ⇒ nothing truncated
+  if (fm.completeness === 'complete' && sc && Array.isArray(sc.threads)) {
+    if (sc.threads.some((t) => t.truncated === true))
+      errors.push('completeness "complete" is invalid when a source is truncated; use "partial-accepted" with named gaps');
+  }
+
+  // --- counts reconcile with body (§9)
+  const counts = fm.counts || {};
+  const bodyLessons = countSectionItems(body, 'Lessons');
+  const bodyMeta = countSectionItems(body, 'Meta-lessons');
+  const bodyProc = countSectionItems(body, 'Process-insights');
+  const bodyNeeds = countSectionItems(body, 'What the program needs');
+  if (counts.lessons !== bodyLessons)
+    errors.push(`counts.lessons=${counts.lessons} but body has ${bodyLessons} "## Lessons" items`);
+  if (counts.metaLessons !== bodyMeta)
+    errors.push(`counts.metaLessons=${counts.metaLessons} but body has ${bodyMeta} "## Meta-lessons" items`);
+  if (counts.processInsights !== bodyProc)
+    errors.push(`counts.processInsights=${counts.processInsights} but body has ${bodyProc} "## Process-insights" items`);
+  if (fm.programNeeds !== bodyNeeds)
+    errors.push(`programNeeds=${fm.programNeeds} but body has ${bodyNeeds} "## What the program needs" items`);
+
+  // --- redaction: approved scrubber, not failed (§7)
+  const r = fm.redaction;
+  if (!r || typeof r !== 'object') {
+    errors.push('missing redaction { scrubber, findingsRemoved, scrubbedAt }');
+  } else {
+    const scrubberName = String(r.scrubber || '').split('@')[0];
+    if (!APPROVED_SCRUBBERS.includes(scrubberName))
+      errors.push(`redaction.scrubber "${r.scrubber}" not in approved list (${APPROVED_SCRUBBERS.join(', ')})`);
+    if (r.status === 'failed') errors.push('redaction.status is "failed" — scrub must succeed before write');
+    if (typeof r.findingsRemoved !== 'number') errors.push('redaction.findingsRemoved must be a number');
+  }
+
+  // --- fidelity review: the authority's stamp (§9)
+  const fr = fm.fidelityReview;
+  if (!fr || typeof fr !== 'object') {
+    errors.push('missing fidelityReview { reviewer, verdict, at }');
+  } else {
+    if (!FIDELITY_VERDICTS.includes(fr.verdict))
+      errors.push(`fidelityReview.verdict must be one of ${FIDELITY_VERDICTS.join('|')}`);
+    if (fr.verdict === 'rejected') errors.push('fidelityReview.verdict is "rejected" — harvest is not faithful');
+    if (fr.verdict === 'partial' && !fr.gaps && !(fr.audit && fr.audit.gaps))
+      errors.push('fidelityReview "partial" must name the gaps (fidelityReview.gaps)');
+    if (!fr.reviewer) errors.push('fidelityReview.reviewer required (must be independent of the harvesting pass)');
+  }
+
+  // --- evidence pointers well-formed (§6). Strip trailing sentence punctuation
+  // so a pointer at a clause boundary ("ledger:abc123, priority…") still validates.
+  const pointerTokens = (body.match(/\b(?:ledger|pr|thread|memory):[^\s)\]]+/g) || [])
+    .map((t) => t.replace(/[.,;:]+$/, ''));
+  for (const tok of pointerTokens) {
+    const scheme = tok.split(':')[0];
+    const re = POINTER_PATTERNS[scheme];
+    if (re && !re.test(tok)) errors.push(`malformed evidence pointer: ${tok}`);
+  }
+
+  // --- secret backstop (§7)
+  const secret = findSecret(body);
+  if (secret) errors.push(`secret-shaped string in body (${secret}) — pointers-not-payloads (§7)`);
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * OPTIONAL live cross-check: every seededToPlaybook id resolves at candidate+ in
+ * the running ledger. Network — never part of the pure unit path. Inject fetch.
+ * @returns {Promise<{ ok: boolean, errors: string[] }>}
+ */
+export async function checkLiveLedger(frontmatter, fetchImpl) {
+  const errors = [];
+  const seeded = Array.isArray(frontmatter.seededToPlaybook) ? frontmatter.seededToPlaybook : [];
+  for (const s of seeded) {
+    const id = s && s.id;
+    if (!id) { errors.push('seededToPlaybook entry without id'); continue; }
+    try {
+      const res = await fetchImpl(id);
+      if (!res || !res.found) errors.push(`seeded id ${id} not found in live ledger`);
+      else if (!['candidate', 'extracted'].includes(res.playbookStatus))
+        errors.push(`seeded id ${id} is "${res.playbookStatus}", expected candidate+`);
+    } catch (e) {
+      errors.push(`live check for ${id} failed: ${e.message}`);
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+// --- CLI entry (guarded so importing for tests is side-effect-free)
+const isMain = (() => {
+  try { return process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]); }
+  catch { return false; }
+})();
+
+if (isMain) {
+  const args = process.argv.slice(2);
+  const file = args.find((a) => !a.startsWith('--'));
+  const priorHarvestExists = args.includes('--prior');
+  if (!file) {
+    console.error('usage: validate-retro-harvest.mjs <artifact.md> [--prior] [--check-live]');
+    process.exit(1);
+  }
+  const text = readFileSync(file, 'utf8');
+  const { valid, errors } = validateRetroHarvest(text, { priorHarvestExists });
+  if (!valid) {
+    console.error(`INVALID: ${file}`);
+    for (const e of errors) console.error('  - ' + e);
+    process.exit(1);
+  }
+  console.log(`valid: ${file}`);
+  process.exit(0);
+}

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-02T02:41:08.992Z",
-  "instarVersion": "1.3.196",
+  "generatedAt": "2026-06-02T05:25:38.499Z",
+  "instarVersion": "1.3.198",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -65,7 +65,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -74,7 +74,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -83,7 +83,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -101,7 +101,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1489,7 +1489,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
+      "contentHash": "600eb489f11a1b72daa4d5845e2cb0b3d24b08d868c7ebc65e090b028d833b67",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/1.3.197.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Agents are no longer assigned a network port that the multi-machine mesh secretly can't reach.
+
+The mesh talks between machines using Node's built-in web-request function, which refuses a short standard list of "bad ports" (for example 4045, the old file-lock service port). That list includes a port inside the default range agents were picked from — so an agent could be handed a port on which it would silently fail to pair or fail over, with no error in normal tools. The port picker now skips those bad ports, and any agent already running on one prints a clear startup warning telling you to change its port.
+
+## What to Tell Your User
+
+Nothing to do for new agents — they'll automatically avoid the handful of reserved ports that break multi-machine networking. If you run multiple machines and one happens to be on a bad port, the agent now warns you at startup with the exact fix (change its port and restart). This removes a silent, very-hard-to-spot failure where an agent looked healthy but could never join the mesh.
+
+## Summary of New Capabilities
+
+- The agent port allocator skips WHATWG fetch "bad ports" (4045, 6000, 6566, 6697, …), so a new agent never lands on a port the mesh's node-fetch comms can't reach.
+- A new exported helper, isFetchBlockedPort, plus an unconditional server-startup warning when an existing agent's configured port is on that list (the migration path for already-running agents).
+
+## Evidence
+
+- Root cause of a real 2026-06-02 failure: a paired test agent on port 4045 could never be joined ("fetch failed: bad port") even though curl reached its pairing endpoint; moving it off 4045 fixed the join immediately.
+- `tsc --noEmit` clean; 34 agent-registry unit tests green, including 3 new ones covering the blocklist helper (both sides of the boundary) and the allocator skipping a blocked port. Side-effects review: upgrades/side-effects/fix-fetch-blocked-ports.md.

package/upgrades/1.3.198.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+An agent that loses its private code copy can now actually reinstall itself at boot.
+
+When the boot wrapper detects a missing "shadow install" it runs `npm install` to self-heal. Some packages run native setup scripts that shell out to `node`/`npm` by name — and under macOS launchd the boot process often has a stripped `PATH` without them, so the reinstall died with "command not found" and the agent stayed stuck (looping on "Shadow install missing"). The reinstall now puts the resolved node directory on PATH and sets npm's scripts-prepend-node-path, so those setup scripts resolve node/npm and the self-heal completes. Existing agents get the fixed wrapper regenerated automatically on update.
+
+## What to Tell Your User
+
+Nothing to do. This makes an agent's automatic self-repair actually work when its private code copy goes missing — the case where it most needs to recover on its own, unattended. A healthy agent is completely unaffected; this only changes the recovery path.
+
+## Summary of New Capabilities
+
+- The boot-wrapper reinstall (`instar-boot.cjs` and `instar-boot.sh`) prepends the resolved node directory to PATH and sets `npm_config_scripts_prepend_node_path` so native postinstall scripts (e.g. sharp) resolve node/npm under a launchd-spawned boot child instead of failing with "command not found".
+- The post-update migration regenerates older boot wrappers that predate this fix (it now requires the install-path marker to consider a wrapper current), so deployed agents receive the fix on their next update — not just new installs.
+
+## Evidence
+
+- Root cause of a real 2026-06-02 failure: a paired test agent could not start; `instar-boot` looped on "Shadow install missing" and a manual reinstall failed on sharp's postinstall with `sh: node: command not found`; re-running with node on PATH fixed it immediately.
+- `tsc --noEmit` clean. `PostUpdateMigrator-bootWrapperAbiCheck` extended to 8 green tests (3-marker idempotency, regen-when-install-path-marker-absent, generated `.cjs` passes `node --check` + carries the env, `.sh` carries the PATH export); 30 sibling boot-wrapper tests still green. Side-effects review: upgrades/side-effects/fix-bootwrapper-install-path.md.

package/upgrades/side-effects/APPRENTICESHIP-STEP0-RETRO-HARVEST-SPEC.md

@@ -0,0 +1,78 @@
+# Side-Effects Review — Apprenticeship Step 0: Retro-Harvest
+
+**Version / slug:** `APPRENTICESHIP-STEP0-RETRO-HARVEST-SPEC`
+**Date:** `2026-06-01`
+**Author:** `echo`
+**Second-pass reviewer:** `not required` (converged via /spec-converge: 5 internal reviewers + codex gpt-5.5, 3 rounds)
+
+## Summary of the change
+
+Builds Step 0 of the Apprenticeship Program (Tier-3 umbrella #675). Ships:
+- `scripts/validate-retro-harvest.mjs` — the pure, offline schema validator (the structural
+  SIGNAL) for `apprenticeship-retro-harvest/v1` artifacts, plus an optional injected-fetch
+  live-ledger cross-check.
+- `tests/unit/validate-retro-harvest.test.ts` (34 cases, both sides of every boundary) +
+  `tests/integration/retro-harvest-artifact.test.ts` (the real artifact as a fixture-of-record).
+- `docs/apprenticeship/RETRO-HARVEST-PROCEDURE.md` — the repeatable how-to.
+- `docs/apprenticeship/retro-harvests/echo-to-codey-mentorship.md` — the first real harvest,
+  grounded in the live ledger (28 issues), reviewed by an independent fidelity reviewer.
+- `docs/apprenticeship/retro-harvests/INDEX.json` — the latest-harvest pointer.
+
+No `src/` is touched. The validator is a standalone `scripts/` tool not imported by `src/`.
+
+## Decision-point inventory
+
+One: the validator's pass/fail boundary (`validateRetroHarvest`). It is a **signal**, not an
+authority (spec §9) — it asserts artifact SHAPE (schema, required fields, count/programNeeds
+reconciliation, coverage-extent, scope/completeness rules, evidence-pointer well-formedness,
+a limited secret-pattern backstop, path confinement, an approved+succeeded scrub, and a
+non-`rejected` fidelity verdict). It does NOT judge harvest fidelity — that is the independent
+LLM fidelity review, recorded in the artifact frontmatter.
+
+## 1. Over-block
+
+**What legitimate inputs does this reject?** A structurally malformed artifact (missing fields,
+counts that disagree with the body, an incremental first harvest, a `complete` artifact with a
+truncated source, an unapproved/failed scrub, a `rejected` fidelity verdict, a secret-shaped
+string, a malformed pointer). All are genuine defects the gate is meant to refuse. Trailing
+sentence punctuation after a pointer is tolerated (stripped before validation) so a clause-
+boundary pointer is not falsely rejected.
+
+## 2. Under-block
+
+**What does this still miss?** By design, the validator does NOT judge whether the harvest is
+*truthful or complete* — a well-shaped but hollow harvest passes the validator; the LLM fidelity
+review is the authority that catches that (Signal vs Authority). The secret-pattern scan is an
+explicit *limited backstop*, not a scrub guarantee (it misses API keys, hostnames, sig-less
+URLs, names, phone numbers, contextual PII); the authoritative defense is the approved scrubber.
+Live-ledger resolution of seeded ids runs only under `--check-live` / the integration path, not
+the pure unit path.
+
+## 3. Level-of-abstraction fit
+
+**Right layer?** Yes. The validator is a pure function with a thin CLI guard, in `scripts/`
+beside the other repo-invariant validators, unit-testable with no git/fs/network mocking. The
+harvest artifact + procedure + index are plain repo docs under `docs/apprenticeship/`. The gate
+that will *require* a valid harvest before an instance starts is deliberately deferred to Step 1
+(spec §12–13) — this step ships the artifact + the validator the gate will call.
+
+## 4. Testing
+
+- **Unit** (`tests/unit/validate-retro-harvest.test.ts`): 34 cases — valid baseline + a targeted
+  failing mutation per decision boundary + `checkLiveLedger` with an injected fetch.
+- **Integration** (`tests/integration/retro-harvest-artifact.test.ts`): the REAL
+  `echo-to-codey-mentorship.md` validates against the REAL validator; it is a full first harvest
+  with an independent (non-Echo) fidelity reviewer; seeds nothing (#50-independent); is INDEX-
+  registered.
+- **E2E:** genuinely n/a — pure CLI validator, no HTTP route, no DI (spec §9, §11).
+
+## 5. Migration / rollback / Agent-Awareness
+
+- **Migration Parity:** N/A. No agent-installed files (`.claude/`, `.instar/config.json`, hooks,
+  skills, CLAUDE.md template), no config defaults, no `src/`. Pure repo docs + one `scripts/`
+  helper + tests.
+- **Rollback:** revert the commit; nothing is deployed to agents, no state is written.
+- **Agent-Awareness:** explicitly deferred to Step 1 (spec §12) — the awareness surface ("a valid
+  harvest is required before an instance starts") belongs with the gate Step 1 wires, not before
+  it exists.
+- **NEXT.md / publish:** no `src/` change → no fleet-release/publish concern.

package/upgrades/side-effects/fix-bootwrapper-install-path.md

@@ -0,0 +1,83 @@
+# Side-Effects Review — Boot-wrapper reinstall: put node on PATH for native postinstalls
+
+**Version / slug:** `fix-bootwrapper-install-path`
+**Date:** `2026-06-02`
+**Author:** `echo`
+**Tier:** 1 (small, well-understood bugfix; ELI16 + side-effects, no converged spec) — but HIGH blast radius (boot shim), reviewed accordingly
+**Parent principle:** Cross-Machine Coherence / Bootstrap Robustness — an agent must be able to self-heal its own install
+
+## Summary of the change
+
+The boot wrapper (`instar-boot.cjs` / `instar-boot.sh`, generated by `installBootWrapper`
+in `src/commands/setup.ts`) self-heals a missing shadow install by running `npm install`.
+That `npm install` was spawned with **no `env` / no PATH augmentation**, so native
+postinstall scripts (e.g. `sharp`: `sh -c "node install/check.js || npm run build"`) ran in
+a subshell whose PATH — under a launchd-spawned boot child — has no `node`/`npm`, dying with
+`command not found`. The reinstall then aborts and the shadow install never heals.
+
+**Observed live (2026-06-02):** a throwaway mini agent could not start — `instar-boot`
+looped on "Shadow install missing", and a manual reinstall reproduced it: it failed on
+`sharp`'s postinstall (`sh: node: command not found`). Re-running with `node` on PATH
+succeeded immediately.
+
+### What changed
+- `src/commands/setup.ts` — `installBootWrapper`:
+  - **`.cjs` (jsWrapper):** the reinstall `execFileSync(nodeBin, [npmCli, 'install', …])` now
+    passes `env: installEnv` where `installEnv` prepends `path.dirname(nodeBin)` to `PATH` and
+    sets `npm_config_scripts_prepend_node_path: 'true'`.
+  - **`.sh` (bashWrapper):** the reinstall now runs with
+    `PATH="$(dirname "$NODE_BIN"):$PATH" npm_config_scripts_prepend_node_path=true` prefixed.
+- `src/core/PostUpdateMigrator.ts` — `migrateBootWrapperAbiCheck`: the "already current" guard
+  now ALSO requires the `npm_config_scripts_prepend_node_path` marker, so existing agents whose
+  wrapper predates this fix are regenerated on update (Migration Parity).
+
+## Decision-point inventory
+- reinstall env: augment vs inherit → augment (prepend node dir + npm flag). Inheriting the
+  launchd PATH is the bug.
+- migration: add a 3rd required marker vs leave 2 → add the marker (otherwise deployed agents
+  with the 2 prior markers never regenerate and never get the fix).
+- auto-re-port / auto-anything else: none — purely the reinstall env.
+
+## 1. Over-correction risk
+The env only AUGMENTS PATH (prepends node dir; keeps the rest) and sets one npm flag. A healthy
+agent never enters the reinstall branch at all (`if (!fs.existsSync(SHADOW))`), so the change is
+inert unless the shadow install is actually missing. `npm_config_scripts_prepend_node_path` is
+npm's own documented option for exactly this case.
+
+## 2. Under-correction risk
+The migration regenerates only wrappers missing the new marker; agents already regenerated stay
+put (idempotent). The `.sh` variant is for manual/Linux use; the launchd-critical path is `.cjs`.
+
+## 3. Level-of-abstraction fit
+The fix lives in the single boot-wrapper generator (`installBootWrapper`) that both `init` and the
+migration call — one source, both consumers. No scattering.
+
+## 4. Signal vs Authority
+Pure deterministic env construction (no LLM/heuristic). Appropriate.
+
+## 5. External surfaces
+None. No route/config-schema change. The generated wrapper gains an env on one spawn.
+
+## 6. Interactions with existing primitives
+The reinstall's debounce marker, the ABI-aware node self-heal, and the version-managed-node
+candidate discovery are all unchanged; this only adds an env to the npm spawn and a 3rd marker
+to the migration's idempotency sniff (composes with the existing two).
+
+## 7. Rollback cost
+Trivial: drop the `env`/PATH additions and the 3rd marker clause. No persistent state.
+
+## Migration parity
+- New agents: `installBootWrapper` (via `init`) writes the fixed wrapper.
+- Existing agents: `migrateBootWrapperAbiCheck` regenerates `instar-boot.cjs` because the new
+  `npm_config_scripts_prepend_node_path` marker is absent. Idempotent — re-running skips once the
+  marker is present.
+
+## Tests
+`tsc --noEmit` clean. `PostUpdateMigrator-bootWrapperAbiCheck` extended to 8 tests (all green):
+the "skip" idempotency case now requires all THREE markers; a new regen case for a wrapper with
+the two prior markers but missing the install-path marker; a generated-content test asserting the
+`.cjs` reinstall passes `env: installEnv` with `npm_config_scripts_prepend_node_path` + the PATH
+prepend AND that the generated `.cjs` passes `node --check` (guards against template-escaping
+bricking the boot shim); a `.sh` generated-content test. 30 sibling boot-wrapper tests
+(`bootWrapperCjs`, `plist-coherence`, `lifeline-shadow-install-self-heal`, `init-join-launchd-handoff`)
+all still green — no regressions.