forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

package/lib/commands/recall.js

@@ -1,10 +1,15 @@
 'use strict';
 
 const memoryRouter = require('../memory/router');
+const projectMemory = require('../project-memory');
+const { types: { isProxy } } = require('node:util');
 const { stripGlobalFlags } = require('../global-flags');
 const { fenceUntrusted } = require('../untrusted-content');
+const { applyBudget, buildSection, estimateTokens } = require('../orientation');
+const { memoryTrustStatus } = require('../memory-recall');
 
 const usage = 'Usage: forge recall [query] [--kind <type>] [--limit N] [--all] [--json]';
+const RECALL_CONTENT_BUDGET = 1100;
 
 // Reserved tag prefix that `remember --kind` writes (kernel issue 8cc1db4d). A `--kind`
 // filter keeps only notes carrying this tag; the prefix is stripped when surfacing the
@@ -12,10 +17,8 @@ const usage = 'Usage: forge recall [query] [--kind <type>] [--limit N] [--all] [
 // `--type`): `--type` is a reserved GLOBAL flag hard-validated to workflow classifications.
 const TYPE_TAG_PREFIX = 'type:';
 
-// When a `--kind` filter is active the tag filter runs in the command layer (the store is
-// not reimplemented), so scan a generous window of recent notes before filtering rather than
+// Kind filtering is pushed into the Kernel read so limits and capped metadata stay truthful.
 // the small default page — otherwise the type match could fall outside the default limit.
-const TYPE_FILTER_SCAN = 1000;
 
 /**
  * Separate the optional positional query from `--kind <type>`, `--limit N`, and `--json`.
@@ -77,26 +80,129 @@ function withType(entry) {
   return type ? { ...entry, type } : entry;
 }
 
+function privateCommandOption(options, field) {
+  if (!options || typeof options !== 'object' || isProxy(options)) return undefined;
+  let descriptor;
+  try { descriptor = Object.getOwnPropertyDescriptor(options, field); } catch { return undefined; }
+  return descriptor && Object.hasOwn(descriptor, 'value') ? descriptor.value : undefined;
+}
+
 function formatEntry(entry) {
   const date = entry.timestamp ? entry.timestamp.slice(0, 10) : '';
-  const prefix = date ? `${date}  ` : '';
+  const trust = memoryTrustStatus({
+    tags: entry.tags,
+    sourceAgent: entry.sourceAgent,
+    value: entry.machine ? {} : entry.note,
+  });
+  const sourceAgent = entry.sourceAgent || 'unknown';
+  const label = `[source=${sourceAgent} trust=${trust} updated=${date || 'unknown'}] `;
   // The reserved `type:` tag renders as a leading `(kind)` marker, not as a raw tag, so the
   // displayed tags stay the user's own labels.
   const type = typeOf(entry);
-  const userTags = (entry.tags || []).filter(t => !t.startsWith(TYPE_TAG_PREFIX));
+  const userTags = (entry.tags || []).filter(
+    t => !t.startsWith(TYPE_TAG_PREFIX) && !t.startsWith('trust:')
+  );
   const tagSuffix = userTags.length > 0 ? ` [${userTags.join(', ')}]` : '';
   const typeMarker = type ? `(${type}) ` : '';
   // Machine/insights records are LABELED with their source so they are never mistaken for a
   // plain human note; human `remember` notes render clean.
   const marker = entry.machine && entry.sourceAgent ? `(${entry.sourceAgent}) ` : '';
-  // Stored note text is UNTRUSTED (a planted memory could carry injected directives),
-  // so the human/agent-facing render is provenance-fenced. The `--json` path above
-  // keeps the raw note so programmatic consumers/parsers are unaffected.
-  const note = fenceUntrusted(entry.note, { source: 'memory' });
-  return `- ${prefix}${marker}${typeMarker}${note}${tagSuffix}`;
+  // Stored note text is untrusted. Fence it after budgeting so a truncation cannot
+  // sever the close marker; the `--json` path above keeps the raw note unchanged.
+  const note = String(entry.note == null ? '' : entry.note);
+  return `- ${label}${marker}${typeMarker}${note}${tagSuffix}`;
+}
+
+function createUsageRecorder(projectRoot, recallStore, commandOpts) {
+  const invocationId = privateCommandOption(commandOpts, 'invocationId');
+  const usageStore = privateCommandOption(commandOpts, 'usageStore');
+  const onUsageEvidence = privateCommandOption(commandOpts, 'onUsageEvidence');
+  const invocationStartedAt = privateCommandOption(commandOpts, 'invocationStartedAt')
+    || privateCommandOption(commandOpts, 'now')
+    || new Date().toISOString();
+  const evidenceCallback = typeof onUsageEvidence === 'function' && !isProxy(onUsageEvidence)
+    ? onUsageEvidence
+    : undefined;
+  return selected => {
+    const observation = projectMemory.recordRecallUsage(projectRoot, selected, {
+      invocationId,
+      usageStore: usageStore || recallStore,
+      invocationStartedAt,
+    });
+    if (evidenceCallback) {
+      // Observability is deliberately aggregate-only: callers never receive query, note,
+      // path, secret, or raw durable identifiers.
+      try { evidenceCallback(observation); } catch { /* advisory test seam */ }
+    }
+  };
+}
+
+function buildRecallSections(notes) {
+  return notes
+    .map((entry, index) => {
+      const content = formatEntry(entry);
+      if (estimateTokens(content) > RECALL_CONTENT_BUDGET) return null;
+      const trust = memoryTrustStatus({
+        tags: entry.tags,
+        sourceAgent: entry.sourceAgent,
+        value: entry.machine ? {} : entry.note,
+      });
+      return buildSection({
+        id: `recall_${index}`,
+        title: '',
+        content,
+        priority: index,
+        preserve: false,
+        data: { trust, memoryId: entry.id },
+      });
+    })
+    .filter(Boolean);
+}
+
+function humanRecallHeader(query, capped, rendered, noteCount, total, scope) {
+  const noun = scope === 'all' && !query ? 'stored memory record(s)' : 'remembered note(s)';
+  if (query) {
+    return capped || rendered < noteCount
+      ? `Top ${rendered} note(s) matching "${query}" (raise --limit for more):`
+      : `${rendered} note(s) matching "${query}":`;
+  }
+  if (capped || rendered < noteCount) {
+    return `Showing ${rendered} of ${total} ${noun} (newest first):`;
+  }
+  return `${rendered} ${noun}:`;
+}
+
+function renderHumanRecall(notes, result, recordUsage) {
+  const sections = buildRecallSections(notes);
+  const budgeted = applyBudget(sections, RECALL_CONTENT_BUDGET).sections
+    .filter(section => section.content);
+  for (const section of budgeted) {
+    section.content = fenceUntrusted(section.content, { source: 'memory' });
+  }
+  recordUsage(budgeted.map(section => ({ id: section.data.memoryId })));
+  const rendered = budgeted.length;
+  const header = humanRecallHeader(result.query, result.capped, rendered, notes.length, result.total, result.scope);
+  const confirmed = budgeted.filter(section => section.data.trust === 'confirmed');
+  const suggested = budgeted.filter(section => section.data.trust === 'suggested');
+  const groups = [
+    confirmed.length ? ['Confirmed memory', confirmed] : null,
+    suggested.length ? ['Suggested memory — verify before relying', suggested] : null,
+  ].filter(Boolean);
+  const body = groups.flatMap(([title, entries]) => [
+    title,
+    ...entries.map(entry => entry.content),
+  ]);
+  return { success: true, output: [header, ...body].join('\n') };
 }
 
-async function handler(args, flags, projectRoot) {
+function emptyRecall(query) {
+  const reason = query
+    ? `No notes match "${query}".`
+    : 'No notes remembered yet. Use "forge remember <note>" to add one.';
+  return { success: true, output: reason };
+}
+
+async function handler(args, flags, projectRoot, commandOpts = {}) {
   const { query, limit, type, json } = parseArgs(args);
   // `--all` is a GLOBAL boolean flag: in production bin/forge.js strips it from
   // args and sets flags.all; on a direct handler call it may still be in args.
@@ -105,56 +211,28 @@ async function handler(args, flags, projectRoot) {
   // A `--type` filter scans a generous recent window, then keeps only matching notes — the
   // read stays entirely in the existing store (no schema change). `--limit` is re-applied
   // AFTER filtering so it caps the typed result set, not the pre-filter scan.
-  const recallLimit = type ? Math.max(limit ?? 0, TYPE_FILTER_SCAN) : limit;
-  const result = memoryRouter.recall(projectRoot, { query, limit: recallLimit, all });
-  let notes = result.notes.map(withType);
-  let { total, capped } = result;
-  const { scope } = result;
-  if (type) {
-    notes = notes.filter(entry => entry.type === type);
-    total = notes.length;
-    if (limit && notes.length > limit) {
-      notes = notes.slice(0, limit);
-      capped = true;
-    } else {
-      capped = false;
-    }
-  }
+  // Resolve once for the complete recall: selection, count, and advisory evidence share
+  // one cached driver/connection rather than each opening or migrating independently.
+  const recallStore = projectMemory.resolveStore(projectRoot);
+  const result = memoryRouter.recall(projectRoot, { query, limit, all, kind: type }, { store: recallStore });
+  const notes = result.notes.map(withType);
+  const recordUsage = createUsageRecorder(projectRoot, recallStore, commandOpts);
 
   if (json) {
     // Object (not a bare array) so programmatic consumers see the total and whether the
     // result was truncated (raise --limit to page further).
+    recordUsage(notes);
     return {
       success: true,
-      output: `${JSON.stringify({ notes, total, capped, scope }, null, 2)}\n`,
+      output: `${JSON.stringify({ notes, total: result.total, capped: result.capped, scope: result.scope }, null, 2)}\n`,
     };
   }
 
   if (notes.length === 0) {
-    const reason = query
-      ? `No notes match "${query}".`
-      : 'No notes remembered yet. Use "forge remember <note>" to add one.';
-    return { success: true, output: reason };
+    return emptyRecall(query);
   }
 
-  const noun = scope === 'all' && !query ? 'stored memory record(s)' : 'remembered note(s)';
-  let header;
-  if (query) {
-    // BM25 returns at most `limit`; when full, signal it is the TOP-N, not the whole set.
-    header = capped
-      ? `Top ${notes.length} note(s) matching "${query}" (raise --limit for more):`
-      : `${notes.length} note(s) matching "${query}":`;
-  } else if (capped) {
-    // Never a bare full dump: show the newest N and the true total.
-    header = `Showing ${notes.length} of ${total} ${noun} (newest first):`;
-  } else {
-    header = `${total} ${noun}:`;
-  }
-  const lines = notes.map(formatEntry);
-  return {
-    success: true,
-    output: [header, ...lines].join('\n'),
-  };
+  return renderHumanRecall(notes, result, recordUsage);
 }
 
 module.exports = {

package/lib/commands/recap.js

@@ -46,7 +46,12 @@ async function handler(args, _flags, projectRoot, opts = {}) {
   }
 
   const budget = readOption(args, '--budget', undefined);
-  const recap = buildIssueRecap(projectRoot, issueId, { budgetTokens: budget });
+  // `runIssueOperation` is the injectable kernel-read seam (Slice C2) — the same
+  // pass-through opts already carry for the grounding write below.
+  const recap = await buildIssueRecap(projectRoot, issueId, {
+    budgetTokens: budget,
+    runIssueOperation: opts.runIssueOperation,
+  });
 
   // Grounding (gate.read_first): a successful recap IS the load-the-doc action,
   // so append a `context.loaded` event that unblocks a later `forge claim <id>`.

package/lib/commands/release.js

@@ -8,12 +8,14 @@ const {
 } = require('../release-readiness');
 const { runIssueOperation: defaultRunIssueOperation } = require('../forge-issues');
 const { normalizeArgs, normalizeIssueResult, withResolvedIssueBackend } = require('./_issue');
+const { generateNpmPublishWorkflow } = require('../npm-publish-workflow');
+const { updateBunWorkflowPins } = require('../bun-workflow-pins');
 
 // `forge release <id>` releases a claimed issue; `forge release check` runs the
 // release-readiness gate. The two share the top-level verb, so this command
 // dispatches `check` to the gate and routes everything else through the shared
 // issue dispatch (resolve backend → runIssueOperation('release') → normalize).
-const usage = 'Usage: forge release <id>  |  forge release check --target 0.1.0 [--json]  |  forge release regen-audit';
+const usage = 'Usage: forge release <id>  |  forge release check --target 0.1.0 [--json]  |  forge release regen-audit  |  forge release generate-npm-workflow --expect-head <full-sha>  |  forge release update-bun-pins --expect-head <full-sha>';
 
 async function runReleaseIssue(args, projectRoot, opts = {}) {
   const resolved = withResolvedIssueBackend(projectRoot, opts);
@@ -44,18 +46,51 @@ function parseReleaseArgs(args = []) {
       return false;
     }
     const previous = args[index - 1];
-    return previous !== '--target';
+    return previous !== '--target' && previous !== '--expect-head';
   });
 
   return {
     subcommand,
     target: readOption(args, '--target', SUPPORTED_TARGET),
+		expectedHead: readOption(args, '--expect-head', null),
     json: args.includes('--json'),
   };
 }
 
 async function handler(args, _flags, projectRoot, opts = {}) {
-  const parsed = parseReleaseArgs(args);
+	const parsed = parseReleaseArgs(args);
+	if (parsed.subcommand === 'update-bun-pins') {
+		const updater = opts.updateBunWorkflowPins || updateBunWorkflowPins;
+		const updated = await updater(projectRoot, {
+			env: opts.env,
+			kernelDeps: opts.kernelDeps,
+			expectedHead: parsed.expectedHead,
+			resolveHead: opts.resolveHead,
+		});
+		return updated.success
+			? {
+				success: true,
+				updated,
+				output: `Pinned ${updated.paths.length} workflows to Bun ${updated.version}.\n`,
+			}
+			: updated;
+	}
+
+	if (parsed.subcommand === 'generate-npm-workflow') {
+		const generated = await generateNpmPublishWorkflow(projectRoot, {
+			env: opts.env,
+			kernelDeps: opts.kernelDeps,
+			expectedHead: parsed.expectedHead,
+			resolveHead: opts.resolveHead,
+		});
+		return generated.success
+			? {
+				success: true,
+				generated,
+				output: `Generated ${generated.path} (${generated.contentHash}).\n`,
+			}
+			: generated;
+	}
 
   if (parsed.subcommand === 'regen-audit') {
     // forge release regen-audit — rewrite the D20 kill-list from a live re-scan.
@@ -96,6 +131,7 @@ module.exports = {
   usage,
   flags: {
     '--target <version>': 'Release target to check',
+		'--expect-head <full-sha>': 'Required exact HEAD for protected workflow generation',
     '--json': 'Emit the readiness report as JSON',
   },
   handler,

package/lib/commands/remember.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const crypto = require('node:crypto');
 const memoryRouter = require('../memory/router');
 const { stripGlobalFlags } = require('../global-flags');
 
@@ -22,6 +23,7 @@ const STRUCTURED_FIELDS = [
 // `--kind` (NOT `--type`): `--type` is a reserved GLOBAL flag that bin/forge.js hard-validates
 // against workflow classifications (critical|standard|…), so it can never carry a note type.
 const TYPE_TAG_PREFIX = 'type:';
+const CONTENT_HASH_TAG_PREFIX = 'content-hash:';
 
 /**
  * Split positional note words from `--kind`, `--tag <label>`, the structured field flags,
@@ -105,15 +107,37 @@ async function handler(args, _flags, projectRoot) {
   }
 
   // The type rides as a reserved tag so it is stored and filterable without a schema change.
-  const allTags = type ? [...tags, `${TYPE_TAG_PREFIX}${type}`] : tags;
-  const entry = memoryRouter.append(projectRoot, body, { tags: allTags });
+  const contentHash = type === 'session-summary'
+    ? crypto.createHash('sha256').update(JSON.stringify({
+      body,
+      tags: [...tags].sort((left, right) => left.localeCompare(right)),
+      type,
+    }), 'utf8').digest('hex')
+    : null;
+  const metadata = contentHash ? { kind: 'session-summary', content_hash: contentHash } : undefined;
+  const hashTag = contentHash ? `${CONTENT_HASH_TAG_PREFIX}${contentHash}` : null;
+  const allTags = [
+    ...tags,
+    ...(type ? [`${TYPE_TAG_PREFIX}${type}`] : []),
+    ...(hashTag ? [hashTag] : []),
+  ];
+  let entry;
+  if (hashTag) {
+    const matches = memoryRouter.recall(projectRoot, {
+      query: contentHash,
+      limit: 2,
+      all: true,
+    }).notes;
+    entry = matches.find(note => Array.isArray(note.tags) && note.tags.includes(hashTag));
+  }
+  if (!entry) entry = memoryRouter.append(projectRoot, body, { tags: allTags });
 
   if (json) {
-    const payload = type ? { ...entry, type } : entry;
+    const payload = type ? { ...entry, type, metadata } : entry;
     return { success: true, output: `${JSON.stringify(payload, null, 2)}\n` };
   }
 
-  const userTags = entry.tags.filter(tag => !tag.startsWith(TYPE_TAG_PREFIX));
+  const userTags = entry.tags.filter(tag => !tag.startsWith(TYPE_TAG_PREFIX) && !tag.startsWith(CONTENT_HASH_TAG_PREFIX));
   const tagSuffix = userTags.length > 0 ? ` [${userTags.join(', ')}]` : '';
   const typePrefix = type ? `(${type}) ` : '';
   return {

package/lib/commands/serve.js

@@ -31,6 +31,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { spawn } = require('node:child_process');
+const { githubWorkerEnvironment } = require('../pr-monitor/watch-lifecycle');
 
 // Shared-machine hardening (single-instance lock, owner-only perms + audit,
 // hash-chained mutation journal). No dependency on serve.js, so a top-level
@@ -237,12 +238,21 @@ async function routeMutation(verb, args, projectRoot, deps = {}) {
 // Snapshot (GET /data.json) — regenerate on demand, debounced.
 // ---------------------------------------------------------------------------
 
-function defaultGenerate(projectRoot, dashboardDir) {
+function defaultGenerate(projectRoot, dashboardDir, deps = {}) {
   return new Promise((resolve, reject) => {
     const script = path.join(dashboardDir, 'generate-snapshot.mjs');
-    const child = spawn(process.execPath, [script], { cwd: projectRoot, stdio: 'ignore', windowsHide: true });
+    const env = githubWorkerEnvironment(projectRoot, deps);
+    let child;
+    try {
+      child = (deps.spawn || spawn)(process.execPath, [script], {
+        cwd: projectRoot, stdio: 'ignore', windowsHide: true, ...(env ? { env } : {}),
+      });
+    } catch {
+      reject(new Error('snapshot generation failed'));
+      return;
+    }
     const timer = setTimeout(() => { child.kill(); reject(new Error('snapshot generation timed out')); }, GEN_TIMEOUT_MS);
-    child.on('error', (err) => { clearTimeout(timer); reject(err); });
+    child.on('error', () => { clearTimeout(timer); reject(new Error('snapshot generation failed')); });
     child.on('exit', (code) => {
       clearTimeout(timer);
       if (code === 0) resolve();
@@ -409,7 +419,7 @@ function buildContext(projectRoot, dashboardDir, token, deps = {}) {
       buffer: null,
       lastGen: 0,
       inFlight: null,
-      generate: deps.generate || defaultGenerate,
+      generate: deps.generate || ((root, dir) => defaultGenerate(root, dir, deps)),
     },
   };
 }
@@ -438,13 +448,16 @@ function browserOpener() {
   return { file: '/usr/bin/xdg-open', args: [] };
 }
 
-function openBrowser(url) {
+function openBrowser(url, projectRoot = process.cwd(), deps = {}) {
   try {
     const { file, args } = browserOpener();
+    const env = githubWorkerEnvironment(projectRoot, deps);
     // windowsHide keeps this detached opener from flashing a console window on
     // Windows (Node defaults windowsHide to false); background/detached spawns
     // must stay silent (issue 931e7924).
-    const child = spawn(file, [...args, url], { detached: true, stdio: 'ignore', windowsHide: true });
+    const child = (deps.spawn || spawn)(file, [...args, url], {
+      detached: true, stdio: 'ignore', windowsHide: true, ...(env ? { env } : {}),
+    });
     // spawn() failures (e.g. the opener binary is missing) surface ASYNChronously
     // as an 'error' event, NOT via the try/catch — an unhandled one would crash
     // `forge serve`. Opening a browser is best-effort; swallow it (URL is printed).
@@ -480,7 +493,7 @@ function announceServe(server, token, options, resolve) {
     `\nforge serve — interactive dashboard (loopback only)\n  ${url}\n`
     + '  Token dies with this process. Press Ctrl-C to stop.\n\n',
   );
-  if (options.open) openBrowser(url);
+  if (options.open) openBrowser(url, options.projectRoot, options.deps);
   installServeShutdown(server, resolve, options.onClose);
 }
 
@@ -535,7 +548,7 @@ function verifyJournalAtStartup(projectRoot, warn = (m) => process.stderr.write(
   return result;
 }
 
-async function handler(args, flags = {}, projectRoot = process.cwd(), _opts = {}) {
+async function handler(args, flags = {}, projectRoot = process.cwd(), opts = {}) {
   const { port, open } = parseServeArgs(args, flags);
   const dashboardDir = path.join(projectRoot, 'web', 'dashboard');
   if (!fs.existsSync(path.join(dashboardDir, 'index.html'))) {
@@ -558,10 +571,12 @@ async function handler(args, flags = {}, projectRoot = process.cwd(), _opts = {}
   verifyJournalAtStartup(projectRoot);
 
   const token = mintToken();
-  const ctx = buildContext(projectRoot, dashboardDir, token);
+  const ctx = buildContext(projectRoot, dashboardDir, token, opts);
   const server = createServeServer(ctx);
   return startListening(server, port, token, {
     open,
+    projectRoot,
+    deps: opts,
     onClose: () => security.releaseLock(projectRoot),
   });
 }
@@ -575,6 +590,8 @@ module.exports = {
   routeMutation,
   parseServeArgs,
   buildContext,
+  defaultGenerate,
+  openBrowser,
   createServeServer,
   verifyToken,
   isLoopbackRequest,