instar 1.3.883 → 1.3.885

package/scripts/lint-migration-consumer-completeness.js

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+// safe-git-allow: pre-commit bootstrap uses read-only diff/show before TypeScript is compiled.
+/**
+ * Structural ratchet for the Migration-Consumer Completeness standard.
+ *
+ * The manifest names every enrolled canonical migration producer, every
+ * authorization/validation consumer of that authority, and the tests that
+ * validate the compatibility boundary. Role markers bind those declarations to
+ * actual files. Staged/CI diff mode treats any producer or consumer edit as a
+ * contract revision: the manifest revision must increase and every declared
+ * producer, consumer, and validator must acknowledge that revision in lockstep.
+ *
+ * This lint is deliberately mechanical. It proves that the declared dependency
+ * set moved in lockstep; review remains the semantic authority for deciding
+ * whether the declaration itself is complete.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const MANIFEST_PATH = 'docs/canonical-migration-contracts.json';
+const MARKER_RE = /canonical-migration-(producer|consumer|validator):\s*([a-z0-9][a-z0-9-]*)@(\d+)/g;
+const SCAN_ROOTS = ['src', 'tests', 'docs'];
+const SCAN_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.mjs', '.cjs', '.md']);
+
+/** @typedef {'producer'|'consumer'|'validator'} MigrationRole */
+/**
+ * @typedef MigrationContract
+ * @property {string} id
+ * @property {number} revision
+ * @property {string[]} producers
+ * @property {string[]} consumers
+ * @property {string[]} validators
+ */
+/** @typedef {{role: MigrationRole, id: string, revision: number, path: string}} MigrationMarker */
+/** @typedef {{rule: string, message: string, id?: string, path?: string}} Finding */
+
+const roleField = /** @type {const} */ ({
+  producer: 'producers',
+  consumer: 'consumers',
+  validator: 'validators',
+});
+
+/** @param {unknown} manifest @returns {Finding[]} */
+export function validateMigrationManifest(manifest) {
+  if (!manifest || typeof manifest !== 'object') {
+    return [{ rule: 'MCC0-manifest-shape', message: 'manifest must be an object' }];
+  }
+  const candidate = /** @type {{schemaVersion?: unknown, contracts?: unknown}} */ (manifest);
+  if (candidate.schemaVersion !== 1) {
+    return [{ rule: 'MCC0-manifest-shape', message: 'schemaVersion must equal 1' }];
+  }
+  if (!Array.isArray(candidate.contracts) || candidate.contracts.length === 0) {
+    return [{ rule: 'MCC0-manifest-shape', message: 'contracts must be a non-empty array' }];
+  }
+  return [];
+}
+
+/**
+ * @param {{contracts: MigrationContract[], baseContracts?: MigrationContract[], markers: MigrationMarker[], changedFiles: Set<string>, pathExists: (path: string) => boolean}} input
+ * @returns {Finding[]}
+ */
+export function auditMigrationConsumerCompleteness(input) {
+  const findings = [];
+  const contractsById = new Map();
+
+  for (const contract of input.contracts) {
+    if (!contract?.id || contractsById.has(contract.id)) {
+      findings.push({
+        rule: 'MCC0-invalid-contract-id',
+        id: contract?.id,
+        message: `contract id must be non-empty and unique: ${contract?.id ?? '(missing)'}`,
+      });
+      continue;
+    }
+    contractsById.set(contract.id, contract);
+    if (!Number.isInteger(contract.revision) || contract.revision < 1) {
+      findings.push({ rule: 'MCC0-invalid-revision', id: contract.id, message: `${contract.id}.revision must be a positive integer` });
+    }
+    for (const field of ['producers', 'consumers', 'validators']) {
+      if (!Array.isArray(contract[field])) {
+        findings.push({ rule: 'MCC0-invalid-contract-shape', id: contract.id, message: `${contract.id}.${field} must be an array` });
+      }
+    }
+    if (!Array.isArray(contract.producers) || contract.producers.length === 0) {
+      findings.push({ rule: 'MCC0-producer-required', id: contract.id, message: `${contract.id} must declare at least one producer` });
+    }
+    if (!Array.isArray(contract.consumers) || contract.consumers.length === 0) {
+      findings.push({ rule: 'MCC2-consumer-required', id: contract.id, message: `${contract.id} must declare at least one consumer` });
+    }
+    if (!Array.isArray(contract.validators) || contract.validators.length === 0) {
+      findings.push({ rule: 'MCC3-validator-required', id: contract.id, message: `${contract.id} must declare at least one validator` });
+    }
+  }
+
+  const markersByKey = new Map();
+  for (const marker of input.markers) {
+    const key = `${marker.id}\0${marker.role}\0${marker.path}`;
+    markersByKey.set(key, marker);
+    const contract = contractsById.get(marker.id);
+    if (!contract) {
+      findings.push({
+        rule: 'MCC1-unregistered-marker', id: marker.id, path: marker.path,
+        message: `${marker.path} declares ${marker.role} for unregistered migration ${marker.id}`,
+      });
+      continue;
+    }
+    const field = roleField[marker.role];
+    if (!contract[field]?.includes(marker.path)) {
+      findings.push({
+        rule: 'MCC4-marker-contract-mismatch', id: marker.id, path: marker.path,
+        message: `${marker.path} carries a ${marker.role} marker but is absent from ${marker.id}.${field}`,
+      });
+    }
+    if (marker.revision !== contract.revision) {
+      findings.push({
+        rule: 'MCC5-stale-role-revision', id: marker.id, path: marker.path,
+        message: `${marker.path} acknowledges ${marker.id}@${marker.revision}, expected @${contract.revision}`,
+      });
+    }
+  }
+
+  for (const contract of input.contracts) {
+    for (const role of /** @type {MigrationRole[]} */ (['producer', 'consumer', 'validator'])) {
+      const field = roleField[role];
+      for (const declaredPath of contract[field] ?? []) {
+        if (!input.pathExists(declaredPath)) {
+          findings.push({
+            rule: 'MCC4-declared-path-missing', id: contract.id, path: declaredPath,
+            message: `${contract.id}.${field} names missing path ${declaredPath}`,
+          });
+        }
+        const key = `${contract.id}\0${role}\0${declaredPath}`;
+        if (!markersByKey.has(key)) {
+          findings.push({
+            rule: 'MCC5-missing-role-marker', id: contract.id, path: declaredPath,
+            message: `${declaredPath} must carry canonical-migration-${role}: ${contract.id}@${contract.revision}`,
+          });
+        }
+      }
+    }
+
+  }
+
+  if (input.baseContracts) {
+    const baseById = new Map(input.baseContracts.map((contract) => [contract.id, contract]));
+    for (const base of input.baseContracts) {
+      if (!contractsById.has(base.id)) {
+        findings.push({
+          rule: 'MCC8-contract-removal-forbidden', id: base.id,
+          message: `${base.id} existed at the diff base and cannot be silently removed`,
+        });
+      }
+      const head = contractsById.get(base.id);
+      if (!head) continue;
+      for (const role of /** @type {MigrationRole[]} */ (['producer', 'consumer', 'validator'])) {
+        const field = roleField[role];
+        for (const basePath of base[field] ?? []) {
+          if (!(head[field] ?? []).includes(basePath)) {
+            findings.push({
+              rule: 'MCC8-role-removal-forbidden', id: base.id, path: basePath,
+              message: `${base.id}.${field} cannot silently remove ${basePath}; retire the contract in a separately reviewed migration`,
+            });
+          }
+        }
+      }
+    }
+    for (const contract of input.contracts) {
+      const base = baseById.get(contract.id);
+      const authorityChanged = [...(contract.producers ?? []), ...(contract.consumers ?? [])]
+        .some((file) => input.changedFiles.has(file));
+      const revisionChanged = !base || contract.revision !== base.revision;
+      if (base && authorityChanged && contract.revision <= base.revision) {
+        findings.push({
+          rule: 'MCC6-revision-bump-required', id: contract.id,
+          message: `${contract.id} producer/consumer surface changed without increasing revision above ${base.revision}`,
+        });
+      }
+      if (base && contract.revision < base.revision) {
+        findings.push({
+          rule: 'MCC6-revision-regression', id: contract.id,
+          message: `${contract.id} revision regressed from ${base.revision} to ${contract.revision}`,
+        });
+      }
+      if (!revisionChanged) continue;
+      for (const role of /** @type {MigrationRole[]} */ (['producer', 'consumer', 'validator'])) {
+        for (const declaredPath of contract[roleField[role]] ?? []) {
+          if (!input.changedFiles.has(declaredPath)) {
+            findings.push({
+              rule: role === 'validator' ? 'MCC7-lockstep-validator' : 'MCC6-lockstep-authority',
+              id: contract.id,
+              path: declaredPath,
+              message: `${contract.id}@${contract.revision} revision changed without lockstep ${role} acknowledgement in ${declaredPath}`,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return findings;
+}
+
+/** @param {string} root */
+function scanMarkers(root) {
+  /** @type {MigrationMarker[]} */
+  const markers = [];
+  const visit = (relativeDir) => {
+    const absoluteDir = path.join(root, relativeDir);
+    if (!fs.existsSync(absoluteDir)) return;
+    for (const entry of fs.readdirSync(absoluteDir, { withFileTypes: true })) {
+      const relativePath = path.posix.join(relativeDir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name !== 'node_modules' && !entry.name.startsWith('.')) visit(relativePath);
+        continue;
+      }
+      if (!SCAN_EXTENSIONS.has(path.extname(entry.name))) continue;
+      const text = fs.readFileSync(path.join(root, relativePath), 'utf8');
+      MARKER_RE.lastIndex = 0;
+      let match;
+      while ((match = MARKER_RE.exec(text)) !== null) {
+        markers.push({ role: /** @type {MigrationRole} */ (match[1]), id: match[2], revision: Number(match[3]), path: relativePath });
+      }
+    }
+  };
+  for (const scanRoot of SCAN_ROOTS) visit(scanRoot);
+  return markers;
+}
+
+/** @param {string} root @param {string[]} args */
+function diffContext(root, args) {
+  let gitArgs = null;
+  let base = null;
+  const baseIndex = args.indexOf('--diff-base');
+  if (args.includes('--staged')) {
+    base = 'HEAD';
+    gitArgs = ['diff', '--cached', '--name-only', '--diff-filter=ACMR'];
+  } else if (baseIndex >= 0 && args[baseIndex + 1]) {
+    base = args[baseIndex + 1];
+    gitArgs = ['diff', '--name-only', '--diff-filter=ACMR', base, 'HEAD'];
+  }
+  if (!gitArgs) return { changedFiles: new Set(), baseContracts: undefined };
+  const output = execFileSync('git', gitArgs, { cwd: root, encoding: 'utf8' });
+  let baseContracts = [];
+  try {
+    const raw = execFileSync('git', ['show', `${base}:${MANIFEST_PATH}`], {
+      cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const parsed = JSON.parse(raw);
+    if (parsed?.schemaVersion === 1 && Array.isArray(parsed.contracts)) baseContracts = parsed.contracts;
+  } catch { /* first registry ship: no base manifest */ }
+  return {
+    changedFiles: new Set(output.split('\n').map((line) => line.trim()).filter(Boolean)),
+    baseContracts,
+  };
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const rootIndex = args.indexOf('--root');
+  const root = rootIndex >= 0 && args[rootIndex + 1] ? path.resolve(args[rootIndex + 1]) : SCRIPT_ROOT;
+  const manifestAbsolute = path.join(root, MANIFEST_PATH);
+  if (!fs.existsSync(manifestAbsolute)) {
+    console.error(`MCC0-manifest-missing: ${MANIFEST_PATH}`);
+    process.exit(1);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestAbsolute, 'utf8'));
+  } catch (error) {
+    console.error(`MCC0-manifest-invalid: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+  const shapeFindings = validateMigrationManifest(manifest);
+  if (shapeFindings.length > 0) {
+    console.error(`${shapeFindings[0].rule}: ${shapeFindings[0].message}`);
+    process.exit(1);
+  }
+  const diff = diffContext(root, args);
+  const findings = auditMigrationConsumerCompleteness({
+    contracts: manifest.contracts,
+    baseContracts: diff.baseContracts,
+    markers: scanMarkers(root),
+    changedFiles: diff.changedFiles,
+    pathExists: (relativePath) => fs.existsSync(path.join(root, relativePath)),
+  });
+  if (findings.length === 0) {
+    console.log('lint-migration-consumer-completeness: clean');
+    return;
+  }
+  console.error(`lint-migration-consumer-completeness: ${findings.length} finding(s)`);
+  for (const finding of findings) {
+    console.error(`  ${finding.rule}${finding.path ? ` ${finding.path}` : ''}: ${finding.message}`);
+  }
+  process.exit(1);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main();

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-19T21:20:00.388Z",
-  "instarVersion": "1.3.883",
+  "generatedAt": "2026-07-19T23:24:44.134Z",
+  "instarVersion": "1.3.885",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "642833df6bd9099d8b35dbc5da5d1d5d17f0c2a4cd93145693854dc028dbaec5",
+      "contentHash": "68624dacc4e2bb0f43676a5bd8509a53c1cf37aa09f80f678c66c37f8a2168e2",
       "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": "642833df6bd9099d8b35dbc5da5d1d5d17f0c2a4cd93145693854dc028dbaec5",
+      "contentHash": "68624dacc4e2bb0f43676a5bd8509a53c1cf37aa09f80f678c66c37f8a2168e2",
       "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": "642833df6bd9099d8b35dbc5da5d1d5d17f0c2a4cd93145693854dc028dbaec5",
+      "contentHash": "68624dacc4e2bb0f43676a5bd8509a53c1cf37aa09f80f678c66c37f8a2168e2",
       "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": "642833df6bd9099d8b35dbc5da5d1d5d17f0c2a4cd93145693854dc028dbaec5",
+      "contentHash": "68624dacc4e2bb0f43676a5bd8509a53c1cf37aa09f80f678c66c37f8a2168e2",
       "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": "642833df6bd9099d8b35dbc5da5d1d5d17f0c2a4cd93145693854dc028dbaec5",
+      "contentHash": "68624dacc4e2bb0f43676a5bd8509a53c1cf37aa09f80f678c66c37f8a2168e2",
       "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": "642833df6bd9099d8b35dbc5da5d1d5d17f0c2a4cd93145693854dc028dbaec5",
+      "contentHash": "68624dacc4e2bb0f43676a5bd8509a53c1cf37aa09f80f678c66c37f8a2168e2",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "642833df6bd9099d8b35dbc5da5d1d5d17f0c2a4cd93145693854dc028dbaec5",
+      "contentHash": "68624dacc4e2bb0f43676a5bd8509a53c1cf37aa09f80f678c66c37f8a2168e2",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "642833df6bd9099d8b35dbc5da5d1d5d17f0c2a4cd93145693854dc028dbaec5",
+      "contentHash": "68624dacc4e2bb0f43676a5bd8509a53c1cf37aa09f80f678c66c37f8a2168e2",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "642833df6bd9099d8b35dbc5da5d1d5d17f0c2a4cd93145693854dc028dbaec5",
+      "contentHash": "68624dacc4e2bb0f43676a5bd8509a53c1cf37aa09f80f678c66c37f8a2168e2",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "642833df6bd9099d8b35dbc5da5d1d5d17f0c2a4cd93145693854dc028dbaec5",
+      "contentHash": "68624dacc4e2bb0f43676a5bd8509a53c1cf37aa09f80f678c66c37f8a2168e2",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "642833df6bd9099d8b35dbc5da5d1d5d17f0c2a4cd93145693854dc028dbaec5",
+      "contentHash": "68624dacc4e2bb0f43676a5bd8509a53c1cf37aa09f80f678c66c37f8a2168e2",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "642833df6bd9099d8b35dbc5da5d1d5d17f0c2a4cd93145693854dc028dbaec5",
+      "contentHash": "68624dacc4e2bb0f43676a5bd8509a53c1cf37aa09f80f678c66c37f8a2168e2",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "642833df6bd9099d8b35dbc5da5d1d5d17f0c2a4cd93145693854dc028dbaec5",
+      "contentHash": "68624dacc4e2bb0f43676a5bd8509a53c1cf37aa09f80f678c66c37f8a2168e2",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "642833df6bd9099d8b35dbc5da5d1d5d17f0c2a4cd93145693854dc028dbaec5",
+      "contentHash": "68624dacc4e2bb0f43676a5bd8509a53c1cf37aa09f80f678c66c37f8a2168e2",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "642833df6bd9099d8b35dbc5da5d1d5d17f0c2a4cd93145693854dc028dbaec5",
+      "contentHash": "68624dacc4e2bb0f43676a5bd8509a53c1cf37aa09f80f678c66c37f8a2168e2",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "642833df6bd9099d8b35dbc5da5d1d5d17f0c2a4cd93145693854dc028dbaec5",
+      "contentHash": "68624dacc4e2bb0f43676a5bd8509a53c1cf37aa09f80f678c66c37f8a2168e2",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1242,7 +1242,7 @@
       "type": "template",
       "domain": "operations",
       "sourcePath": "src/templates/scripts/telegram-reply.sh",
-      "contentHash": "d55feb9a203c7835c36b6bf0e23972c79a1e26fe6ea29683f31f831fb956c0f3",
+      "contentHash": "1182b2c7e3779a9c37355e7317962ea48122a5f4a42425d7f3f9973e8127aa19",
       "since": "2025-01-01"
     },
     "template:whatsapp-reply.sh": {
@@ -1562,7 +1562,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "642833df6bd9099d8b35dbc5da5d1d5d17f0c2a4cd93145693854dc028dbaec5",
+      "contentHash": "68624dacc4e2bb0f43676a5bd8509a53c1cf37aa09f80f678c66c37f8a2168e2",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/src/templates/scripts/telegram-reply.sh

@@ -373,6 +373,8 @@ ATTEMPTED_AT=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
 # from config — the server uses it to reject wrong-port requests before
 # evaluating the token.
 CURL_ARGS=(-s -w "\n%{http_code}" -X POST "http://localhost:${PORT}/telegram/reply/${TOPIC_ID}"
+  --connect-timeout 3
+  --max-time 125
   -H 'Content-Type: application/json'
   -d "$JSON_BODY")
 if [ -n "$AUTH_TOKEN" ]; then
@@ -386,6 +388,19 @@ if [ -n "$DELIVERY_ID" ]; then
 fi
 
 RESPONSE=$(curl "${CURL_ARGS[@]}")
+CURL_STATUS=$?
+
+# A transport failure after request start is inherently ambiguous: the server
+# may still finish its tone review or Telegram send after our bounded client
+# window closes. Always render a terminal outcome so a yielded/reattached tool
+# call cannot complete silently, and never auto-enqueue/retry an unknown send.
+if [ "$CURL_STATUS" -ne 0 ]; then
+  echo "AMBIGUOUS: Telegram relay transport ended without an HTTP outcome (curl ${CURL_STATUS})." >&2
+  echo "  The message MAY still be delivered. Do NOT retry blindly; verify the conversation first." >&2
+  [ -n "$DELIVERY_ID" ] && echo "  Delivery id: ${DELIVERY_ID}" >&2
+  echo "AMBIGUOUS: no HTTP outcome — verify delivery before retrying"
+  exit 0
+fi
 
 HTTP_CODE=$(echo "$RESPONSE" | tail -1)
 BODY=$(echo "$RESPONSE" | sed '$d')

package/upgrades/1.3.884.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+- Telegram reply requests now have finite connection and total deadlines.
+- Transport failures always return an explicit ambiguous outcome with a delivery id and safe retry guidance.
+- Stock installed relay scripts upgrade in place; locally customized scripts remain protected.
+
+## What to Tell Your User
+
+If a Telegram reply loses its connection before Instar can return a result, the agent now sees a clear uncertain-delivery warning instead of an empty tool outcome. It will verify before retrying rather than risk sending the message twice.
+
+## Summary of New Capabilities
+
+- Bounded, observable Telegram reply outcomes even when the transport fails before an HTTP response.
+
+## Evidence
+
+- Feedback: `fb-9c139a25-11e`
+- Behavioral test: `tests/unit/telegram-reply-bounded-outcome.test.ts`
+- Existing recovery/status regression suite remains green.

package/upgrades/1.3.885.md

@@ -0,0 +1,25 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+- Added Migration-Consumer Completeness as a constitutional standard.
+- Added a contract registry and lint that require canonical migration producers, consumers, and validators to move together.
+- Enrolled Threadline's canonical inbound store and reply-validation boundary as the first protected contract.
+
+## What to Tell Your User
+
+Instar's internal migrations now carry a stronger completion check. When one component becomes the new source of truth, the development process verifies that every declared authorization and validation consumer moves with it, reducing failures where half the system uses the new authority while another half silently uses the old one.
+
+## Summary of New Capabilities
+
+- Canonical migrations have an explicit, reviewable producer/consumer/validator contract.
+- Local commits and CI refuse producer-only migrations that leave declared consumers or validators behind.
+
+## Evidence
+
+- `docs/STANDARDS-REGISTRY.md` — Migration-Consumer Completeness.
+- `scripts/lint-migration-consumer-completeness.js`.
+- `tests/unit/migration-consumer-completeness-lint.test.ts`.

package/upgrades/migration-consumer-completeness.eli16.md

@@ -0,0 +1,9 @@
+# Migration-consumer completeness
+
+A system migration is not finished merely because a new canonical store exists and its own tests pass. Other parts of the system may still consult the old store when they authorize a reply, validate a request, route work, or decide whether evidence is genuine. That creates two competing truths: the producer believes the new authority is canonical, while a consumer still behaves as if the retired authority is canonical. PR #1523 repaired one such Threadline instance, but it only named the general rule in prose; the repository had no standard or guard capable of catching the next occurrence.
+
+This change makes that class explicit and enforceable. A new Migration-Consumer Completeness entry in the standards registry says that a canonical migration must enumerate its producers, every authorization and validation consumer, and the tests that prove the compatibility boundary. A machine-readable contract registry binds those roles to real repository paths. Each enrolled file carries a matching role marker, so a manifest cannot quietly claim coverage for a file that never acknowledged the migration.
+
+The lint checks two layers. On every normal lint run it verifies that contracts are well formed, paths exist, role markers match, and every producer has at least one consumer and validator. During a staged commit and in the full pull-request diff, a producer or consumer edit must increment the contract revision, and every declared producer, consumer, and validator must acknowledge that revision in the same unit of work. This would have stopped the original ThreadLog migration from shipping while reply authorization and recovery still read only the legacy listener inbox.
+
+The guard is deliberately honest about its boundary. It can prove that the declared set moved together, but a static parser cannot know whether a developer omitted an unknown consumer from the declaration. Independent review remains responsible for semantic completeness. The structural guard makes the dependency set explicit, reviewable, and mechanically synchronized instead of leaving it to memory.

package/upgrades/side-effects/migration-consumer-completeness.md

@@ -0,0 +1,82 @@
+# Side-Effects Review — Migration-consumer completeness
+
+**Version / slug:** `migration-consumer-completeness`
+**Date:** `2026-07-19`
+**Author:** `Instar Agent (instar-codey)`
+**Second-pass reviewer:** independent sub-agent review — concurred after two correction rounds
+
+## Summary of the change
+
+This change registers Migration-Consumer Completeness in `docs/STANDARDS-REGISTRY.md`, adds the machine-readable contract registry at `docs/canonical-migration-contracts.json`, and adds `scripts/lint-migration-consumer-completeness.js` to normal lint, staged commit, and pull-request-diff gates. The existing Threadline canonical-store migration is enrolled as the first contract. It also closes two real compatibility consumers: reply authorization already accepts legacy-plus-ThreadLog evidence, and reap recovery now accepts the same union, resolving inline bodies directly and store-backed bodies only after MessageStore identity and content-digest verification.
+
+## Decision-point inventory
+
+- Migration lockstep gate — added hard structural invariant — a changed canonical producer or consumer requires a revision bump acknowledged by every declared producer, consumer, and validator in the same diff.
+- Contract completeness review — passed through — the lint reports declared structure; independent review remains semantic authority over whether the declaration includes every real consumer.
+- Reap recovery authority — changed from legacy-inbox-only to the canonical legacy-plus-ThreadLog union; modern store references resolve through MessageStore and fail closed on absence, identity mismatch, or digest mismatch.
+
+## 1. Over-block
+
+A producer or consumer file changed for a reason unrelated to its canonical authority still requires a contract revision and an explicit marker acknowledgement across the declared boundary. This is deliberate conservative friction at an authority boundary, but it makes the review event visible rather than pretending that a same-diff touch proves semantic behavior. The contract can be narrowed later by extracting the authority into smaller dedicated modules; there is no bypass flag.
+
+## 2. Under-block
+
+The lint cannot infer an undeclared semantic consumer. A developer could omit a consumer from both the manifest and markers and still pass the mechanical gate. The registry and marker set make that omission visible to review, but semantic completeness remains an independent-review responsibility. Revision acknowledgement also does not prove that a changed validator meaningfully exercises the behavior; test review and CI remain responsible for that. Store-backed recovery intentionally remains unavailable when MessageStore evidence is missing, corrupt, identity-inconsistent, or digest-inconsistent; the resume item stays retryable rather than executing unverified content.
+
+## 3. Level-of-abstraction fit
+
+The manifest is the right deterministic layer for dependency declaration, and the lint is the right layer for path, marker, and diff invariants. A static parser is not promoted into semantic authority: it never guesses which files are consumers. Review judges the declaration; the gate enforces the declared contract.
+
+## 4. Signal vs authority compliance
+
+Per `docs/signal-vs-authority.md`, the hard block is a fully enumerable repository invariant: declared paths and markers either exist and move together or they do not. The non-enumerable question—whether the declaration covers every semantic consumer—remains with contextual review. No brittle keyword detector decides semantic completeness.
+
+## 4b. Judgment-point check
+
+No static heuristic is added at a competing-signals decision point. Lockstep membership is an invariant over an explicit contract. Semantic consumer discovery remains a judgment candidate owned by review rather than this lint.
+
+## 5. Interactions
+
+- **Shadowing:** normal `npm run lint` checks registry integrity before CI; the staged and PR-diff invocations add lockstep evidence. They are complementary rather than shadowing.
+- **Double-fire:** a malformed registry may be reported by both local lint and the staged invocation. Both are read-only and deterministic; duplicate diagnostics have no side effect.
+- **Races:** the lint reads immutable checkout/staging state and writes nothing. Recovery continues to use the existing durable reply-claim ledger; MessageStore resolution occurs before the claim, then the existing claim/transfer/release sequence prevents double execution.
+- **Feedback loops:** none. It does not mutate contracts or source markers.
+
+## 6. External surfaces
+
+Instar developers see actionable commit/CI failures when a canonical producer or consumer moves without its declared dependency set. At runtime, an interrupted modern Threadline inbound can now be redriven even when the legacy inbox has no copy. No new external service, credential, operator action, or URL is introduced; recovery reads only local canonical ThreadLog and MessageStore state.
+
+## 6b. Operator-surface quality
+
+No operator surface — not applicable.
+
+## 7. Multi-machine posture
+
+Replicated through git: the standard, manifest, markers, and lint are repository artifacts and therefore identical in every worktree and CI runner. Threadline evidence remains machine-local under the existing single-holder model; recovery reads the local ThreadLog and MessageStore associated with the interrupted worker and does not invent cross-machine lookup or replication. The change adds no user-facing notice or URL.
+
+## 8. Rollback cost
+
+Revert the policy/guard and recovery union, then ship a patch. No data migration or agent-state repair is required because the runtime change is read-only over existing ThreadLog/MessageStore records and writes only through the pre-existing reply-claim and router paths. Rolling back restores legacy-only reap recovery and therefore reopens the modern-only stranded-work defect.
+
+## Conclusion
+
+The original #1523 CLASS review named Migration-Consumer Completeness but did not add it to the constitution or enforce it structurally. This change closes that meta-gap with an explicit standard and a real lockstep guard, while preserving review as the semantic authority. Independent review is required because the change adds a blocking repository guard.
+
+## Second-pass review
+
+**Reviewer:** `/root/migration_guard_review`
+**Independent read:** Concurred. The first pass required enrollment of the real append/recovery consumers, revision-based acknowledgements, root/removal guards, and honest runtime documentation. The second pass found role-member removal and store-backed recovery bypasses. Final review verified both adversarial closures, MessageStore identity/digest binding, production wiring, retry posture, and the updated side-effects analysis; no merge blocker remains.
+
+## Evidence pointers
+
+- `tests/unit/migration-consumer-completeness-lint.test.ts`
+- `tests/unit/threadline/ThreadlineReplyValidation.test.ts`
+- `tests/integration/threadline-relay-send-priority.test.ts`
+- `tests/integration/threadline-reap-recovery-wiring.test.ts`
+- `tests/integration/threadline/canonical-history-wiring.test.ts`
+- `tests/e2e/threadline-reap-mid-processing.test.ts`
+- PR #1523
+
+## Class-Closure Declaration (display-only mirror)
+
+`defectClass: claim-vs-evidence`, `closure: guard`, `guardEvidence: { enforcementType: lint, citation: scripts/lint-migration-consumer-completeness.js#auditMigrationConsumerCompleteness, howCaught: a canonical migration producer cannot substantiate completeness without registered consumer and validator paths, matching role markers, and same-diff lockstep evidence }`.