yam-flow 2.8.1 → 2.8.2

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to yam-flow are documented here.
 
+## v2.8.2 - 2026-10-02
+
+### Improved
+
+- Hook configuration now uses Codex's required top-level `hooks` wrapper. `yam hook migrate` backs up legacy files and preserves commands and unrelated handlers without automatically approving Codex trust.
+- Hook status can now separate configured health, Codex `hooks/list` discovery, and opt-in local entrypoint observations; Node launcher selection is bound to the running executable identity.
+- External yam update checks distinguish exact-version npm distribution propagation (`pending_distribution`) from network, authorization, or metadata failures.
+- Memory listing and summary preserve the difference between missing, empty, invalid, unreadable, and incomplete record storage; incomplete reads cannot overwrite an existing summary.
+- Added bounded Markdown skill-content checks for frontmatter identity, symlinks, personal absolute paths, download-to-shell patterns, and high-signal secrets.
+
 ## v2.8.1 - 2026-10-01
 
 ### Security

package/COMMANDS.md

@@ -153,6 +153,8 @@ yam memory add /path/to/project --kind repeat_mistake --summary "UI work was dec
 yam memory summary /path/to/project
 ```
 
+`yam memory list --json` keeps the normal complete result as an array and returns a bounded `yam.memory-read.v1` envelope for missing, invalid, unreadable, or incomplete storage. `yam memory summary --json` refuses to overwrite the existing summary unless the record directory was read completely.
+
 ## Token Budget
 
 ```bash
@@ -172,7 +174,7 @@ yam update apply --component yam --json
 yam update apply --all --json
 ```
 
-`yam update check` is read-only. Its component result preserves the registry artifact source receipt: npm integrity/`gitHead` for yam, PyPI release-file SHA-256 values for Scrapling, and the Git-pinned manifest commit for Insane Search. Every `apply` needs explicit authorization, pins the official npm registry or isolated PyPI index, uses a concurrent-run lock, records a component receipt, and stops on failed/manual results. `--all` runs yam last. A yam install verifies the effective executable identity before any yam-side install command and repeats that check during rollback. This identity contract currently supports POSIX symlink layouts; Windows npm `.cmd` shims fail closed as unverified. Insane Search requires a clean tracked local manifest whose bytes match Git and matching pre/post-add commits, is never remove-first, and never edits `.codex/plugins/cache` directly.
+`yam update check` is read-only. Its component result preserves the registry artifact source receipt: npm integrity/`gitHead` for yam, PyPI release-file SHA-256 values for Scrapling, and the Git-pinned manifest commit for Insane Search. Yam also compares `latest` with exact-version metadata and probes the official exact tarball URL; a 404 is `pending_distribution`, while network/auth/metadata mismatch is `check_failed`. The bounded HEAD probe confirms availability only and does not hash tarball bytes. Every `apply` needs explicit authorization, pins the official npm registry or isolated PyPI index, uses a concurrent-run lock, records a component receipt, and stops on failed/manual results. `--all` runs yam last. A yam install verifies the effective executable identity before any yam-side install command and repeats that check during rollback. This identity contract currently supports POSIX symlink layouts; Windows npm `.cmd` shims fail closed as unverified. Insane Search requires a clean tracked local manifest whose bytes match Git and matching pre/post-add commits, is never remove-first, and never edits `.codex/plugins/cache` directly.
 
 ## Release Supply Chain
 
@@ -327,15 +329,18 @@ Supported report shapes:
 
 `lite` is advisory-only. `study-note` runs the read-only Study Note Guard against the final assistant message and can request one correction pass; neither profile runs verification or forces routes.
 
+`yam hook migrate [--global|--project dir]` wraps legacy top-level events in Codex's `hooks` object without changing commands. It backs up the original, refuses unsafe files, and is a no-op for canonical configs. Review changed definitions in Codex `/hooks` before execution; yam does not approve trust.
+
 ```bash
 yam hook status --global
+yam hook migrate --global
 yam hook enable lite --global
 yam hook enable study-note --global
 yam hook disable lite --global
 yam hook disable study-note --global
 ```
 
-`yam hook status` exits nonzero for unreadable configs, stale paths, missing targets, duplicate handlers, or incomplete event coverage. Re-enable the affected profile to back up the file, preserve unrelated hooks, and migrate its command and events.
+`yam hook status` exits nonzero for unreadable configs, stale paths, missing targets, duplicate handlers, or incomplete event coverage. Add `--json` for `yam.hook-readiness.v1`, or `--probe` to query `hooks/list` in a separate bounded Codex app-server. The probe separates host discovery from local configuration and never claims that the active Desktop session loaded the hook. Add `--observe` to `yam hook enable` to record a bounded local entrypoint observation; it contains only hashes and event metadata and remains partial same-user evidence. Re-enable the affected profile to back up the file, preserve unrelated hooks, and migrate its command and events.
 
 ## Security check
 

package/README.md

@@ -74,6 +74,8 @@ yam memory add . --kind lesson --summary "Keep UI checks visual before declaring
 yam memory summary .
 ```
 
+`yam memory list --json` distinguishes missing, empty, invalid, unreadable, and incomplete record directories. A blocked `yam memory summary --json` exits nonzero and preserves the previous summary instead of treating an access failure as an empty memory set.
+
 Memory writes to `.yam/memory/` only when you run the command. Routes should prefer `.yam/memory/summary.md` and should not read every record by default.
 
 ## Lite Hook
@@ -91,6 +93,8 @@ It only adds short advisory context. It does not run verification, tmux, browser
 
 ## Study Note Hook
 
+Codex hook files use a top-level `hooks` object containing event groups (`{"hooks":{"Stop":[...]}}`). For older yam files with events at the top level, run `yam hook migrate --global`: this creates a backup and changes only the layout, preserving existing commands and unrelated handlers. Review the changed definitions in Codex `/hooks`; discovery alone does not authorize execution, and yam never approves hook trust automatically.
+
 Enable this profile when you want Codex to check changed work at final-response time as well as remind the agent at prompt time.
 
 ```bash
@@ -102,7 +106,7 @@ The profile installs `UserPromptSubmit` and `Stop` handlers. At `Stop`, yam chec
 
 Hook stdin is limited to 1 MiB. Malformed JSON or an oversized payload produces a valid fail-open response without echoing the rejected content, deriving hook context from it, or mutating the workspace. Other CLI commands that read piped text use a 4 MiB limit and fail closed when it is exceeded.
 
-`yam hook status` reports stale or missing command targets as `broken` and exits nonzero. Run `yam hook enable <profile> --global` again to create a timestamped backup, preserve unrelated hooks, and migrate that profile to the current installed path and event coverage. Restart Codex or open a new task after changing hooks.
+`yam hook status` reports stale or missing command targets as `broken` and exits nonzero. Run `yam hook enable <profile> --global` again to create a timestamped backup, preserve unrelated hooks, and migrate that profile to the current installed path and event coverage. For runtime-oriented diagnosis, use `yam hook status --global --json --probe`; this separates configured hooks, discovery from a new bounded Codex app-server, and local entrypoint observations. The active Desktop session remains `not_measured` unless the host provides independent evidence. `yam hook enable <profile> --global --observe` records only a local hash-bound event observation; it is partial evidence and not host attestation. Restart Codex or open a new task after changing hooks.
 
 ## Install
 

package/dist/bin/yam.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
+import { selectHookNode, probeHookDiscovery, inspectHookObservation, recordHookObservation } from '../lib/hook-readiness.js';
+import { readMemoryDirectory } from '../lib/memory-records.js';
 import { runSecurityCommand } from '../lib/security-integration.js';
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
@@ -71,8 +73,8 @@ const INSTRUCTION_DUPLICATION_LIMITS = {
     minDirectiveChars: 40
 };
 const YAM_HOOK_ENTRYPOINT = path.join(ROOT, 'dist', 'bin', 'yam.js');
-const YAM_LITE_HOOK_COMMAND = `${JSON.stringify(process.execPath)} ${JSON.stringify(YAM_HOOK_ENTRYPOINT)} hook run lite`;
-const YAM_STUDY_NOTE_HOOK_COMMAND = `${JSON.stringify(process.execPath)} ${JSON.stringify(YAM_HOOK_ENTRYPOINT)} hook run study-note`;
+let YAM_LITE_HOOK_COMMAND = `${JSON.stringify(process.execPath)} ${JSON.stringify(YAM_HOOK_ENTRYPOINT)} hook run lite`;
+let YAM_STUDY_NOTE_HOOK_COMMAND = `${JSON.stringify(process.execPath)} ${JSON.stringify(YAM_HOOK_ENTRYPOINT)} hook run study-note`;
 const REQUIRED_PACK_SECTIONS = [
     'Product Direction',
     'UI Direction',
@@ -1944,6 +1946,8 @@ async function hook(args = []) {
         return hookUsage();
     if (subcommand === 'status')
         return hookStatus(args.slice(1));
+    if (subcommand === 'migrate')
+        return hookMigrate(args.slice(1));
     if (subcommand === 'enable')
         return hookEnable(args.slice(1));
     if (subcommand === 'disable')
@@ -1957,14 +1961,17 @@ function hookUsage() {
     console.log(`yam hook
 
 Usage:
-  yam hook status [--global|--project dir]
-  yam hook enable <lite|study-note> [--global|--project dir]
+  yam hook status [--global|--project dir] [--probe] [--json]
+  yam hook migrate [--global|--project dir]
+  yam hook enable <lite|study-note> [--global|--project dir] [--observe]
   yam hook disable [lite|study-note] [--global|--project dir]
   yam hook run <lite|study-note>
 
 Notes:
   hooks are opt-in. lite is advisory-only; study-note adds a prompt reminder and a one-pass Stop completion gate.
   Hooks do not generate reports, run tmux, start subagents, or execute verification automatically.
+  --probe queries hooks/list in a separate bounded Codex app-server; active session loading stays unknown.
+  --observe opts into private local entrypoint observations without storing prompt content; not host attestation.
 `);
 }
 function parseHookArgs(args = []) {
@@ -1991,7 +1998,7 @@ function parseHookArgs(args = []) {
 }
 function hookPathFor(parsed) {
     if (parsed.mode === 'global')
-        return path.join(os.homedir(), '.codex', 'hooks.json');
+        return path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'hooks.json');
     return path.join(path.resolve(parsed.projectDir || process.cwd()), '.codex', 'hooks.json');
 }
 function isYamLiteHook(handler = {}) {
@@ -2003,12 +2010,34 @@ function isYamStudyNoteHook(handler = {}) {
 function isYamHookProfile(handler = {}, profile = 'lite') {
     return profile === 'study-note' ? isYamStudyNoteHook(handler) : isYamLiteHook(handler);
 }
+const CODEX_HOOK_EVENTS = new Set(['SessionStart', 'SessionEnd', 'PreToolUse', 'PermissionRequest', 'PostToolUse', 'PreCompact', 'PostCompact', 'UserPromptSubmit', 'SubagentStart', 'SubagentStop', 'Stop', 'Interrupt']);
+function hookEventMap(config = {}) {
+    const nested = config.hooks && typeof config.hooks === 'object' && !Array.isArray(config.hooks) ? config.hooks : {};
+    const events = { ...nested };
+    for (const [event, entries] of Object.entries(config)) {
+        if (CODEX_HOOK_EVENTS.has(event) && Array.isArray(entries)) {
+            events[event] = [...(Array.isArray(events[event]) ? events[event] : []), ...entries];
+        }
+    }
+    return events;
+}
+function canonicalHookConfig(config = {}) {
+    if (config.hooks != null && (typeof config.hooks !== 'object' || Array.isArray(config.hooks)))
+        throw new Error('hooks must be an event object; existing file preserved');
+    const next = { ...config, hooks: hookEventMap(config) };
+    for (const event of CODEX_HOOK_EVENTS) {
+        if (event in config && !Array.isArray(config[event]))
+            throw new Error('legacy hook event must be an array; existing file preserved');
+        delete next[event];
+    }
+    return next;
+}
 function stripYamHooks(config = {}, profile = 'lite') {
-    const next = { ...config };
-    for (const event of Object.keys(next)) {
-        if (!Array.isArray(next[event]))
+    const next = canonicalHookConfig(config);
+    for (const event of Object.keys(next.hooks)) {
+        if (!Array.isArray(next.hooks[event]))
             continue;
-        const entries = next[event];
+        const entries = next.hooks[event];
         const keptEntries = [];
         for (const entry of entries) {
             const hooks = Array.isArray(entry?.hooks) ? entry.hooks.filter((handler) => !isYamHookProfile(handler, profile)) : [];
@@ -2017,9 +2046,9 @@ function stripYamHooks(config = {}, profile = 'lite') {
                 keptEntries.push(rest);
         }
         if (keptEntries.length > 0)
-            next[event] = keptEntries;
+            next.hooks[event] = keptEntries;
         else
-            delete next[event];
+            delete next.hooks[event];
     }
     return next;
 }
@@ -2036,7 +2065,7 @@ function withYamHook(config = {}, profile = 'lite') {
                 }
             ]
         };
-        next[event] = [...(Array.isArray(next[event]) ? next[event] : []), entry];
+        next.hooks[event] = [...(Array.isArray(next.hooks[event]) ? next.hooks[event] : []), entry];
     }
     return next;
 }
@@ -2045,6 +2074,11 @@ async function hookStatus(args = []) {
     const target = hookPathFor(parsed);
     const loaded = await readHookConfig(target);
     if (loaded.error) {
+        if (args.includes('--json')) {
+            console.log(JSON.stringify({ schema: 'yam.hook-readiness.v1', scope: parsed.mode, configuration: 'unreadable', loaded: 'unknown', execution_observed: false, truth_status: 'partial' }, null, 2));
+            process.exitCode = 1;
+            return;
+        }
         console.log('yam-lite hook: broken');
         console.log('yam-study-note hook: broken');
         console.log(`  - hook config unreadable: ${loaded.error}`);
@@ -2055,10 +2089,30 @@ async function hookStatus(args = []) {
     }
     const lite = await inspectHookProfile(loaded.config, 'lite');
     const studyNote = await inspectHookProfile(loaded.config, 'study-note');
+    const cwd = path.resolve(parsed.projectDir || process.cwd());
+    const commands = { lite: lite.entries.map((entry) => String(entry.handler.command)), 'study-note': studyNote.entries.map((entry) => String(entry.handler.command)) };
+    const host = args.includes('--probe')
+        ? await probeHookDiscovery({ executable: await findExecutable('codex') || 'codex', cwd, commands, configPath: target })
+        : { state: 'not_measured', active_session_loaded: 'not_measured', execution_observed: false, truth_status: 'partial' };
+    const profiles = {};
+    for (const [profile, health] of [['lite', lite], ['study-note', studyNote]]) {
+        profiles[profile] = { configured: health.state, issues: health.issues, loaded: 'unknown',
+            execution: await inspectHookObservation(cwd, profile, YAM_HOOK_ENTRYPOINT) };
+    }
+    if (args.includes('--json')) {
+        console.log(JSON.stringify({ schema: 'yam.hook-readiness.v1', scope: parsed.mode, profiles, host, truth_status: 'partial' }, null, 2));
+        if (lite.state === 'broken' || studyNote.state === 'broken')
+            process.exitCode = 1;
+        return;
+    }
     printHookProfileStatus('lite', lite);
     printHookProfileStatus('study-note', studyNote);
     console.log(`scope: ${parsed.mode}`);
     console.log(`file: ${target}`);
+    console.log('active Codex session loaded: unknown (configuration is not runtime evidence)');
+    console.log(`host discovery: ${host.state}`);
+    for (const profile of ['lite', 'study-note'])
+        console.log(`yam-${profile} execution: ${profiles[profile].execution.state} (local entrypoint evidence, not host attestation)`);
     if (lite.state === 'broken' || studyNote.state === 'broken')
         process.exitCode = 1;
 }
@@ -2066,7 +2120,7 @@ function hookConfigHasYamLite(config = {}) {
     return hookConfigHasProfile(config, 'lite');
 }
 function hookConfigHasProfile(config = {}, profile = 'lite') {
-    return Object.values(config).some((entries) => Array.isArray(entries) && entries.some((entry) => {
+    return Object.values(hookEventMap(config)).some((entries) => Array.isArray(entries) && entries.some((entry) => {
         return Array.isArray(entry?.hooks) && entry.hooks.some((handler) => isYamHookProfile(handler, profile));
     }));
 }
@@ -2078,7 +2132,7 @@ function hookEventsForProfile(profile = 'lite') {
 }
 function hookProfileEntries(config = {}, profile = 'lite') {
     const matches = [];
-    for (const [event, entries] of Object.entries(config)) {
+    for (const [event, entries] of Object.entries(hookEventMap(config))) {
         if (!Array.isArray(entries))
             continue;
         for (const entry of entries) {
@@ -2142,6 +2196,8 @@ function splitHookCommand(command = '') {
 }
 function parseYamHookCommand(command = '', profile = 'lite') {
     const words = splitHookCommand(command);
+    if (words.at(-1) === '--observe')
+        words.pop();
     if (words.length === 5 && words[2] === 'hook' && words[3] === 'run' && words[4] === profile) {
         const nodeName = path.basename(words[0]).toLowerCase();
         if (/^node(?:\.exe)?$/.test(nodeName) && path.basename(words[1]).toLowerCase() === 'yam.js') {
@@ -2185,6 +2241,8 @@ async function inspectHookProfile(config = {}, profile = 'lite') {
     if (!entries.length)
         return { state: 'disabled', issues: [], entries };
     const issues = [];
+    if (Object.keys(config).some((event) => CODEX_HOOK_EVENTS.has(event)))
+        issues.push('legacy hook config requires the top-level hooks wrapper; rerun yam hook enable to migrate with backup');
     for (const event of hookEventsForProfile(profile)) {
         const count = entries.filter((entry) => entry.event === event).length;
         if (count === 0)
@@ -2213,6 +2271,9 @@ async function readHookConfig(target) {
         if (!value || Array.isArray(value) || typeof value !== 'object') {
             return { config: {}, exists: true, error: 'top-level value must be a JSON object' };
         }
+        if (value.hooks != null && (typeof value.hooks !== 'object' || Array.isArray(value.hooks))) {
+            return { config: {}, exists: true, error: 'hooks must be an event object' };
+        }
         return { config: value, exists: true, error: '' };
     }
     catch (error) {
@@ -2233,8 +2294,41 @@ async function writeHookConfig(target, config) {
         throw error;
     }
 }
+async function hookMigrate(args = []) {
+    const parsed = parseHookArgs(args);
+    const target = hookPathFor(parsed);
+    const loaded = await readHookConfig(target);
+    if (loaded.error) {
+        console.error('hook migration blocked: unreadable configuration');
+        process.exitCode = 1;
+        return;
+    }
+    if (!loaded.exists || !Object.keys(loaded.config).some((key) => CODEX_HOOK_EVENTS.has(key))) {
+        console.log('hook migration: no legacy event layout found');
+        return;
+    }
+    const before = await fsp.lstat(target);
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1)
+        throw new Error('hook migration blocked: unsafe config file');
+    const original = await fsp.readFile(target, 'utf8');
+    if (JSON.stringify(JSON.parse(original)) !== JSON.stringify(loaded.config))
+        throw new Error('hook configuration changed; retry migration');
+    const next = canonicalHookConfig(loaded.config);
+    const backup = `${target}.yam-backup-${timestampId()}`;
+    await fsp.copyFile(target, backup, fs.constants.COPYFILE_EXCL);
+    const after = await fsp.lstat(target);
+    if (after.dev !== before.dev || after.ino !== before.ino || after.mtimeMs !== before.mtimeMs
+        || await fsp.readFile(target, 'utf8') !== original)
+        throw new Error('hook configuration changed; backup preserved, retry migration');
+    await writeHookConfig(target, next);
+    console.log(`hook migration: wrapped event groups; handlers and metadata preserved\nbackup: ${backup}\nReview changed definitions in Codex /hooks before enabling execution.`);
+}
 async function hookEnable(args = []) {
     const parsed = parseHookArgs(args);
+    const node = await selectHookNode();
+    const observe = args.includes('--observe') ? ' --observe' : '';
+    YAM_LITE_HOOK_COMMAND = `${JSON.stringify(node.executable)} ${JSON.stringify(YAM_HOOK_ENTRYPOINT)} hook run lite${observe}`;
+    YAM_STUDY_NOTE_HOOK_COMMAND = `${JSON.stringify(node.executable)} ${JSON.stringify(YAM_HOOK_ENTRYPOINT)} hook run study-note${observe}`;
     if (!['lite', 'study-note'].includes(parsed.profile)) {
         console.error('Only lite and study-note hooks are supported: yam hook enable <lite|study-note>');
         process.exitCode = 1;
@@ -2263,6 +2357,7 @@ async function hookEnable(args = []) {
     }
     await writeHookConfig(target, next);
     console.log(`yam-${parsed.profile} hook enabled (${parsed.mode}): ${target}`);
+    console.log(`node launcher: ${node.selection}; alias identity matched the current runtime (no PATH candidate executed)`);
     if (needsMigration)
         console.log(`migrated: ${existing.length} existing yam-${parsed.profile} handler(s) to the current command and event coverage`);
     console.log('Restart Codex or start a new thread if the app does not pick up hook changes immediately.');
@@ -2283,7 +2378,7 @@ async function hookDisable(args = []) {
         return;
     }
     const next = stripYamHooks(current, parsed.profile);
-    if (Object.keys(next).length === 0) {
+    if (Object.keys(next).length === 1 && Object.keys(next.hooks).length === 0) {
         await rmrf(target);
     }
     else {
@@ -2313,6 +2408,8 @@ async function hookRun(args = []) {
     }
     const event = input?.hook_event_name || input?.hookEventName || input?.event || 'UserPromptSubmit';
     const cwd = String(input?.cwd || process.cwd());
+    if (args.includes('--observe'))
+        await recordHookObservation(cwd, profile, String(event), YAM_HOOK_ENTRYPOINT).catch(() => { });
     if (profile === 'study-note' && event === 'Stop') {
         console.log(JSON.stringify(await buildStudyNoteStopOutput(input, cwd)));
         return;
@@ -6079,7 +6176,7 @@ async function memory(args = []) {
     }
     if (subcommand === 'summary' || subcommand === 'summarize') {
         const parsed = parseMemoryArgs(args.slice(1));
-        return memorySummary(parsed.dir);
+        return memorySummary(parsed.dir, { json: args.includes('--json') });
     }
     if (subcommand === 'resolve')
         return memoryResolve(args.slice(1));
@@ -6093,7 +6190,7 @@ Usage:
   yam memory init [dir]
   yam memory add [dir] --kind <kind> --summary <text> [--evidence <text>] [--action <text>] [--source <text>]
   yam memory list [dir] [--json]
-  yam memory summary [dir]
+  yam memory summary [dir] [--json]
   yam memory resolve [dir] <id> [--note <text>]
 
 Kinds:
@@ -6163,7 +6260,17 @@ async function memoryAdd(args = []) {
     console.log(`memory added: ${id}`);
 }
 async function memoryList(targetDir = process.cwd(), { json = false } = {}) {
-    const records = await readMemoryRecords(targetDir);
+    const report = await readMemoryRecords(targetDir);
+    const records = report.records;
+    if (!report.complete) {
+        if (report.state !== 'missing')
+            process.exitCode = 1;
+        if (json)
+            console.log(JSON.stringify(report, null, 2));
+        else
+            console.error(`memory read ${report.state}: ${JSON.stringify(report.diagnostics)}${report.diagnostics_truncated ? ' (diagnostics truncated)' : ''}`);
+        return;
+    }
     if (json) {
         console.log(JSON.stringify(records, null, 2));
         return;
@@ -6178,9 +6285,18 @@ async function memoryList(targetDir = process.cwd(), { json = false } = {}) {
             console.log(`  action: ${record.action}`);
     }
 }
-async function memorySummary(targetDir = process.cwd()) {
+async function memorySummary(targetDir = process.cwd(), { json = false } = {}) {
     const dir = memoryDir(targetDir);
-    const records = await readMemoryRecords(targetDir);
+    const report = await readMemoryRecords(targetDir);
+    if (!report.complete) {
+        process.exitCode = 1;
+        if (json)
+            console.log(JSON.stringify({ ...report, summary_written: false }, null, 2));
+        else
+            console.error(`memory summary blocked (${report.state}); existing summary preserved: ${JSON.stringify(report.diagnostics)}${report.diagnostics_truncated ? ' (diagnostics truncated)' : ''}`);
+        return;
+    }
+    const records = report.records;
     await fsp.mkdir(dir, { recursive: true });
     const active = records.filter((record) => record.status !== 'resolved');
     const resolved = records.filter((record) => record.status === 'resolved');
@@ -6212,7 +6328,10 @@ async function memorySummary(targetDir = process.cwd()) {
     }
     const target = path.join(dir, 'summary.md');
     await fsp.writeFile(target, `${lines.join('\n').trim()}\n`);
-    console.log(`memory summary written: ${target}`);
+    if (json)
+        console.log(JSON.stringify({ ...report, summary_written: true, path: target }, null, 2));
+    else
+        console.log(`memory summary written: ${target}`);
 }
 async function memoryResolve(args = []) {
     const parsed = parseMemoryArgs(args);
@@ -6267,23 +6386,7 @@ function memoryDir(targetDir = process.cwd()) {
 }
 async function readMemoryRecords(targetDir = process.cwd()) {
     const recordsDir = path.join(memoryDir(targetDir), 'records');
-    if (!await exists(recordsDir))
-        return [];
-    const entries = await fsp.readdir(recordsDir, { withFileTypes: true });
-    const records = [];
-    for (const entry of entries) {
-        if (!entry.isFile() || !entry.name.endsWith('.json'))
-            continue;
-        const file = path.join(recordsDir, entry.name);
-        try {
-            const record = await readJson(file);
-            records.push(record);
-        }
-        catch (error) {
-            records.push({ id: entry.name.replace(/\.json$/, ''), kind: 'invalid', status: 'invalid', summary: `invalid JSON: ${errorMessage(error)}` });
-        }
-    }
-    return records.sort((a, b) => String(a.createdAt || '').localeCompare(String(b.createdAt || '')));
+    return readMemoryDirectory(recordsDir);
 }
 function timestampId() {
     const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\.(\d{3})Z$/, '$1z');

package/dist/lib/design-production.d.ts

@@ -129,7 +129,7 @@ export declare function createPlanReviewCanvas(input: {
         visual_correctness: string;
         implementation_correctness: string;
     };
-    truth_status: "verified" | "partial";
+    truth_status: "partial" | "verified";
 }>;
 export declare function addPlanReviewComment(input: {
     root: string;
@@ -147,7 +147,7 @@ export declare function addPlanReviewComment(input: {
         visual_correctness: string;
         implementation_correctness: string;
     };
-    truth_status: "verified" | "partial";
+    truth_status: "partial" | "verified";
 }>;
 export declare function closePlanReviewCanvas(input: {
     root: string;
@@ -165,7 +165,7 @@ export declare function closePlanReviewCanvas(input: {
         visual_correctness: string;
         implementation_correctness: string;
     };
-    truth_status: "verified" | "partial";
+    truth_status: "partial" | "verified";
 }>;
 export declare function readPlanReviewSession(file: string): Promise<PlanReviewSession>;
 export declare function createDesignRevisionState(input: {
@@ -228,7 +228,7 @@ export declare function verifyFinalGalleryManifest(input: {
         implementation_correctness: string;
     };
     next_action: string;
-    truth_status: "blocked" | "partial";
+    truth_status: "partial" | "blocked";
 }>;
 export declare function finalizeDesignProductionPhase(input: {
     root: string;
@@ -283,7 +283,7 @@ export declare function finalizeDesignProductionPhase(input: {
         server: false;
         background_service: false;
     };
-    phase_evidence_status: "complete" | "bounded_stop" | "incomplete";
+    phase_evidence_status: "complete" | "incomplete" | "bounded_stop";
     ready: boolean;
     ready_to_claim_correctness: boolean;
     next_action: string;
@@ -301,6 +301,6 @@ export declare function verifyDesignProductionPhaseReceipt(input: {
     receipt_digest: string;
     ready_to_claim_correctness: boolean;
     next_action: string;
-    truth_status: "blocked" | "partial";
+    truth_status: "partial" | "blocked";
 }>;
 export {};

package/dist/lib/external-updates.d.ts

@@ -22,6 +22,7 @@ export interface ExternalUpdatePaths {
 export interface ExternalUpdateDependencies {
     run?: (command: string, args: string[], options?: ExternalCommandOptions) => Promise<ExternalCommandResult> | ExternalCommandResult;
     fetchJson?: (url: string) => Promise<any>;
+    probeArtifact?: (url: string) => Promise<number>;
     now?: () => Date;
     homeDir?: string;
     env?: NodeJS.ProcessEnv;
@@ -33,7 +34,7 @@ export interface ExternalComponentCheck {
     installed_version: string;
     latest_version: string;
     update_available: boolean;
-    status: 'up_to_date' | 'update_available' | 'not_installed' | 'check_failed';
+    status: 'up_to_date' | 'update_available' | 'not_installed' | 'pending_distribution' | 'check_failed';
     source: string;
     source_revision?: {
         local: string;
@@ -132,4 +133,8 @@ export declare function applyExternalUpdates(currentYamVersion: string, selectio
     truth_status: string;
     next_action: string;
 }>;
+export declare class RegistryHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, url: string);
+}
 export {};