@ijfw/memory-server 1.5.4 → 1.5.5

package/src/cross-orchestrator-cli.js

@@ -1614,6 +1614,111 @@ function writeStateFields(updates) {
   });
 }
 
+// V155-001 (BLOCKER) — `ijfw update` was writing `installed_version` /
+// `last_applied_version` based on the install subprocess returning exit 0
+// across all 3 install methods (npm-global, git-clone, manual). Exit 0 from
+// `npm install -g @ijfw/install@X` is "npm did not crash" — NOT "@ijfw/install
+// on disk is now version X". On registry blips, npm-cache poisoning, or a
+// no-op install (already-installed, lockfile pin), `state.json` would advance
+// to a version that does not exist on the filesystem. Every subsequent
+// `ijfw update --check` then saw "we're up to date" and refused to retry.
+//
+// Fix: AFTER the install subprocess returns 0, re-read the *actual*
+// installed package.json (preferring npm-global root for the npm-global path,
+// repo-tree installer/package.json for git-clone, and either for manual)
+// and confirm `pkg.version === expectedVersion` before writing state.json.
+// If they disagree, refuse the state write and surface the discrepancy.
+//
+// Returns { ok: true, actualVersion } on success, { ok: false, actualVersion,
+// reason } on mismatch / unreadable.
+//
+// Exported (v1.5.5 V155-001 follow-up) so the regression test
+// `test-v155-update-flow.js` can drive the function directly without spawning
+// the full CLI. Behavior unchanged.
+export function verifyInstallSucceeded({ method, repoRoot, expectedVersion }) {
+  // TR-006: type-validate `expectedVersion` at function entry. Without this,
+  // a stray trailing newline (from sloppy `npmViewVersion` parse) makes the
+  // strict `pkg.version === expectedVersion` check fail for the wrong reason
+  // and surfaces operator-hostile mismatch messages like
+  // "expected v1.5.5\n got v1.5.5". Normalize + validate before any probe.
+  expectedVersion = String(expectedVersion || '').trim();
+  if (!isVersionStringValid(expectedVersion)) {
+    return {
+      ok: false,
+      actualVersion: null,
+      reason: `expectedVersion not a valid semver string (got: ${JSON.stringify(expectedVersion)})`,
+    };
+  }
+  // TR-002: probe candidates are now method-strict. The previous shape
+  // silently fell back to `repoRoot/installer/package.json` for ALL methods,
+  // so a stale git clone at the expected version would mask an npm-global
+  // install that never happened. Each method now declares its own source of
+  // truth; `manual` keeps the multi-candidate fallback because dev-mode
+  // installs legitimately ride on either npm-global or a sibling git clone.
+  const candidates = [];
+  const probeNpmGlobal = () => {
+    try {
+      const r = spawnSync('npm', ['root', '-g'], {
+        encoding: 'utf8',
+        timeout: 5_000,
+        shell: process.platform === 'win32',
+      });
+      if (r.status === 0) {
+        const globalRoot = (r.stdout || '').trim();
+        if (globalRoot) {
+          candidates.push(join(globalRoot, '@ijfw', 'install', 'package.json'));
+        }
+      }
+    } catch { /* ignore — surfaces as no-candidates */ }
+  };
+  if (method === 'npm-global') {
+    // npm-global verification MUST read the npm-global package.json
+    // exclusively. A sibling repo tree at the expected version is a category
+    // error here — it would mean we record "npm-global install succeeded"
+    // when the only thing on disk at that version is an unrelated git clone.
+    probeNpmGlobal();
+  } else if (method === 'git-clone' && repoRoot) {
+    candidates.push(join(repoRoot, 'installer', 'package.json'));
+  } else if (method === 'manual') {
+    // Dev-mode: try npm-global first, then the repo tree. Either is a
+    // legitimate source of truth for a manually-driven install.
+    probeNpmGlobal();
+    if (repoRoot) {
+      const fallback = join(repoRoot, 'installer', 'package.json');
+      if (!candidates.includes(fallback)) candidates.push(fallback);
+    }
+  }
+
+  if (candidates.length === 0) {
+    return {
+      ok: false,
+      actualVersion: null,
+      reason:
+        method === 'npm-global'
+          ? 'npm-global package.json not readable (npm root -g failed)'
+          : `no package.json candidates for method=${method}`,
+    };
+  }
+
+  const seen = [];
+  for (const p of candidates) {
+    const pkg = readJsonSafe(p);
+    if (!pkg) {
+      seen.push(`${p} (unreadable)`);
+      continue;
+    }
+    seen.push(`${p} (v${pkg.version || 'unknown'})`);
+    if (pkg.version === expectedVersion) {
+      return { ok: true, actualVersion: pkg.version, source: p };
+    }
+  }
+  return {
+    ok: false,
+    actualVersion: null,
+    reason: `no package.json reported version v${expectedVersion}. Probed: ${seen.join(', ')}`,
+  };
+}
+
 function cmdUpdateCheck() {
   const state = readState();
   const current = state.installed_version || '0.0.0';
@@ -1631,7 +1736,7 @@ function cmdUpdateCheck() {
   // rely on exit codes. Previously exited 3 which broke POSIX if-statements.
   console.log(`update-available: ${r.version}`);
   console.log(`Update available: v${current} -> v${r.version}`);
-  console.log(`  Release notes: https://gitlab.com/therealseandonahoe/ijfw/-/releases/v${r.version}`);
+  console.log(`  Release notes: https://github.com/FerroxLabs/ijfw/releases/tag/v${r.version}`);
   console.log(`  Run: ijfw update`);
   process.exit(0);
 }
@@ -1683,17 +1788,24 @@ function cmdUpdateChangelog() {
     console.error(`could not fetch latest version: ${r.message}`);
     process.exit(1);
   }
-  const url = `https://gitlab.com/api/v4/projects/therealseandonahoe%2Fijfw/releases/v${r.version}`;
-  const fetchRes = spawnSync('curl', ['-fsSL', '-H', 'User-Agent: ijfw', url], { encoding: 'utf8', timeout: 10_000 });
+  // V155 rebrand: ported from GitLab API (releases/v<ver>, data.description)
+  // to GitHub API (releases/tags/v<ver>, data.body). GitHub's repo path is
+  // NOT URL-encoded, unlike GitLab's %2F-separated project id.
+  const url = `https://api.github.com/repos/FerroxLabs/ijfw/releases/tags/v${r.version}`;
+  const fetchRes = spawnSync(
+    'curl',
+    ['-fsSL', '-H', 'User-Agent: ijfw', '-H', 'Accept: application/vnd.github+json', url],
+    { encoding: 'utf8', timeout: 10_000 },
+  );
   if (fetchRes.status !== 0) {
     console.log(`No release notes available for v${r.version}.`);
-    console.log(`Visit: https://gitlab.com/therealseandonahoe/ijfw/-/releases/v${r.version}`);
+    console.log(`Visit: https://github.com/FerroxLabs/ijfw/releases/tag/v${r.version}`);
     process.exit(0);
   }
   let body = '';
   try {
     const data = JSON.parse(fetchRes.stdout || '{}');
-    body = data.description || '(no body)';
+    body = data.body || '(no body)';
   } catch { body = '(could not parse release JSON)'; }
   // ANSI strip + cap 4KB. Control-char regex is intentional -- defangs
   // CHANGELOG bytes fetched over HTTPS so paste into the terminal can't
@@ -1707,7 +1819,7 @@ function cmdUpdateChangelog() {
   console.log(`Changelog for v${r.version}`);
   console.log('');
   console.log(stripped);
-  if (body.length > 4096) console.log(`\n... (truncated; full notes at https://gitlab.com/therealseandonahoe/ijfw/-/releases/v${r.version})`);
+  if (body.length > 4096) console.log(`\n... (truncated; full notes at https://github.com/FerroxLabs/ijfw/releases/tag/v${r.version})`);
   process.exit(0);
 }
 
@@ -1734,7 +1846,7 @@ function cmdUpdateConfirm(token) {
   // Locate pending sentinel under any session in ~/.ijfw/run/
   const runRoot = join(ijfwHome(), 'run');
   if (!existsSync(runRoot)) {
-    console.error('No pending update sentinel found. Run `ijfw_update_apply` via your AI first.');
+    console.error('No pending update sentinel found. Run `ijfw_update_check` via your AI first to issue a confirm token.');
     process.exit(1);
   }
   let sentinelPath = null;
@@ -1758,15 +1870,15 @@ function cmdUpdateConfirm(token) {
   if (!sentinelPath) {
     console.error(
       sawPending
-        ? 'Token mismatch -- run ijfw_update_check + ijfw_update_apply via your AI to issue a fresh token.'
-        : 'No pending update sentinel found. The MCP `ijfw_update_apply` tool issues sentinels.'
+        ? 'Token mismatch -- run `ijfw_update_check` via your AI to issue a fresh token.'
+        : 'No pending update sentinel found. Run `ijfw_update_check` via your AI to issue one.'
     );
     process.exit(1);
   }
 
   if (!pending || !isVersionStringValid(pending.target_version)) {
     try { rmSync(sentinelPath, { force: true }); } catch { /* */ }
-    console.error('Pending update sentinel is malformed -- run ijfw_update_check + ijfw_update_apply again.');
+    console.error('Pending update sentinel is malformed -- run `ijfw_update_check` again to issue a fresh one.');
     process.exit(1);
   }
   const tokenCheck = validateToken(sessionId, token);
@@ -1777,7 +1889,7 @@ function cmdUpdateConfirm(token) {
       tokenCheck.error === 'already-consumed' ? 'Token already consumed' :
       tokenCheck.error === 'mismatch' ? 'Token mismatch' :
       'Token validation failed';
-    console.error(`${why} -- run ijfw_update_check + ijfw_update_apply to issue a fresh token.`);
+    console.error(`${why} -- run \`ijfw_update_check\` to issue a fresh token.`);
     process.exit(1);
   }
 
@@ -1849,7 +1961,7 @@ function cmdUpdateInteractive(opts = {}) {
     }
   }
   // Shasum cross-verify (F-SEC-7): independent second factor on top of
-  // npm-side signatures. Fetches the GitLab release asset shasum and
+  // npm-side signatures. Fetches the GitHub release asset shasum and
   // compares it against npm's dist.shasum for the same version. Mismatch
   // means we refuse to install; advisory (release shasum unavailable)
   // requires explicit --yes to proceed.
@@ -1860,7 +1972,7 @@ function cmdUpdateInteractive(opts = {}) {
     console.error('  Shasum: MISMATCH -- refusing install.');
     console.error(`    npm     : ${shasum.npmShasum}`);
     console.error(`    release : ${shasum.releaseShasum}`);
-    console.error('  The npm tarball does NOT match the GitLab release asset.');
+    console.error('  The npm tarball does NOT match the GitHub release asset.');
     console.error('  This could indicate a compromised registry or release. Aborting.');
     return 1;
   } else if (shasum.mode === 'error') {
@@ -1954,10 +2066,28 @@ function cmdUpdateInteractive(opts = {}) {
       console.error(`npm install did not complete (exit ${npmInstall.status}). Run \`npm install --omit=dev --ignore-scripts\` in ${repoRoot} manually.`);
       return 1;
     }
-    installRes = spawnSync('bash', [installSh], { stdio: 'inherit' });
+    // V155-001 (H-002): hardcoded `bash` ENOENTs on Windows where the runtime
+    // is `sh.exe` (Git-Bash) or absent. Use shell:true on Windows so the
+    // .sh extension dispatches via the registered shebang handler; POSIX
+    // keeps the explicit `bash` binary for portability across distros.
+    //
+    // TS-001 (v1.5.5 Trident security): with shell:true on Windows, the
+    // first argument is interpreted by cmd.exe and tokenized on whitespace,
+    // `&`, `(`, `)`, `;`, `%`, etc. Paths containing those characters are
+    // common on Windows (e.g. `C:\Users\Bob & Alice\...` or
+    // `C:\Program Files (x86)\ijfw\...`) — without quotes cmd will execute
+    // an unrelated binary or fail confusingly. Same-uid attacker could plant
+    // `C:\Users\Bob.exe` and have it picked up first. Quote the path so
+    // cmd.exe treats it as a single token.
+    installRes = process.platform === 'win32'
+      ? spawnSync(`"${installSh}"`, [], { stdio: 'inherit', shell: true })
+      : spawnSync('bash', [installSh], { stdio: 'inherit' });
   } else {
     console.log('  Manual install detected -- run: npx @ijfw/install');
-    installRes = spawnSync('npx', ['-y', `@ijfw/install@${r.version}`], { stdio: 'inherit' });
+    installRes = spawnSync('npx', ['-y', `@ijfw/install@${r.version}`], {
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+    });
   }
   if (!installRes) {
     console.error('Update did not complete (install command could not be spawned)');
@@ -1971,6 +2101,23 @@ function cmdUpdateInteractive(opts = {}) {
     console.error(`Update did not complete (exit ${installRes.status}). State not written.`);
     return 1;
   }
+  // V155-001 (A-001 + C-001 + C-002): subprocess exit 0 is "the command did
+  // not crash" — NOT "@ijfw/install on disk is now version r.version".
+  // Re-verify by reading the installed package.json BEFORE writing state.json.
+  // If the filesystem disagrees with what we asked for, refuse the state
+  // write and surface a clear actionable error.
+  const repoRoot = method === 'git-clone' ? repoRootFromCli() : null;
+  const verify = verifyInstallSucceeded({
+    method,
+    repoRoot: repoRoot || repoRootFromCli(),
+    expectedVersion: r.version,
+  });
+  if (!verify.ok) {
+    console.error(`Update did NOT complete: install subprocess exited 0 but filesystem still reports v${verify.actualVersion || 'unknown'} (expected v${r.version}).`);
+    console.error(`  Details: ${verify.reason}`);
+    console.error('  State not written. Inspect with `ijfw status`; rerun `ijfw update` after diagnosing.');
+    return 1;
+  }
   // Persist both fields atomically -- single write avoids concurrent-reader inconsistency.
   // last_good_shasum records the shasum we just successfully cross-verified +
   // installed (per docs/SECURITY.md "last_good_shasum is a one-way 'what did
@@ -2192,7 +2339,7 @@ function statuslineRecompute() {
 function cmdConfig(sub) {
   if (sub === 'audit') {
     console.log('ijfw config --audit -- this feature is queued for a later release.');
-    console.log('Track progress: https://gitlab.com/therealseandonahoe/ijfw/issues');
+    console.log('Track progress: https://github.com/FerroxLabs/ijfw/issues');
     return;
   }
   console.log('Usage: ijfw config --audit');
@@ -2271,7 +2418,7 @@ async function handleGuide(useBrowser) {
   ];
   const guidePath = candidates.find(p => existsSync(p));
   if (!guidePath) {
-    console.error('[ijfw] Guide not found. Visit https://gitlab.com/therealseandonahoe/ijfw/-/blob/main/docs/GUIDE.md');
+    console.error('[ijfw] Guide not found. Visit https://github.com/FerroxLabs/ijfw/blob/main/docs/GUIDE.md');
     process.exit(1);
   }
   const md = readFileSync(guidePath, 'utf8');
@@ -3315,7 +3462,18 @@ function cmdSwarm(sub) {
     const taskId = args[0];
     const owner = optionValue(args.slice(1), ['--owner', '-o']);
     const message = optionValue(args.slice(1), ['--message', '-m']) || positionalMessage(args.slice(1), ['--owner', '-o']);
-    const result = completeSwarmTask(process.cwd(), taskId, { owner, message });
+    const commitSha = optionValue(args.slice(1), ['--commit', '--sha']);
+    const filesChanged = Number(optionValue(args.slice(1), ['--files-changed']));
+    const skipEvidence = args.includes('--skip-evidence');
+    // V155-006: caller must produce a filesystem witness (sha OR diffStats) OR
+    // explicitly opt out via --skip-evidence (admin overrides, dry-run flows).
+    // The planner records `task.completed-no-evidence` for downstream audit.
+    const evidence = commitSha
+      ? { commitSha }
+      : Number.isFinite(filesChanged) && filesChanged >= 1
+        ? { diffStats: { filesChanged } }
+        : undefined;
+    const result = completeSwarmTask(process.cwd(), taskId, { owner, message, evidence, skipEvidence });
     if (!result.ok) {
       console.log(`Swarm complete halted: ${result.error}`);
       process.exit(1);

package/src/dashboard-server.js

@@ -10,7 +10,7 @@ import { createServer } from 'node:http';
 import { existsSync, readFileSync, watch, writeFileSync, mkdirSync, readdirSync, statSync, realpathSync, renameSync, unlinkSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { join, dirname, resolve, relative, isAbsolute } from 'node:path';
+import { join, dirname, resolve, relative, isAbsolute, basename, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { buildCostReport, buildBreakdown, buildDailySeries, buildBlockUsage, getSavingsMethodology } from './cost/aggregator.js';
@@ -736,10 +736,15 @@ export async function startServer(options = {}) {
       try {
         const tierFilter = url.searchParams.get('tier') || null;
         const result = ttlCache(`memory:list:${tierFilter}`, COST_CACHE_TTL, memoryDirsMtimeKey, () => {
-          const { files, total, root, tiers } = listMemoryFiles(REPO_ROOT, tierFilter);
+          // V155-026 (v1.5.5): surface unreadable / corrupt-frontmatter files
+          // so the dashboard can warn the operator. Previously silently dropped.
+          const { files, errors, total, root, tiers } = listMemoryFiles(REPO_ROOT, tierFilter);
           const { counts, weekCounts, totalThisWeek } = buildRecallCounts(ledgerPath);
           const enriched = mergeRecallCounts(files, counts, weekCounts);
-          return { files: enriched, total, root, tiers, totalRecallsThisWeek: totalThisWeek };
+          return {
+            files: enriched, errors: errors || [], total, root, tiers,
+            totalRecallsThisWeek: totalThisWeek,
+          };
         });
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify(result));
@@ -1254,7 +1259,35 @@ export async function startServer(options = {}) {
       const contentDir = join(homedir(), '.ijfw', 'design-companion', 'content');
       mkdirSync(contentDir, { recursive: true });
       const name = url.pathname.split('/').pop();
+      // V155-037 (v1.5.5): the route regex `[^/]+\.html$` only forbids forward
+      // slashes — Windows `path.join` treats backslashes as separators, so
+      // `GET /design/files/..\..\..\windows\system32\hosts.html` previously
+      // escaped contentDir at join time. Reject any name that contains a
+      // backslash or a dot-segment, or starts with a dot, or doesn't survive
+      // a basename() round-trip. Belt-and-braces: also verify the joined
+      // filePath resolves under contentDir.
+      const isUnsafeName = (
+        name.includes('\\')
+        || name.includes('/')
+        || name.startsWith('.')
+        || name.includes('..')
+        // Null-byte truncates path strings on POSIX syscalls that honour
+        // C-string null-terminators. Reject any path containing one.
+        || name.includes('\u0000')
+        || basename(name) !== name
+      );
       const filePath = join(contentDir, name);
+      const filePathResolved = resolve(filePath);
+      const contentDirResolved = resolve(contentDir);
+      const isContained = (
+        filePathResolved === contentDirResolved
+        || filePathResolved.startsWith(contentDirResolved + sep)
+      );
+      if (isUnsafeName || !isContained) {
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('404 Not Found');
+        return;
+      }
       let html = null;
       try {
         if (existsSync(filePath)) html = readFileSync(filePath, 'utf8');

package/src/dispatch/override.js

@@ -151,14 +151,30 @@ async function cmdAudit({ projectRoot }) {
       const paths = resolveOverridePaths(skill, projectRoot);
       let sections = 0;
       let extendsChain = [];
+      const errors = [];
       for (const p of paths) {
-        const file = await loadOverrideFile(p).catch(() => null);
+        // V155-028 (v1.5.5): previously `.catch(() => null)` silently treated
+        // schema-invalid / unreadable overrides as 'not present'. The audit
+        // command exists precisely to surface override health, so swallowing
+        // these errors hid the exact failure mode operators care about.
+        let file;
+        try { file = await loadOverrideFile(p); }
+        catch (err) {
+          errors.push({ path: p, reason: 'load-fail', message: err?.message || String(err) });
+          continue;
+        }
         if (!file) continue;
         if (Array.isArray(file.manifest?.extends)) extendsChain = file.manifest.extends;
         const matches = file.body?.match(/<!--\s*ijfw-override:/g);
         sections += matches ? matches.length : 0;
       }
-      items.push({ preset: entry.preset, scope: entry.scope, skill, sections, extends: extendsChain });
+      items.push({
+        preset: entry.preset, scope: entry.scope, skill, sections,
+        extends: extendsChain,
+        // Only include `errors` when there is something to report — avoids
+        // every clean item carrying a noisy empty array.
+        ...(errors.length > 0 ? { errors } : {}),
+      });
     }
   }
   return { ok: true, command: 'audit', result: { items } };

package/src/dispatch/signer-cli.js

@@ -276,22 +276,27 @@ async function keygenHandler(args, ctx = {}) {
 }
 
 /**
- * keygen-fido2 handler — deferred stub.
+ * keygen-fido2 handler — unimplemented.
  *
- * Native libfido2 bindings would be IJFW's first native prod dep; that's
- * a v1.5.0+ architecture decision. For v1.4.3, FIDO2-backed signing is
- * available transitively via ssh-agent (modern YubiKey/Solokey speak
- * SSH agent natively).
+ * V155-057: previously returned `ok:true, deferred:true` — JSON consumers
+ * (CI scripts, automated install flows) reading `r.ok` saw success and
+ * proceeded as if a key had been minted. That's truthfulness-of-state
+ * violation: nothing was minted, no key exists, but state recorded ok.
  *
- * @returns {Promise<{ ok: true, deferred: true, message: string }>}
+ * Now returns `ok:false, error:'unimplemented'` so callers fail closed.
+ * The transitive ssh-agent path (modern YubiKey/Solokey speak SSH agent
+ * natively) remains the recommended route; the hint stays the same but
+ * the verdict is honest.
+ *
+ * @returns {Promise<{ ok: false, error: 'unimplemented', message: string }>}
  */
 async function keygenFido2Handler(_args, ctx = {}) {
-  const msg = 'FIDO2/libfido2 path deferred to v1.5.0; use --backend ssh-agent or default software backend';
+  const msg = 'FIDO2/libfido2 native backend is unimplemented — use `keygen <author> --backend ssh-agent` (modern YubiKey/Solokey work transitively via ssh-agent)';
   // Write to stderr for CLI visibility without disturbing JSON-stdout
   // consumers. Optionally inject a writer via ctx for tests.
   const stderr = ctx.stderr || process.stderr;
   try { stderr.write(`${msg}\n`); } catch { /* ignore */ }
-  return { ok: true, deferred: true, message: msg };
+  return { ok: false, error: 'unimplemented', message: msg };
 }
 
 export const handlers = Object.freeze({
@@ -301,7 +306,7 @@ export const handlers = Object.freeze({
 
 export const subcommandHelp = Object.freeze({
   keygen: 'keygen <author> [--backend software|ssh-agent] [--ssh-key-comment <c>] — generate or enrol a publisher signing key',
-  'keygen-fido2': 'keygen-fido2 <author> — deferred to v1.5.0; use --backend ssh-agent instead',
+  'keygen-fido2': 'keygen-fido2 <author> — UNIMPLEMENTED (no native libfido2 backend); use `keygen <author> --backend ssh-agent` instead',
 });
 
 // Test-only exports.

package/src/dream/stage-runner.js

@@ -27,6 +27,23 @@ export async function runStages(root, stages) {
       const extras = (await stage.run()) || {};
       markStageCompleted(root, stage.name, extras);
       completed.push({ name: stage.name, extras });
+      // TP-003 (v1.5.5 Trident): V155-005 closed the truthfulness-of-state
+      // hole (status:'completed_with_error' / 'skipped' written to
+      // .dream-state-v2.json), but operators don't read JSON unless they
+      // already suspect something's wrong. Surface the non-clean shapes on
+      // stderr at run time so the operator discovers the truth proactively
+      // (Sutherland: the system explains itself). The JSON state file
+      // remains the canonical record; this is the discoverability rail.
+      if (extras && extras.error) {
+        process.stderr.write(
+          `[dream] stage ${stage.name} completed with error: ${extras.error}. `
+          + 'Full envelope in .ijfw/state/.dream-state-v2.json.\n',
+        );
+      } else if (extras && extras.skipped) {
+        process.stderr.write(
+          `[dream] stage ${stage.name} skipped: ${extras.skipped}\n`,
+        );
+      }
     } catch (e) {
       markStageFailed(root, stage.name, e?.message || String(e));
       failed.push({ name: stage.name, reason: e?.message || String(e) });

package/src/dream/state-file.js

@@ -56,9 +56,23 @@ export function markStageStarted(root, stage) {
 
 export function markStageCompleted(root, stage, extras = {}) {
   const s = readDreamState(root);
+  // V155-005 (HIGH): the previous shape unconditionally wrote
+  // `status:'completed'` even when the stage returned a payload like
+  // `{ skipped:'db-unavailable' }` or `{ error:'tier-promotion-failed' }`.
+  // Operators reading `.dream-state-v2.json` saw "all stages completed"
+  // perpetually even when wiki-compile had been skipped for weeks. Inspect
+  // the returned envelope and route to a more honest status:
+  //   - `extras.skipped`      → status:'skipped'
+  //   - `extras.error`        → status:'completed_with_error'
+  //   - otherwise             → status:'completed' (back-compat shape).
+  let status = 'completed';
+  if (extras && typeof extras === 'object') {
+    if (extras.skipped) status = 'skipped';
+    else if (extras.error) status = 'completed_with_error';
+  }
   s.stages[stage] = {
     ...s.stages[stage],
-    status: 'completed',
+    status,
     completed_at: Date.now(),
     ...extras,
   };

package/src/extension-installer.js

@@ -736,6 +736,53 @@ export function extensionAuditBrief(manifest, skillBodies) {
 
 // --- install ----------------------------------------------------------------
 
+/**
+ * V155-061 (v1.5.5): byte-for-byte equality check for two directory trees.
+ * Returns true only when every file in `a` is present in `b` with identical
+ * bytes (and vice versa). Bails on the first divergence for efficiency.
+ * Used by the installer's staged-flip path to short-circuit re-installing
+ * the same version (avoids rewriting `installed_at` for no behavior change).
+ */
+async function dirsAreByteIdentical(a, b) {
+  let entriesA;
+  let entriesB;
+  try { entriesA = await readdir(a, { withFileTypes: true }); }
+  catch { return false; }
+  try { entriesB = await readdir(b, { withFileTypes: true }); }
+  catch { return false; }
+  const namesA = entriesA.map((e) => e.name).sort();
+  const namesB = entriesB.map((e) => e.name).sort();
+  if (namesA.length !== namesB.length) return false;
+  for (let i = 0; i < namesA.length; i += 1) {
+    if (namesA[i] !== namesB[i]) return false;
+  }
+  const byNameA = new Map(entriesA.map((e) => [e.name, e]));
+  const byNameB = new Map(entriesB.map((e) => [e.name, e]));
+  for (const name of namesA) {
+    const ea = byNameA.get(name);
+    const eb = byNameB.get(name);
+    const aPath = join(a, name);
+    const bPath = join(b, name);
+    if (ea.isDirectory() !== eb.isDirectory()) return false;
+    if (ea.isDirectory()) {
+      if (!(await dirsAreByteIdentical(aPath, bPath))) return false;
+      continue;
+    }
+    // Treat anything that isn't a regular file as "not identical" — symlinks,
+    // sockets etc. don't survive npm-publish round-trips, so this is rare.
+    if (!ea.isFile() || !eb.isFile()) return false;
+    let bufA;
+    let bufB;
+    try {
+      bufA = await readFile(aPath);
+      bufB = await readFile(bPath);
+    } catch { return false; }
+    if (bufA.length !== bufB.length) return false;
+    if (!bufA.equals(bufB)) return false;
+  }
+  return true;
+}
+
 /**
  * Install an extension from npm, local path, or https git URL.
  *
@@ -747,7 +794,7 @@ export function extensionAuditBrief(manifest, skillBodies) {
  *   accept_degraded_trident?: boolean,
  *   tridentExecutor?: Function,  // test seam — forwarded as runTrident({executor})
  * }} opts
- * @returns {Promise<{ok: boolean, name?: string, version?: string, scope?: string, gate_result_block?: string, errors?: string[]}>}
+ * @returns {Promise<{ok: boolean, name?: string, version?: string, scope?: string, gate_result_block?: string, errors?: string[], unchanged?: boolean}>}
  */
 export async function installExtension(source, opts = {}) {
   if (!opts || typeof opts !== 'object') {
@@ -1015,6 +1062,29 @@ export async function installExtension(source, opts = {}) {
         await cp(s.absPath, dst, { force: true });
       }
 
+      // V155-061 (v1.5.5): byte-identical short-circuit. Re-installing the
+      // same version was unconditional rm+rename → registry rewrite with a
+      // fresh installed_at timestamp. That defeats staleness audits and
+      // makes downstream watchers + hot-reloaders churn for nothing. If the
+      // staged tmpScopeDir is byte-identical to the existing scopeDir, skip
+      // both the swap AND the registry update so installed_at stays pinned
+      // to the original install. Mirrors `syncCodexAgents`'s `existing ===
+      // rendered` pattern. We still need the staged dir cleaned up if we
+      // bail out.
+      const identical = await dirsAreByteIdentical(tmpScopeDir, scopeDir);
+      if (identical) {
+        await rm(tmpScopeDir, { recursive: true, force: true }).catch(() => {});
+        return {
+          ok: true,
+          name: manifest.name,
+          version: manifest.version,
+          scope: opts.scope,
+          gate_result_block: gateResultBlock,
+          // Diagnostic so callers can tell a no-op install from a fresh one.
+          unchanged: true,
+        };
+      }
+
       // Atomic flip: drop old scopeDir, rename tmp -> scope. fs.rename is
       // atomic on POSIX when source/dest are on the same filesystem (they are
       // — same parent directory). On Windows rename to existing dir fails, so
@@ -1129,18 +1199,37 @@ export async function installExtension(source, opts = {}) {
       }
     }
 
+    // V155-003 / TP-002 (v1.5.5 Trident): when a project-scope install only
+    // partially deploys to platforms (e.g. some skill writes failed), the
+    // registry has already been updated but the user's editor world is
+    // incomplete. The prior shape returned `ok: 'partial'` — a string —
+    // which is TRUTHY under JS-idiomatic `if (r.ok)` checks, so legacy
+    // callers still saw the partial deploy as success. That's the very bug
+    // class V155-003 was meant to retire.
+    //
+    // TP-002 closes the loop: `ok` is now STRICTLY BOOLEAN (false on
+    // partial), and a new `status` field carries the tri-state for callers
+    // that want to differentiate full success vs partial vs failure.
+    // Legacy `if (r.ok) succeed()` consumers now correctly refuse on
+    // partial; new callers can branch on `r.status === 'partial'`.
+    const partialFailed = opts.scope === 'project' && deployPartial === true;
     return {
-      ok: true,
+      ok: !partialFailed,
+      status: partialFailed ? 'partial' : 'success',
       name: manifest.name,
       version: manifest.version,
       scope: opts.scope,
       gate_result_block: gateResultBlock,
       deploy: deployInfo,
       deploy_partial: deployPartial,
+      ...(partialFailed
+        ? { error: 'deploy-partial', partial_failures: partialDeployFailures }
+        : {}),
     };
   } catch (err) {
     return {
       ok: false,
+      status: 'failed',
       errors: [err && err.message ? err.message : String(err)],
       gate_result_block: gateResultBlock,
     };