memorix 1.5.1 → 1.6.1

package/src/embedding/provider.ts

@@ -175,12 +175,26 @@ let initPromise: Promise<EmbeddingProvider | null> | null = null;
 type EmbeddingMode = 'off' | 'fastembed' | 'transformers' | 'api' | 'auto';
 type ProviderKind = 'api' | 'fastembed' | 'transformers' | 'unknown';
 
+export type EmbeddingRuntimeStatus = 'disabled' | 'uninitialized' | 'ready' | 'degraded';
+export type EmbeddingFailureKind = 'authorization' | 'billing' | 'timeout' | 'upstream';
+
+export interface EmbeddingRuntimeHealth {
+  status: EmbeddingRuntimeStatus;
+  provider?: { name: string; dimensions: number };
+  failure?: {
+    kind: EmbeddingFailureKind;
+    occurredAt: string;
+    retryAfterMs: number;
+  };
+}
+
 /**
  * Tracks whether the last init attempt resulted in a temporary failure
  * (mode != 'off' but provider returned null). When true, the next
  * getEmbeddingProvider() call will retry instead of returning cached null.
  */
 let lastInitWasTemporaryFailure = false;
+let lastEmbeddingFailure: { kind: EmbeddingFailureKind; occurredAt: number } | null = null;
 let lastEmbeddingWarning = '';
 let lastEmbeddingWarningAt = 0;
 const WARNING_COOLDOWN_MS = 30_000;
@@ -271,13 +285,38 @@ function isTemporaryEmbeddingFailure(error: unknown): boolean {
   );
 }
 
+function classifyEmbeddingFailure(error: unknown): EmbeddingFailureKind {
+  const message = error instanceof Error ? error.message : String(error);
+  if (/embedding api error \(401\)|invalid_api_key|incorrect api key|unauthorized/i.test(message)) {
+    return 'authorization';
+  }
+  if (/embedding api error \(402\)|quota exceeded|account balance/i.test(message)) {
+    return 'billing';
+  }
+  if (/embedding api timeout|abort/i.test(message)) {
+    return 'timeout';
+  }
+  return 'upstream';
+}
+
 function markTemporaryFailure(reason: unknown): void {
   provider = null;
   initPromise = null;
   lastInitWasTemporaryFailure = true;
   lastFailureTimestamp = Date.now();
+  lastEmbeddingFailure = {
+    kind: classifyEmbeddingFailure(reason),
+    occurredAt: lastFailureTimestamp,
+  };
   const message = reason instanceof Error ? reason.message : String(reason);
-  warnOnce(`[memorix] Embedding provider temporarily unavailable at runtime: ${message}`);
+  warnOnce(`[memorix] Embedding provider unavailable at runtime: ${message}`);
+}
+
+function markProviderReady(candidate: EmbeddingProvider): EmbeddingProvider {
+  provider = wrapProvider(candidate);
+  lastInitWasTemporaryFailure = false;
+  lastEmbeddingFailure = null;
+  return provider;
 }
 
 async function createFastEmbedProvider(): Promise<EmbeddingProvider | null> {
@@ -438,7 +477,7 @@ export async function getEmbeddingProvider(
     if (mode === 'fastembed') {
       const initialized = await createFastEmbedProvider();
       if (!initialized) return null;
-      provider = wrapProvider(initialized);
+      provider = markProviderReady(initialized);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
@@ -447,7 +486,7 @@ export async function getEmbeddingProvider(
     if (mode === 'transformers') {
       const initialized = await createTransformersProvider();
       if (!initialized) return null;
-      provider = wrapProvider(initialized);
+      provider = markProviderReady(initialized);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
@@ -456,7 +495,7 @@ export async function getEmbeddingProvider(
     if (mode === 'api') {
       const initialized = await createAPIProvider(options);
       if (!initialized) return null;
-      provider = wrapProvider(initialized);
+      provider = markProviderReady(initialized);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
@@ -465,7 +504,7 @@ export async function getEmbeddingProvider(
     if (hasAPIEmbeddingConfig()) {
       const initialized = await createAPIProvider(options);
       if (initialized) {
-        provider = wrapProvider(initialized);
+        provider = markProviderReady(initialized);
         warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
         return provider;
       }
@@ -473,7 +512,7 @@ export async function getEmbeddingProvider(
 
     const localFallback = await createLocalFallbackProvider();
     if (localFallback) {
-      provider = wrapProvider(localFallback);
+      provider = markProviderReady(localFallback);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
@@ -507,6 +546,36 @@ export async function isVectorSearchAvailable(): Promise<boolean> {
   return p !== null;
 }
 
+/**
+ * Process-local embedding health, intentionally read-only and network-free.
+ * It lets the control plane distinguish a configured provider from one that
+ * has degraded after a live credential, billing, timeout, or upstream error.
+ */
+export function getEmbeddingRuntimeHealth(): EmbeddingRuntimeHealth {
+  const mode = getEmbeddingMode();
+  if (mode === 'off') return { status: 'disabled' };
+
+  if (lastInitWasTemporaryFailure && lastEmbeddingFailure) {
+    return {
+      status: 'degraded',
+      failure: {
+        kind: lastEmbeddingFailure.kind,
+        occurredAt: new Date(lastEmbeddingFailure.occurredAt).toISOString(),
+        retryAfterMs: Math.max(0, RETRY_COOLDOWN_MS - (Date.now() - lastEmbeddingFailure.occurredAt)),
+      },
+    };
+  }
+
+  if (provider) {
+    return {
+      status: 'ready',
+      provider: { name: provider.name, dimensions: provider.dimensions },
+    };
+  }
+
+  return { status: 'uninitialized' };
+}
+
 /**
  * Check if embedding is explicitly disabled by configuration (mode === 'off').
  *
@@ -529,6 +598,7 @@ export function resetProvider(): void {
   initPromise = null;
   lastInitWasTemporaryFailure = false;
   lastFailureTimestamp = 0;
+  lastEmbeddingFailure = null;
   lastEmbeddingWarning = '';
   lastEmbeddingWarningAt = 0;
 }

package/src/hooks/handler.ts

@@ -21,6 +21,11 @@ import { normalizeHookInput } from './normalizer.js';
 import { detectBestPattern, patternToObservationType } from './pattern-detector.js';
 import { isSignificantKnowledge, isRetrievedResult, isTrivialCommand } from './significance-filter.js';
 import type { AgentName, HookEvent, HookOutput, NormalizedHookInput } from './types.js';
+import {
+  hookObservationRuntimeOptions,
+  readHookStdin,
+  resolveHookStdinTimeoutMs,
+} from './lifecycle.js';
 
 type HookInjectionMode = 'full' | 'minimal' | 'silent';
 type HookContextTarget = 'hook-session-start' | 'hook-user-prompt';
@@ -762,23 +767,9 @@ export function formatHookOutput(
  * Called by the CLI: `memorix hook`
  */
 export async function runHook(agentOverride?: string, eventOverride?: string): Promise<void> {
-  // Read stdin with a timeout — some hosts (e.g. Gemini CLI) may not close
-  // stdin promptly, causing `for await` to hang until the process is killed.
-  const rawInput = await new Promise<string>((resolve) => {
-    const chunks: Buffer[] = [];
-    const finish = () => resolve(Buffer.concat(chunks).toString('utf-8').trim());
-
-    // Hard timeout: resolve with whatever we have after 3 s
-    const timer = setTimeout(() => {
-      process.stdin.removeAllListeners('data');
-      process.stdin.removeAllListeners('end');
-      finish();
-    }, 3_000);
-
-    process.stdin.on('data', (chunk: Buffer) => { chunks.push(chunk); });
-    process.stdin.on('end', () => { clearTimeout(timer); finish(); });
-    process.stdin.on('error', () => { clearTimeout(timer); finish(); });
-  });
+  // Some hosts (e.g. Gemini CLI) may not close stdin promptly. Bound the
+  // read and release the stream so an open pipe cannot keep Node alive.
+  const rawInput = await readHookStdin(process.stdin, resolveHookStdinTimeoutMs());
 
   if (!rawInput) {
     process.stdout.write(JSON.stringify({ continue: true }));
@@ -841,7 +832,7 @@ export async function runHook(agentOverride?: string, eventOverride?: string): P
       await initObservationStore(dataDir);
       await initMSStore(dataDir);
       await initSessStore(dataDir);
-      await initObservations(dataDir);
+      await initObservations(dataDir, hookObservationRuntimeOptions(rawProject.rootPath));
       await storeObservation({ ...observation, projectId, sourceDetail: 'hook' });
       // Automatic capture is deliberately quiet. Candidate state and later
       // qualification are visible through Memorix inspection, not injected as

package/src/hooks/installers/index.ts

@@ -1259,7 +1259,7 @@ function getAgentRulesContent(agent?: AgentName, scope: 'project' | 'global' = '
     '',
     `Default first step for non-trivial coding work: call \x60memorix_project_context\x60 with the user's actual task before progress files, dev-log reads, ad-hoc file reads, or git archaeology. Memorix will choose a task-lensed brief (bugfix, feature, release, onboarding, refactor, docs, test, or general). When the task is continuing prior work, the same brief also includes a bounded prior-work projection. Treat its "Start here" files as the first ${contextNoun} files to inspect.`,
     '',
-    'If the MCP tool is not visible yet but the client supports tool discovery or dynamic loading, search/select \x60memorix_project_context\x60 first. Continuation fallback is mandatory: when the user asks to continue, resume, take over, or explain prior work and MCP cannot be called in this turn, run exactly one CLI brief with the user\'s real task before inspecting files, Git history, progress notes, or guessing: \x60memorix resume "<task>" --json\x60. For a new task, use \x60memorix context "<task>" --json\x60 instead. The absence of \x60.memorix\x60 or visible memory files never proves project memory is empty. If that one command fails, report it and proceed normally. Do not probe help, enumerate commands, chain broad searches, wait indefinitely on MCP startup, or hand-write tool-call syntax.',
+    'If the MCP tool is not visible yet but the client supports tool discovery or dynamic loading, search/select \x60memorix_project_context\x60 first. Continuation fallback is mandatory: when the user asks to continue, resume, take over, or explain prior work and MCP cannot be called in this turn, run exactly one CLI brief with the user\'s real task before inspecting files, Git history, progress notes, or guessing: \x60memorix resume "<task>" --brief-json\x60. For a new task, use \x60memorix context "<task>" --brief-json\x60 instead. The absence of \x60.memorix\x60 or visible memory files never proves project memory is empty. Use \x60--json\x60 only when a diagnostic needs the detailed legacy payload. If that one command fails, report it and proceed normally. Do not probe help, enumerate commands, chain broad searches, wait indefinitely on MCP startup, or hand-write tool-call syntax.',
     '',
     'After a successful \x60memorix_project_context\x60 result, the brief is the default retrieval boundary. Do not call more Memorix retrieval tools after a complete brief. Use \x60memorix_context_pack\x60, \x60memorix_search\x60, or \x60memorix_detail\x60 only when the brief lacks a specific reference, freshness field, or fact needed for the task, or when the user explicitly asks for deeper history. In MCP, name that missing fact in \x60purpose\x60 when intentionally expanding beyond the brief. Do not retrieve the same decision twice just to confirm an already-complete brief.',
     'If the user asks for read-only work or says not to modify files, do not call \x60memorix_store\x60 just to record an assessment. Store only when the user explicitly asks to preserve it.',

package/src/hooks/lifecycle.ts

@@ -0,0 +1,173 @@
+/**
+ * Process-level lifecycle for `memorix hook`.
+ *
+ * Hosts invoke this command on every agent event. It must read stdin, emit
+ * one JSON object, and exit. Leftover hook processes are a bug: they reserve
+ * heap, orphan onto PID 1, and can exhaust a laptop.
+ */
+
+import type { ObservationRuntimeOptions } from '../memory/observations.js';
+
+export const DEFAULT_HOOK_TIMEOUT_MS = 20_000;
+export const MIN_HOOK_TIMEOUT_MS = 1_000;
+export const MAX_HOOK_TIMEOUT_MS = 120_000;
+
+export const DEFAULT_HOOK_STDIN_TIMEOUT_MS = 3_000;
+export const MIN_HOOK_STDIN_TIMEOUT_MS = 100;
+export const MAX_HOOK_STDIN_TIMEOUT_MS = 30_000;
+
+type EnvMap = NodeJS.ProcessEnv | Record<string, string | undefined>;
+
+function parseBoundedMs(
+  raw: string | undefined,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  const value = raw?.trim();
+  if (!value) return fallback;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(parsed)));
+}
+
+export function resolveHookTimeoutMs(env: EnvMap = process.env): number {
+  return parseBoundedMs(
+    env.MEMORIX_HOOK_TIMEOUT_MS,
+    DEFAULT_HOOK_TIMEOUT_MS,
+    MIN_HOOK_TIMEOUT_MS,
+    MAX_HOOK_TIMEOUT_MS,
+  );
+}
+
+export function resolveHookStdinTimeoutMs(env: EnvMap = process.env): number {
+  return parseBoundedMs(
+    env.MEMORIX_HOOK_STDIN_TIMEOUT_MS,
+    DEFAULT_HOOK_STDIN_TIMEOUT_MS,
+    MIN_HOOK_STDIN_TIMEOUT_MS,
+    MAX_HOOK_STDIN_TIMEOUT_MS,
+  );
+}
+
+export function hookObservationRuntimeOptions(projectRoot: string): ObservationRuntimeOptions {
+  return {
+    embeddingWriteMode: 'deferred',
+    projectRoot,
+  };
+}
+
+type HookStdin = NodeJS.ReadableStream & {
+  pause?: () => void;
+  destroy?: (error?: Error) => void;
+  unref?: () => void;
+  isTTY?: boolean;
+};
+
+/**
+ * Read hook JSON from a pipe. Resolves on EOF, stream error, or idle timeout.
+ * Always releases the stream so an open stdin cannot keep Node alive.
+ */
+export async function readHookStdin(stdin: HookStdin, timeoutMs: number): Promise<string> {
+  return new Promise<string>((resolve) => {
+    const chunks: Buffer[] = [];
+    let settled = false;
+
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      stdin.removeListener('data', onData);
+      stdin.removeListener('end', finish);
+      stdin.removeListener('error', finish);
+      stdin.pause?.();
+      if (!stdin.isTTY) {
+        stdin.destroy?.();
+      } else {
+        stdin.unref?.();
+      }
+      resolve(Buffer.concat(chunks).toString('utf-8').trim());
+    };
+
+    const onData = (chunk: Buffer | string) => {
+      chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+    };
+
+    const timer = setTimeout(finish, timeoutMs);
+    stdin.on('data', onData);
+    stdin.on('end', finish);
+    stdin.on('error', finish);
+  });
+}
+
+export interface HookDeadlineIo {
+  write(chunk: string): unknown;
+}
+
+export interface HookDeadlineOptions {
+  timeoutMs: number;
+  run: () => Promise<void>;
+  stdout?: HookDeadlineIo;
+  stderr?: HookDeadlineIo;
+  exit?: (code: number) => void;
+}
+
+function writeContinue(stdout: HookDeadlineIo): void {
+  try {
+    stdout.write(JSON.stringify({ continue: true }));
+  } catch {
+    // The host already closed the pipe. Exiting is still required.
+  }
+}
+
+/**
+ * Run a hook body under a hard deadline, then force-exit.
+ * `withTimeout` cannot abort in-flight fetches; process.exit is the backstop.
+ */
+export async function runHookWithDeadline(options: HookDeadlineOptions): Promise<void> {
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const exit = options.exit ?? ((code: number) => { process.exit(code); });
+
+  await new Promise<void>((resolve) => {
+    let finished = false;
+
+    const settle = () => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      resolve();
+    };
+
+    const timer = setTimeout(() => {
+      if (finished) return;
+      try {
+        stderr.write(`[memorix] hook timed out after ${options.timeoutMs}ms\n`);
+      } catch {
+        // stderr may already be closed
+      }
+      writeContinue(stdout);
+      exit(0);
+      settle();
+    }, options.timeoutMs);
+
+    options.run().then(
+      () => {
+        if (finished) return;
+        exit(0);
+        settle();
+      },
+      (error: unknown) => {
+        if (finished) return;
+        try {
+          const message = error instanceof Error ? error.message : String(error);
+          stderr.write(`[memorix] hook failed: ${message}\n`);
+        } catch {
+          // stderr may already be closed
+        }
+        writeContinue(stdout);
+        exit(0);
+        settle();
+      },
+    );
+  });
+}

package/src/hooks/official-skills.ts

@@ -31,8 +31,8 @@ export const OFFICIAL_MEMORIX_SKILLS: OfficialMemorixSkill[] = [
       '',
       '| Situation | Prefer | CLI fallback |',
       '|---|---|---|',
-      '| Starting a coding task and needing the best task-lensed project map | `memorix_project_context` with the user\'s task | `memorix context "<task>" --json` |',
-      '| Continuing prior project work | `memorix_project_context` with the user\'s task | `memorix resume "<task>" --json` |',
+      '| Starting a coding task and needing the best task-lensed project map | `memorix_project_context` with the user\'s task | `memorix context "<task>" --brief-json` |',
+      '| Continuing prior project work | `memorix_project_context` with the user\'s task | `memorix resume "<task>" --brief-json` |',
       '| Need structured refs/freshness for code-bound memories | `memorix_context_pack` | `memorix codegraph context-pack --task "<topic>"` |',
       '| Explicit memory graph question | `memorix_graph_context` | `memorix memory graph-context --query "<topic>"` |',
       '| Specific past decision, bug, file, or change | `memorix_search` | `memorix memory search --query "<topic>"` |',
@@ -45,7 +45,7 @@ export const OFFICIAL_MEMORIX_SKILLS: OfficialMemorixSkill[] = [
       '',
       '- Default first step for non-trivial coding work: call `memorix_project_context` before progress files, dev-log reads, ad-hoc file reads, or git archaeology. Pass the user\'s actual task so Memorix can choose a bugfix, feature, release, onboarding, refactor, docs, test, or general brief. Start by reading its suggested files.',
       '- In Claude Code headless/print-mode, an initial MCP `pending` status is not a failure by itself. Prefer MCP first: use the client\'s tool discovery/dynamic loading to find `memorix_project_context` when it is not in the first visible tool list.',
-      '- Continuation fallback is mandatory: when the user asks to continue, resume, take over, or explain prior work and MCP cannot be called in this turn, run `memorix resume "<task>" --json` exactly once before inspecting files, Git history, progress notes, or guessing. The absence of `.memorix` or visible memory files never proves project memory is empty. For a new task, use `memorix context "<task>" --json` instead. If that one command fails, report it and proceed normally; do not probe help, enumerate commands, or chain broad searches.',
+      '- Continuation fallback is mandatory: when the user asks to continue, resume, take over, or explain prior work and MCP cannot be called in this turn, run `memorix resume "<task>" --brief-json` exactly once before inspecting files, Git history, progress notes, or guessing. The absence of `.memorix` or visible memory files never proves project memory is empty. For a new task, use `memorix context "<task>" --brief-json` instead. Use `--json` only when a diagnostic needs the detailed legacy payload. If that one command fails, report it and proceed normally; do not probe help, enumerate commands, or chain broad searches.',
       '- After a successful `memorix_project_context`, the brief is the default retrieval boundary. Do not call more Memorix retrieval tools after a complete brief. Use Context Pack, search, or detail only when the brief lacks a specific reference, freshness field, or fact needed for the task, or when the user explicitly asks for deeper history. In MCP, name that missing fact in `purpose` when intentionally expanding beyond the brief. Do not retrieve the same decision twice just to confirm an already-complete brief.',
       '- If the user asks for read-only work or says not to modify files, do not call `memorix_store` just to record an assessment. Store only when the user explicitly asks to preserve it.',
       '- Use `memorix_search` for a specific decision, bug, file, or prior change that the project context did not answer. Fetch detail only for a result you still need after the brief.',

package/src/hooks/rules/memorix-agent-rules.md

@@ -7,7 +7,7 @@ You have access to Memorix memory tools. Follow these rules to maintain persiste
 At the beginning of non-trivial coding work, use Memorix Memory Autopilot before local progress notes or broad file exploration. A session bind is not required for every conversation.
 
 1. Default first step for non-trivial coding work: call `memorix_project_context` with the user's actual task before progress files, dev-log reads, ad-hoc file reads, or git archaeology. Memorix will choose a task-lensed brief (bugfix, feature, release, onboarding, refactor, docs, test, or general). Treat its "Start here" files as the first code or docs to inspect.
-2. If the MCP tool is not visible yet but the client supports tool discovery or dynamic loading, search/select `memorix_project_context` first. Continuation fallback is mandatory: when the user asks to continue, resume, take over, or explain prior work and MCP cannot be called in this turn, run exactly one CLI brief with the user's real task before inspecting files, Git history, progress notes, or guessing: use `memorix resume "<task>" --json`. For a new task, use `memorix context "<task>" --json` instead. The absence of `.memorix` or visible memory files never proves project memory is empty. If that one command fails, report it and proceed normally. Do not probe help, enumerate commands, chain broad searches, wait indefinitely on MCP startup, or hand-write tool-call syntax.
+2. If the MCP tool is not visible yet but the client supports tool discovery or dynamic loading, search/select `memorix_project_context` first. Continuation fallback is mandatory: when the user asks to continue, resume, take over, or explain prior work and MCP cannot be called in this turn, run exactly one CLI brief with the user's real task before inspecting files, Git history, progress notes, or guessing: use `memorix resume "<task>" --brief-json`. For a new task, use `memorix context "<task>" --brief-json` instead. The absence of `.memorix` or visible memory files never proves project memory is empty. If that one command fails, report it and proceed normally. Do not probe help, enumerate commands, chain broad searches, wait indefinitely on MCP startup, or hand-write tool-call syntax. Use `--json` only when a diagnostic needs the detailed legacy payload.
 3. After a successful `memorix_project_context` result, the brief is the default retrieval boundary. Do not call more Memorix retrieval tools after a complete brief. Use `memorix_context_pack`, `memorix_search`, or `memorix_detail` only when the brief lacks a specific reference, freshness field, or fact needed for the task, or when the user explicitly asks for deeper history. In MCP, name that missing fact in `purpose` when intentionally expanding beyond the brief. Do not retrieve the same decision twice just to confirm an already-complete brief.
    If the user asks for read-only work or says not to modify files, do not call `memorix_store` just to record an assessment. Store only when the user explicitly asks to preserve it.
 4. Use `memorix_context_pack` when you need structured refs and freshness for code-bound memories.

package/src/knowledge/context-receipt.ts

@@ -0,0 +1,41 @@
+import type { CodeGraphProviderQuality } from '../codegraph/types.js';
+import type { TaskWorkset } from './workset.js';
+
+/**
+ * A small machine-readable counterpart to the agent-facing Workset prompt.
+ * Detailed CLI JSON remains available for diagnostics; this shape is for
+ * clients that need a bounded handoff without loading raw stores.
+ */
+export interface BoundedContextReceipt {
+  schemaVersion: '1';
+  task: string;
+  brief: string;
+  receipt: TaskWorkset['receipt'];
+  code: {
+    selected: CodeGraphProviderQuality['selected'];
+    quality: CodeGraphProviderQuality['selectedQuality'];
+    externalState: CodeGraphProviderQuality['external']['state'];
+    snapshotId?: string;
+  };
+  loadout?: TaskWorkset['agentLoadout'];
+}
+
+export function buildBoundedContextReceipt(input: {
+  workset: TaskWorkset;
+  providerQuality?: CodeGraphProviderQuality;
+}): BoundedContextReceipt {
+  const provider = input.providerQuality ?? input.workset.provenance.codeProvider;
+  return {
+    schemaVersion: '1',
+    task: input.workset.task,
+    brief: input.workset.prompt,
+    receipt: input.workset.receipt,
+    code: {
+      selected: provider?.selected ?? 'lite',
+      quality: provider?.selectedQuality ?? 'heuristic',
+      externalState: provider?.external.state ?? 'not-detected',
+      ...(input.workset.provenance.snapshotId ? { snapshotId: input.workset.provenance.snapshotId } : {}),
+    },
+    ...(input.workset.agentLoadout ? { loadout: input.workset.agentLoadout } : {}),
+  };
+}

package/src/knowledge/workflows.ts

@@ -22,7 +22,7 @@ import type {
 } from './workflow-types.js';
 import type { KnowledgeWorkspace } from './workspace-types.js';
 
-const KNOWN_AGENTS: AgentTarget[] = [
+export const WORKFLOW_AGENT_TARGETS: AgentTarget[] = [
   'windsurf',
   'cursor',
   'claude-code',
@@ -117,7 +117,7 @@ function optionalStatus(data: Record<string, unknown>): WorkflowStatus {
 }
 
 function normalizeAgents(values: string[]): AgentTarget[] {
-  const unknown = values.filter(value => !KNOWN_AGENTS.includes(value as AgentTarget));
+  const unknown = values.filter(value => !WORKFLOW_AGENT_TARGETS.includes(value as AgentTarget));
   if (unknown.length > 0) {
     throw new Error('workflow frontmatter has unsupported agent: ' + unknown[0]);
   }
@@ -459,12 +459,15 @@ function taskScore(workflow: WorkflowSpec, task: string): { score: number; reaso
 export function selectWorkflows(input: {
   workflows: WorkflowSpec[];
   task: string;
+  /** Only select workflows that explicitly support the target agent. */
+  agent?: AgentTarget;
   projectId?: string;
   store?: WorkflowStore;
   limit?: number;
 }): WorkflowSelection[] {
   const selected = input.workflows
-    .filter(workflow => workflow.status === 'active')
+    .filter(workflow => workflow.status === 'active'
+      && (!input.agent || workflow.compatibleAgents.includes(input.agent)))
     .map(workflow => {
       const match = taskScore(workflow, input.task);
       const cautions = input.store && input.projectId

package/src/knowledge/workset.ts

@@ -8,6 +8,7 @@ import { WorkflowStore } from './workflow-store.js';
 import { OutcomeStore } from './outcome-store.js';
 import { qualityFromOutcome, type OutcomeQuality } from './outcome-types.js';
 import { selectWorkflows } from './workflows.js';
+import type { AgentTarget } from '../types.js';
 import { renderLongTermMemorySummary, selectLongTermMemoriesForTask } from '../memory/long-term.js';
 import { governContextCandidates, type GovernancePlan } from './governor.js';
 import type {
@@ -73,6 +74,18 @@ export interface WorksetWorkflow {
   cautions: string[];
 }
 
+/**
+ * A task-scoped plan assembled from existing workflow and wiki assets. It is
+ * descriptive rather than an authorization boundary: host agents retain their
+ * own tool and approval policies.
+ */
+export interface WorksetAgentLoadout {
+  agent: AgentTarget;
+  workflowIds: string[];
+  requiredContext: string[];
+  allowedTools: string[];
+}
+
 export interface WorksetMemorySource {
   id: number;
   title: string;
@@ -156,6 +169,7 @@ export interface TaskWorkset {
   pages: WorksetPage[];
   durableMemory: WorksetLongTermMemory[];
   workflows: WorksetWorkflow[];
+  agentLoadout?: WorksetAgentLoadout;
   cautions: WorksetCaution[];
   verification: string[];
   evidenceIds: string[];
@@ -179,6 +193,8 @@ export interface BuildTaskWorksetInput {
   projectId: string;
   dataDir: string;
   task?: string;
+  /** Optional target used to select workflows explicitly compatible with this agent. */
+  agent?: AgentTarget;
   lens: string;
   currentFacts?: string[];
   continuation?: WorksetContinuation;
@@ -313,6 +329,18 @@ function workflowOutput(selection: WorkflowSelection): WorksetWorkflow {
   };
 }
 
+function workflowLoadout(agent: AgentTarget | undefined, selections: WorkflowSelection[]): WorksetAgentLoadout | undefined {
+  if (!agent) return undefined;
+  return {
+    agent,
+    workflowIds: selections.map(selection => selection.workflow.id),
+    requiredContext: unique(selections.flatMap(selection => selection.workflow.requiredContext))
+      .map(item => short(item, 18)).slice(0, 4),
+    allowedTools: unique(selections.flatMap(selection => selection.workflow.allowedTools))
+      .map(item => short(item, 12)).slice(0, 6),
+  };
+}
+
 function appendLine(
   lines: string[],
   candidate: string,
@@ -853,6 +881,23 @@ export function renderTaskWorksetPrompt(input: Omit<TaskWorkset, 'prompt' | 'bud
     }
   }
 
+  if (input.agentLoadout) {
+    appendLine(lines, '', maxTokens, omitted, 'agent-loadout-heading');
+    appendLine(lines, 'Agent loadout (' + input.agentLoadout.agent + ')', maxTokens, omitted, 'agent-loadout-heading');
+    for (const required of input.agentLoadout.requiredContext.slice(0, 2)) {
+      appendLine(lines, '- Need: ' + required, maxTokens, omitted, 'agent-loadout-context');
+    }
+    if (input.agentLoadout.allowedTools.length > 0) {
+      appendLine(
+        lines,
+        '- Workflow tools: ' + input.agentLoadout.allowedTools.join(', '),
+        maxTokens,
+        omitted,
+        'agent-loadout-tools',
+      );
+    }
+  }
+
   if (input.verification.length > 0) {
     appendLine(lines, '', maxTokens, omitted, 'verification-heading');
     appendLine(lines, 'Verify', maxTokens, omitted, 'verification-heading');
@@ -965,6 +1010,7 @@ export async function buildTaskWorkset(input: BuildTaskWorksetInput): Promise<Ta
   let workspace: KnowledgeWorkspace | undefined;
   let pages: WorksetPage[] = [];
   let workflows: WorksetWorkflow[] = [];
+  let workflowSelections: WorkflowSelection[] = [];
   try {
     workspace = await preferredWorkspace(input.projectId, input.dataDir);
     if (workspace) {
@@ -985,14 +1031,15 @@ export async function buildTaskWorkset(input: BuildTaskWorksetInput): Promise<Ta
       if (task) {
         const workflowStore = new WorkflowStore();
         await workflowStore.init(input.dataDir);
-        const selected = selectWorkflows({
+        workflowSelections = selectWorkflows({
           workflows: workflowStore.listWorkflows(workspace.id, 'active'),
           task,
           projectId: input.projectId,
           store: workflowStore,
+          ...(input.agent ? { agent: input.agent } : {}),
           limit: 2,
         });
-        workflows = selected.map(workflowOutput);
+        workflows = workflowSelections.map(workflowOutput);
         for (const workflow of workflows) {
           for (const caution of workflow.cautions) {
             cautions.push({ kind: 'workflow-failed-verification', message: caution });
@@ -1018,6 +1065,10 @@ export async function buildTaskWorkset(input: BuildTaskWorksetInput): Promise<Ta
     workflows,
   });
   const governedDurableIds = new Set(governed.durableMemory.map(memory => memory.id));
+  const agentLoadout = workflowLoadout(
+    input.agent,
+    workflowSelections.filter(selection => governed.workflows.some(workflow => workflow.id === selection.workflow.id)),
+  );
   const evidenceIds = unique(governed.claims.flatMap(claim => evidenceIdsForClaim(
     claim,
     evidenceByClaim.get(claim.id) ?? [],
@@ -1084,6 +1135,9 @@ export async function buildTaskWorkset(input: BuildTaskWorksetInput): Promise<Ta
     pages: pages.filter(page => page.claimIds.some(claimId => governed.claims.some(claim => claim.id === claimId))),
     durableMemory: governed.durableMemory,
     workflows: governed.workflows,
+    ...(agentLoadout
+      ? { agentLoadout }
+      : {}),
     cautions: normalizedCautions,
     verification,
     evidenceIds,