instar 1.3.195 → 1.3.197

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-02T01:29:07.977Z",
-  "instarVersion": "1.3.195",
+  "generatedAt": "2026-06-02T04:46:08.483Z",
+  "instarVersion": "1.3.197",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {
@@ -1089,7 +1089,7 @@
       "type": "template",
       "domain": "operations",
       "sourcePath": "src/templates/scripts/convergence-check.sh",
-      "contentHash": "41ef69307819140731f293b175093238f88988365c3973b8e44b9c18669e32bd",
+      "contentHash": "b0475554bde6729d2d9a1f8005dcada6a8e4c767203d8293c09a212f9bf0a196",
       "since": "2025-01-01"
     },
     "template:git-sync-gate.sh": {
@@ -1545,7 +1545,7 @@
       "type": "subsystem",
       "domain": "coordination",
       "sourcePath": "src/core/MultiMachineCoordinator.ts",
-      "contentHash": "f5c2bd171e32ec39384c2b16b73b3d2827f044d664b8923183f6006fce009ba8",
+      "contentHash": "63ce6fcd9564b1e547e2b0ad6153e43293566dac6a6db6f17ffb8cbf28b28894",
       "since": "2025-01-01"
     },
     "subsystem:backup-manager": {

package/src/templates/scripts/convergence-check.sh

@@ -149,6 +149,26 @@ if echo "$CONTENT" | grep -qiE "(i used to (think|believe|feel|assume)|back when
   ISSUE_COUNT=$((ISSUE_COUNT + 1))
 fi
 
+# 8. SPEC-REVIEW LINK — a spec handed over for review must carry a rendered
+# ELI16 tunnel link the operator can open. Structure > Willpower: the link is
+# guaranteed by skills/spec-converge/scripts/publish-spec-review.mjs. Narrow by
+# design (this blocks the send): fires only on an unambiguous spec handoff —
+# a docs/specs/*.md reference, OR a GitHub PR mentioned with the word "spec" —
+# in an explicit review/approval handoff, with no /view/ link present. An
+# ordinary code-PR mention does not fire.
+SPEC_HANDOFF=""
+if echo "$CONTENT" | grep -qiE "docs/specs/[^ )]+\.md"; then
+  SPEC_HANDOFF="yes"
+elif echo "$CONTENT" | grep -qiE "github\.com/[^ )]+/pull/[0-9]+" && echo "$CONTENT" | grep -qiE "\bspec(s|ification)?\b"; then
+  SPEC_HANDOFF="yes"
+fi
+if [ -n "$SPEC_HANDOFF" ] \
+  && echo "$CONTENT" | grep -qiE "\b(review|approv|sign[- ]?off|take a look|for your|ready for)\b" \
+  && ! echo "$CONTENT" | grep -qiE "/view/[0-9a-f-]{8,}"; then
+  ISSUES+=("SPEC_REVIEW_LINK: You're handing a spec over for review with no rendered ELI16 tunnel link the operator can open. Deliver spec reviews via skills/spec-converge/scripts/publish-spec-review.mjs — it renders the ELI16, verifies the link (HTTP 200), and includes it. Don't send a spec for review without the rendered link.")
+  ISSUE_COUNT=$((ISSUE_COUNT + 1))
+fi
+
 # Output results
 if [ "$ISSUE_COUNT" -gt "0" ]; then
   echo "=== CONVERGENCE CHECK: ${ISSUE_COUNT} ISSUE(S) FOUND ==="

package/upgrades/1.3.196.md

@@ -0,0 +1,27 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixes a crash-loop regression introduced with the multi-machine active-pull feature.
+
+On a machine running by itself (no other live machine in its mesh), the active-pull loop was re-checking the "who's awake" role every few seconds and, whenever the short-lived internal lease briefly lapsed between renewals, wrongly flipped the machine to a standby (read-only) state. A follow-up write then crashed the server, and it restarted into the same loop. Because the server is also the messaging relay, the operator saw silence during the loop.
+
+The fix: the active-pull loop now only re-evaluates the awake/standby role when it has actually heard a lease from a peer. A machine on its own is never demoted by the pull loop on a transient lease lapse — its normal heartbeat keeps renewing the lease as before. The genuine multi-machine behavior (a backup that pulls a newer lease from a live peer still steps down) is unchanged.
+
+This pairs with the earlier hardening that made a read-only/standby write non-fatal, so both the wrong state and the crash it could cause are now closed.
+
+## What to Tell Your User
+
+Nothing to do. If you run an agent on a single machine, this removes a rare crash-restart loop that could make it go quiet for a while; multi-machine setups behave the same as before, just without the spurious solo demotion.
+
+## Summary of New Capabilities
+
+- The active lease-pull loop only reconciles the awake/standby role when a peer lease was actually observed, so a solo machine is never demoted (and never driven read-only) by the pull loop on a transient self-lease lapse. Regression test added; the real peer-driven demotion path is retained and tested.
+
+## Evidence
+
+- `tsc --noEmit` clean; 45 multi-machine unit tests green, including a new regression (a solo holder whose self-lease lapses with no peer observed stays awake and never goes read-only) and the retained same-epoch contested-split-brain test (feature intact).
+- Root cause of the 2026-06-02 echo crash-loop incident. Spec: docs/specs/MULTI-MACHINE-ROBUST-LEASE-PROPAGATION-SPEC.md (approved). Side-effects review: upgrades/side-effects/fix-activepull-solo-demotion.md.

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/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-activepull-solo-demotion.md

@@ -0,0 +1,75 @@
+# Side-Effects Review — Fix: active-pull must not demote a solo machine on a transient lease lapse
+
+**Version / slug:** `fix-activepull-solo-demotion`
+**Date:** `2026-06-02`
+**Author:** `echo`
+**Spec:** `docs/specs/MULTI-MACHINE-ROBUST-LEASE-PROPAGATION-SPEC.md` (approved: true) — corrects a regression in the active-pull it introduced (#668).
+**Parent principle:** `Cross-Machine Coherence — One Agent, Robust Under Degraded Conditions`
+
+## Summary of the change
+
+A one-condition fix to `MultiMachineCoordinator.tickLeasePull`: it now only calls
+`reconcileRoleToLease('lease-pull')` + `surfacePullDiscoveredSplitBrain()` when a peer
+lease was **actually observed** (`leaseCoordinator.observedPeerLease()` non-null).
+
+### Why (live incident, 2026-06-02)
+
+The active-pull loop (shipped in #668) reconciled the machine's lease role
+**unconditionally** every `leasePullIntervalMs` (~5s). On a solo machine — one with no
+reachable peers (the only registry peer was dead 3 days, no `lastKnownUrl`, so `peers()`
+was empty) — every brief lapse of the 60s self-lease between renewals made
+`holdsLease()` return false, so the pull loop flipped the machine to **standby** →
+`StateManager` read-only → a standby write threw and (pre-#673) crashed the server in a
+launchd restart loop (lease epoch climbed into the thousands). The crashing server is the
+Telegram relay, so the operator saw silence. #673 already stopped the *crash* (read-only
+write is now an isolated/recoverable uncaught-exception class); this PR removes the *root
+cause* (the spurious demotion itself).
+
+## Decision-point inventory
+
+- `tickLeasePull` reconcile vs skip: reconcile only when `observedPeerLease()` is non-null.
+  Pull is for LEARNING from peers; with no peer signal there is nothing to reconcile.
+  Role/renewal for a solo holder stays with the heartbeat `tickLease` (which RE-ACQUIRES,
+  not merely demotes).
+
+## 1. Over-correction risk
+Does gating on an observed peer break the real feature (a standby pulling a higher-epoch
+holder must still demote)? No — that path records the holder's lease via `recordObserved`,
+so `observedPeerLease()` is non-null and the reconcile runs exactly as before. Covered by
+the retained "same-epoch contested" test.
+
+## 2. Under-correction risk
+A solo holder whose lease lapses is no longer demoted by the *pull* loop, but the 2-min
+heartbeat `tickLease` still renews/re-acquires it — so role management is preserved, just
+moved off the aggressive 5s pull cadence that caused the DoS.
+
+## 3. Level-of-abstraction fit
+The fix sits in the pull tick (the loop that caused the regression), gating on the
+coordinator's existing `observedPeerLease()` accessor — no new surface.
+
+## 4. Signal vs Authority
+The pull remains a SIGNAL (observe peer leases); the FencedLease epoch/validity checks
+remain the authority for who holds. The fix stops the signal loop from ACTING (demoting)
+in the absence of any signal.
+
+## 5. External surfaces
+None. No route/config/schema change. `leasePullIntervalMs` unchanged.
+
+## 6. Interactions with existing primitives
+Composes with #673 (read-only-write no longer fatal) as defense-in-depth: #673 prevents
+the crash; this prevents the wrong state that led to it. The heartbeat `tickLease` and the
+acquire path are untouched.
+
+## 7. Rollback cost
+Trivial + safe: a single `if (observedPeerLease())` guard. Reverting restores the prior
+(buggy) unconditional reconcile.
+
+## Migration parity
+None — pure code logic change, reaches existing agents on the normal dist update.
+
+## Tests
+`tsc --noEmit` clean. 45 multi-machine tests green, including a NEW regression
+(`MultiMachineCoordinator-leasePull` — a solo holder whose self-lease lapses with no peer
+observed stays awake + never goes read-only) and the retained same-epoch-contested test
+(feature intact). Operational note: echo was reverted to solo mode during the incident
+(machine identity moved aside); re-pairing its mesh is a separate, operator-gated step.

package/upgrades/side-effects/fix-fetch-blocked-ports.md

@@ -0,0 +1,74 @@
+# Side-Effects Review — Skip WHATWG fetch-blocked ports in agent port allocation
+
+**Version / slug:** `fix-fetch-blocked-ports`
+**Date:** `2026-06-02`
+**Author:** `echo`
+**Tier:** 1 (small, low-risk; ELI16 + side-effects, no converged spec)
+**Parent principle:** Cross-Machine Coherence — One Agent, Robust Under Degraded Conditions
+
+## Summary of the change
+
+Instar's multi-machine mesh does ALL cross-machine I/O over node's global `fetch`
+(pairing `POST /api/pair`, lease broadcast/pull, heartbeat). Node's `fetch` (undici)
+throws `TypeError: fetch failed { cause: 'bad port' }` for any URL whose port is on the
+WHATWG Fetch spec "bad ports" list. The default agent port-allocation range (4040–4099)
+**contains 4045** (NFS `lockd`, a blocked port), so the allocator could hand an agent a
+port on which it can **never** be reached over the mesh — silently, because `curl`
+ignores the blocklist so the endpoint looks healthy.
+
+**Observed live (2026-06-02):** a freshly-paired throwaway test agent landed on 4045 and
+could not be joined — `instar join` failed with "fetch failed" despite `curl` to the same
+`/api/pair` returning 400. Moving it off 4045 fixed the join instantly.
+
+### What changed
+- `src/core/AgentRegistry.ts`: added `FETCH_BLOCKED_PORTS` (the WHATWG bad-ports set) +
+  exported `isFetchBlockedPort(port)`. Both `allocatePort` and `allocatePortByName` now
+  skip blocked ports (in addition to used + lsof-busy ones).
+- `src/commands/server.ts`: an unconditional startup warning when `config.port` is a
+  blocked port — the migration-parity path for EXISTING agents already on one (the
+  allocator guard only protects newly-allocated agents).
+
+## Decision-point inventory
+- allocator: skip vs allocate a port → skip if on the blocklist (the check precedes the
+  lsof probe, so it's deterministic).
+- startup: warn vs silent → warn (loud, non-fatal) when an existing config sits on a
+  blocked port; we do NOT auto-re-port (that would change a running agent's port — left
+  to the operator).
+
+## 1. Over-correction risk
+The blocklist is the fixed WHATWG set; legitimate agent ports (4040–4044, 4046–4099, etc.)
+are unaffected. Only 4045 falls in the default range. Skipping reduces the usable range by
+one port — negligible (60→59).
+
+## 2. Under-correction risk
+Existing agents already on a blocked port aren't auto-fixed (that would change their port);
+the startup warning surfaces it so the operator re-ports. Acceptable — auto-re-porting a
+live agent is riskier than a loud warning.
+
+## 3. Level-of-abstraction fit
+The skip lives in the single port allocator both callers use; the warning at the single
+server-start path. No scattering.
+
+## 4. Signal vs Authority
+Pure deterministic check against a fixed spec list — no LLM, no heuristic. Appropriate.
+
+## 5. External surfaces
+None. No route/config-schema change. `isFetchBlockedPort` is a new pure export.
+
+## 6. Interactions with existing primitives
+The allocator's existing used-port + lsof checks are unchanged; the blocklist is an
+additional AND condition. The warning composes with the existing startup logs.
+
+## 7. Rollback cost
+Trivial: remove the `&& !FETCH_BLOCKED_PORTS.has(port)` clauses + the warning. No state.
+
+## Migration parity
+- New agents: allocator skips blocked ports (no action needed).
+- Existing agents on a blocked port: the startup warning surfaces it (operator re-ports).
+- Pure code; reaches existing agents on the normal dist update. No config/hook migration.
+
+## Tests
+`tsc --noEmit` clean. 34 `agent-registry` unit tests green, including 3 new: `isFetchBlockedPort`
+both sides of the boundary (4045/6000/6697/2049 blocked; 4040/4046/4050/4099 not),
+`allocatePort` throws rather than return a sole blocked candidate, and `allocatePort` skips
+a blocked port to return the next usable one.