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

package/lib/commands/plan.js

@@ -13,6 +13,10 @@ const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 const { resolveIssueBackend } = require('../issue-backend');
 const { runIssueOperation } = require('../forge-issues');
+const {
+	findPlanWorkFolder,
+	reconcilePlanAuthority,
+} = require('../workflow/plan-authority');
 
 // Constants for security
 // Note: cwd is resolved at call-time via getExecOptions() to avoid stale require-time snapshots
@@ -483,7 +487,7 @@ async function registerBranchIssueLinkage(options, branch, issueId) {
 				branch,
 				actor: null,
 				issue_id: issueId,
-				work_folder: null,
+				work_folder: options.workFolder || null,
 				registered_at: new Date().toISOString(),
 				state: 'active',
 			});
@@ -976,11 +980,38 @@ async function executePlan(featureName, options = {}) { // NOSONAR S3776
 			};
 		}
 
+		const workFolder = options.workFolder || findPlanWorkFolder(options.projectRoot || process.cwd(), featureSlug);
+
 		// F1: persist the branch->issue linkage so a plan-created branch resolves
 		// to its issue for kernel-authoritative stage state (dev/validate/ship).
 		// Kernel-only, best-effort.
 		if (issueBackend === 'kernel') {
-			await registerBranchIssueLinkage({ ...options, issueBackend }, branch.branchName, issue.issueId);
+			await registerBranchIssueLinkage({ ...options, issueBackend, workFolder }, branch.branchName, issue.issueId);
+			await withPlanDriver(options, driver => {
+				if (!driver || typeof driver.loadPlanSnapshot !== 'function') return null;
+				let existing;
+				try {
+					existing = driver.loadPlanSnapshot({ issue_id: issue.issueId }, {});
+				} catch (error) {
+					// Injectable issue runners used by embedding callers may not persist into
+					// this driver's store. With no repository artifacts there is nothing to
+					// reconcile; preserve that legacy embedding contract.
+					if (/^Issue .* not found in the kernel$/i.test(error.message)) {
+						if (!workFolder) return null;
+						throw new Error(`Issue ${issue.issueId} is not available for plan authority persistence`);
+					}
+					throw error;
+				}
+				if (!existing && !workFolder) return null;
+				return reconcilePlanAuthority({
+					driver,
+					issueId: issue.issueId,
+					projectRoot: options.projectRoot || process.cwd(),
+					workFolder,
+					mode: 'plan',
+					repairCommand: `forge plan ${JSON.stringify(featureName)} --issue ${issue.issueId}`,
+				});
+			});
 		}
 
 		// Build result summary

package/lib/commands/pr.js

@@ -81,6 +81,8 @@ async function handler(args, flags, projectRoot, opts) {
 
 module.exports = {
   name: 'pr',
+  githubAuth: (args = []) => ['ship', 'merge', 'shepherd']
+    .includes(stripGlobalFlags(args).find(arg => !arg.startsWith('-'))),
   description:
     'Unified pull-request surface: forge pr ship|preflight|shepherd|merge (wraps ship/preflight/shepherd/merge)',
   usage,

package/lib/commands/preflight.js

@@ -88,11 +88,19 @@ function resolveBaseRef(exec) {
  * @param {{ runAll?: boolean }} [opts]
  * @returns {{ resolved: boolean, changedFiles: string[], reason?: string, baseRef?: string }}
  */
-function resolveChangeSet(exec = execFileSync, { runAll = false } = {}) {
+function resolveChangeSet(exec = execFileSync, { runAll = false, baseRef: explicitBaseRef = null } = {}) {
   if (runAll) {
     return { resolved: true, changedFiles: [], reason: 'whole-tree scope (--all)' };
   }
-  const baseRef = resolveBaseRef(exec);
+  const baseRef = explicitBaseRef || resolveBaseRef(exec);
+  if (explicitBaseRef && !gitVerifyRef(exec, explicitBaseRef)) {
+    return {
+      resolved: false,
+      baseRef: explicitBaseRef,
+      changedFiles: [],
+      reason: `explicit base branch ${explicitBaseRef} is unavailable`,
+    };
+  }
   if (!baseRef) {
     return {
       resolved: false,

package/lib/commands/push.js

@@ -4,7 +4,7 @@ const { execFileSync, spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
 const forgeToken = require('../../scripts/check-forge-token');
-const { QUICK_LANE_ENV_VAR, QUICK_LANE_VALUE } = require('../../scripts/test');
+const { QUICK_LANE_ENV_VAR, QUICK_LANE_VALUE, resolveFullSuiteTimeoutMs } = require('../../scripts/test');
 const { fireAndForget } = require('../pr-monitor/reconcile-executor');
 
 const isWindows = process.platform === 'win32';
@@ -127,8 +127,8 @@ function maybeTriggerShepherdAfterPush({
 	try {
 		trigger({ projectRoot });
 		return { armed: true };
-	} catch (err) {
-		return { armed: false, reason: err.message };
+	} catch {
+		return { armed: false, reason: 'shepherd-launch-failed' };
 	}
 }
 
@@ -191,6 +191,94 @@ function runLint(spawnFn, pkgManager, projectRoot) {
 	return lintResult.status === 0;
 }
 
+/**
+ * Reports the kill signal a timed-out test run is terminated with. Shared by
+ * the spawn options and the timeout detector so the two cannot drift.
+ */
+const TEST_RUN_KILL_SIGNAL = 'SIGKILL';
+
+/**
+ * Reads the terminating signal under either field name.
+ *
+ * `node:child_process.spawnSync` reports `signal`; native `Bun.spawnSync`
+ * reports `signalCode`. Read both rather than assuming one.
+ *
+ * @param {Object} testResult - spawnSync result object
+ * @returns {string|null} Signal name, or null when none was reported
+ */
+function terminationSignalOf(testResult) {
+	return testResult.signal || testResult.signalCode || null;
+}
+
+/**
+ * Reports whether a test run was killed by its own wall-clock budget.
+ *
+ * Requires AFFIRMATIVE evidence. Verified against pinned Bun 1.3.12 on Windows:
+ * a `node:child_process` spawnSync timeout returns `status: null`,
+ * `signal: <killSignal>`, AND an error whose `code` is `ETIMEDOUT`. Native
+ * `Bun.spawnSync` instead sets `exitedDueToTimeout: true` with `signalCode`.
+ * Those two markers are the only proof of a timeout, and they are checked
+ * BEFORE the generic error branch — testing `error` first swallowed the timeout
+ * diagnostic in exactly the case it was written for.
+ *
+ * A bare kill signal with no marker is deliberately NOT treated as a timeout:
+ * an OOM kill or an operator `kill -9` produces the identical status/signal
+ * shape, and since a genuine budget kill always carries a marker, inferring
+ * from the signal alone buys nothing and costs a misdiagnosis (it would claim
+ * the budget elapsed and send the user to raise FORGE_TEST_TIMEOUT_MS).
+ *
+ * @param {Object} testResult - spawnSync result object
+ * @returns {boolean} True when the run hit its budget
+ */
+function isTimeoutTermination(testResult) {
+	if (testResult.exitedDueToTimeout === true) return true;
+	return Boolean(testResult.error) && testResult.error.code === 'ETIMEDOUT';
+}
+
+/**
+ * Explain a test run that never produced an exit status.
+ *
+ * `spawnSync` reports `status: null` when the child was killed by a signal
+ * (timeout kill included) or never started at all. Without this the push
+ * aborted with no summary at all, which is indistinguishable from a genuine
+ * test failure.
+ *
+ * @param {Object} testResult - spawnSync result object
+ * @param {number} timeoutMs - Wall-clock budget applied to the run
+ * @param {function} log - Logger function
+ */
+function reportTestRunTermination(testResult, timeoutMs, log) {
+	const signal = terminationSignalOf(testResult);
+
+	if (isTimeoutTermination(testResult)) {
+		log(
+			`Test run timed out after ${Math.round(timeoutMs / 1000)}s `
+			+ `(killed by ${signal || 'timeout'}) — push aborted.`,
+		);
+		log('Raise the budget with FORGE_TEST_TIMEOUT_MS if this machine is slower than the default.');
+		return;
+	}
+
+	if (testResult.error) {
+		log(`Test run could not complete: ${testResult.error.message}`);
+		return;
+	}
+
+	if (signal) {
+		// Signalled without timeout evidence: report the fact and the likely
+		// causes. Do NOT blame the budget — that sends the user after the wrong
+		// lever and hides the real failure.
+		log(
+			`Test run was terminated by ${signal} before finishing — push aborted. `
+			+ `The run had a ${Math.round(timeoutMs / 1000)}s budget but reported no timeout, `
+			+ 'so this is most likely an external kill or an out-of-memory kill.',
+		);
+		return;
+	}
+
+	log('Test run ended without an exit status — push aborted.');
+}
+
 /**
  * Run tests unless in quick mode, logging warnings for first push.
  * @param {function} spawnFn - spawnSync or mock
@@ -199,9 +287,10 @@ function runLint(spawnFn, pkgManager, projectRoot) {
  * @param {string} projectRoot - Absolute path to project root
  * @param {boolean} quickMode - Whether to skip tests
  * @param {function} log - Logger function
+ * @param {NodeJS.ProcessEnv} [env] - Environment used to resolve the test budget
  * @returns {boolean|undefined} True if tests passed, undefined if skipped
  */
-function runTests(spawnFn, execFn, pkgManager, projectRoot, quickMode, log) {
+function runTests(spawnFn, execFn, pkgManager, projectRoot, quickMode, log, env = process.env) {
 	if (quickMode) {
 		log('Tests skipped (--quick) — CI will run full suite on GitHub');
 		const branch = getCurrentBranch(execFn);
@@ -211,12 +300,25 @@ function runTests(spawnFn, execFn, pkgManager, projectRoot, quickMode, log) {
 		return undefined;
 	}
 
+	// `forge push` runs the package-level `test` script, i.e. the whole suite.
+	// Budget it from the shared full-suite budget in scripts/test.js — which is
+	// sized as ~2x the measured healthy full-suite runtime and overridable with
+	// FORGE_TEST_TIMEOUT_MS — instead of an arbitrary local cap: the old fixed
+	// 120s killed a healthy full run mid-suite and pushed nothing. Never
+	// reintroduce a local constant here; change the shared budget with a fresh
+	// measurement instead.
+	const timeoutMs = resolveFullSuiteTimeoutMs(env);
 	const testResult = spawnFn(pkgManager, ['run', 'test'], {
 		stdio: 'inherit',
 		shell: isWindows,
 		cwd: projectRoot,
-		timeout: 120000,
+		timeout: timeoutMs,
+		killSignal: TEST_RUN_KILL_SIGNAL,
 	});
+	if (testResult.status === null || testResult.status === undefined) {
+		reportTestRunTermination(testResult, timeoutMs, log);
+		return false;
+	}
 	return testResult.status === 0;
 }
 
@@ -266,7 +368,7 @@ module.exports = {
 		}
 
 		// Step 3: Tests (skip in quick mode)
-		const testsPassed = runTests(spawnFn, execFn, pkgManager, projectRoot, quickMode, log);
+		const testsPassed = runTests(spawnFn, execFn, pkgManager, projectRoot, quickMode, log, deps?.env || process.env);
 		if (!quickMode && !testsPassed) {
 			return { success: false, quickMode, lintPassed: true, testsPassed: false, pushed: false };
 		}

package/lib/commands/recall.js

@@ -1,6 +1,8 @@
 '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');
@@ -15,10 +17,8 @@ const RECALL_CONTENT_BUDGET = 1100;
 // `--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`.
@@ -80,6 +80,13 @@ 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 trust = memoryTrustStatus({
@@ -106,48 +113,32 @@ function formatEntry(entry) {
   return `- ${label}${marker}${typeMarker}${note}${tagSuffix}`;
 }
 
-async function handler(args, flags, projectRoot) {
-  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.
-  const all = Boolean(flags && flags.all) || args.includes('--all');
-
-  // 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;
+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 */ }
     }
-  }
-
-  if (json) {
-    // Object (not a bare array) so programmatic consumers see the total and whether the
-    // result was truncated (raise --limit to page further).
-    return {
-      success: true,
-      output: `${JSON.stringify({ notes, total, capped, 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 };
-  }
+  };
+}
 
-  const sections = notes
+function buildRecallSections(notes) {
+  return notes
     .map((entry, index) => {
       const content = formatEntry(entry);
       if (estimateTokens(content) > RECALL_CONTENT_BUDGET) return null;
@@ -162,29 +153,35 @@ async function handler(args, flags, projectRoot) {
         content,
         priority: index,
         preserve: false,
-        data: { trust },
+        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 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 || rendered < notes.length
-      ? `Top ${rendered} note(s) matching "${query}" (raise --limit for more):`
-      : `${rendered} note(s) matching "${query}":`;
-  } else if (capped || rendered < notes.length) {
-    // Never a bare full dump: show the rendered count and the true total.
-    header = `Showing ${rendered} of ${total} ${noun} (newest first):`;
-  } else {
-    header = `${rendered} ${noun}:`;
-  }
+  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 = [
@@ -195,10 +192,47 @@ async function handler(args, flags, projectRoot) {
     title,
     ...entries.map(entry => entry.content),
   ]);
-  return {
-    success: true,
-    output: [header, ...body].join('\n'),
-  };
+  return { success: true, output: [header, ...body].join('\n') };
+}
+
+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.
+  const all = Boolean(flags && flags.all) || args.includes('--all');
+
+  // 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.
+  // 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: result.total, capped: result.capped, scope: result.scope }, null, 2)}\n`,
+    };
+  }
+
+  if (notes.length === 0) {
+    return emptyRecall(query);
+  }
+
+  return renderHumanRecall(notes, result, recordUsage);
 }
 
 module.exports = {

package/lib/commands/release.js

@@ -9,12 +9,13 @@ const {
 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  |  forge release generate-npm-workflow';
+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);
@@ -45,23 +46,42 @@ 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);
+	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
 			? {
@@ -111,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 {