@openagents-org/agent-launcher 0.2.165 → 0.2.167

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openagents-org/agent-launcher",
-  "version": "0.2.165",
+  "version": "0.2.167",
   "description": "OpenAgents Launcher \u2014 install, configure, and run AI coding agents from your terminal",
   "main": "src/index.js",
   "bin": {

package/src/adapters/amp.js

@@ -48,6 +48,8 @@ class AmpAdapter extends BaseAdapter {
   constructor(opts) {
     super(opts);
     this.disabledModules = opts.disabledModules || new Set();
+    // Pin the channel's decision log + glossary into the system prompt.
+    this._usesPinnedContext = true;
 
     // channel -> Amp thread id (for `amp threads continue <id>`)
     this._channelThreads = {};
@@ -181,6 +183,7 @@ class AmpAdapter extends BaseAdapter {
       mode: this._mode,
       disabledModules: this.disabledModules,
       browserEnabled,
+      ...this.pinnedPromptOpts(channelName),
     });
   }
 

package/src/adapters/base.js

@@ -20,6 +20,12 @@
 const { WorkspaceClient, SessionRevokedError } = require('../workspace-client');
 const { generateSessionTitle, SESSION_DEFAULT_RE } = require('./utils');
 const { defaultAgentWorkdir } = require('../paths');
+const {
+  decisionLogTitle,
+  glossaryTitle,
+  WORKSPACE_GLOSSARY_TITLE,
+  pickEntryByTitle,
+} = require('./decision-log');
 const {
   REASON,
   classifyJoinError,
@@ -85,6 +91,22 @@ class BaseAdapter {
     // workspace flag must reconnect/restart to pick up the change (matches
     // the Python adapter behavior in workspace_prompt.py).
     this._browserEnabledCache = null;
+    // ── Knowledge pinning (decision log + glossary) ──
+    // Entry-id caches make the steady state a single GET per pinned entry;
+    // reads happen on EVERY message, so they get a hard short deadline
+    // instead of the client's default 15s — a workspace hiccup must cost the
+    // turn a couple of seconds, not half a minute.
+    this._decisionEntryIds = {}; // channel → knowledge entry id of its decision log
+    this._glossaryEntryIds = {}; // channel → knowledge entry id of its glossary
+    this._DECISION_FETCH_TIMEOUT_MS = 2000;
+    this._warnedKnowledgeDisabled = false;
+    this._pinnedStatusWarned = new Set(); // channels already told pinning is inactive
+    // Subclasses whose sync prompt builders consume pinnedPromptOpts() set
+    // this true; the channel worker then refreshes _pinnedContext before
+    // every _handleMessage call. Adapters with their own pinning flow
+    // (Claude) fetch directly instead and leave it false.
+    this._usesPinnedContext = false;
+    this._pinnedContext = {}; // channel → { decisions, glossary }
     // Wall-clock timestamp of adapter init, used by the `status` control
     // action to report uptime back to the channel. Reset on reinstantiation
     // (e.g. after a `restart` IPC bounce) so uptime tracks "time since last
@@ -747,6 +769,7 @@ class BaseAdapter {
   async _channelWorker(channel, msg) {
     this._channelBusy.add(channel);
     try {
+      await this._prefetchPinnedContext(channel);
       await this._handleMessage(msg);
     } catch (e) {
       this._log(`Error in channel worker for ${channel}: ${e.message}`);
@@ -762,6 +785,8 @@ class BaseAdapter {
         try { await this.sendStatus(channel, 'processing queued message', { queue_id: nextMsg._queueId, queue_status: 'processed' }); } catch {}
       }
       try {
+        // Pinned entries may have changed while this message waited.
+        await this._prefetchPinnedContext(channel);
         await this._handleMessage(nextMsg);
       } catch (e) {
         this._log(`Error processing queued message in ${channel}: ${e.message}`);
@@ -771,6 +796,200 @@ class BaseAdapter {
     this._channelBusy.delete(channel);
   }
 
+  // ------------------------------------------------------------------
+  // Knowledge pinning (decision log + glossary)
+  // ------------------------------------------------------------------
+
+  /**
+   * Read one pinned knowledge entry with a short per-request deadline
+   * (worst case one list + one get, ~2x that budget). `titles` is tried in
+   * precedence order against a single listing; `cache` maps channel → entry
+   * id. Returns { available, state, entryId, content, error }:
+   * - available=false  → knowledge module disabled, pinning inactive
+   * - state 'found'    → the entry exists (entryId set; content null when a
+   *                      transient error hid it this turn)
+   * - state 'absent'   → a successful listing confirmed no entry exists
+   * - state 'unknown'  → fetch failed before existence could be confirmed;
+   *                      the prompt must NOT claim the entry is missing, or a
+   *                      recovered network mid-turn produces a duplicate
+   * - error=true       → transient failure; callers must NOT treat this as
+   *                      "entry changed/empty"
+   * The matched entry id is cached per channel so the steady state is a
+   * single GET; a 404 or a soft-deleted entry (the backend keeps deleted
+   * rows readable by id with status "deleted") invalidates the cache and
+   * falls back to list+match, which only sees active entries.
+   */
+  async _fetchPinnedEntry(channel, titles, cache, label) {
+    if ((this.disabledModules || new Set()).has('knowledge')) {
+      if (!this._warnedKnowledgeDisabled) {
+        this._warnedKnowledgeDisabled = true;
+        this._log(
+          'Knowledge module is disabled — decision-log pinning is INACTIVE. ' +
+          'Confirmed decisions will not survive context compaction or session resets.'
+        );
+      }
+      if (!this._pinnedStatusWarned.has(channel)) {
+        this._pinnedStatusWarned.add(channel);
+        try {
+          await this.sendStatus(
+            channel,
+            'Decision pinning inactive: the knowledge module is disabled for ' +
+            'this agent, so confirmed decisions and the shared glossary ' +
+            'cannot be pinned across session resets.'
+          );
+        } catch {}
+      }
+      return { available: false, state: 'unknown', entryId: null, title: null, content: null, error: false };
+    }
+
+    const timeout = this._DECISION_FETCH_TIMEOUT_MS;
+    // Only highest-precedence matches are ever cached (see below), so a
+    // cached id always belongs to titles[0].
+    const cachedId = cache[channel];
+    if (cachedId) {
+      try {
+        const entry = await this.client.getKnowledge(this.workspaceId, this.token, cachedId, { timeout });
+        if (entry && entry.status && entry.status !== 'active') {
+          // Soft-deleted: still served by id, but dead for updates.
+          delete cache[channel];
+          // Fall through to list+match below.
+        } else if (entry && typeof entry.title === 'string' && entry.title !== titles[0]) {
+          // Renamed (e.g. archived): the id no longer owns the canonical
+          // title, so the pin must re-resolve — a fallback or a replacement
+          // entry has to win over the stale cache.
+          delete cache[channel];
+          // Fall through to list+match below.
+        } else {
+          return { available: true, state: 'found', entryId: cachedId, title: titles[0], content: (entry && entry.content) || '', error: false };
+        }
+      } catch (e) {
+        if (/not found|HTTP 404/i.test(e.message || '')) {
+          delete cache[channel];
+          // Entry is gone — fall through to list+match below.
+        } else {
+          this._log(`${label} read failed (${e.message}) — reusing last known state`);
+          return { available: true, state: 'found', entryId: cachedId, title: titles[0], content: null, error: true };
+        }
+      }
+    }
+
+    try {
+      const data = await this.client.listKnowledge(this.workspaceId, this.token, { limit: 500, timeout });
+      const entries = (data && data.entries) || [];
+      let entry = null;
+      let matchedTitle = null;
+      for (const title of titles) {
+        const picked = pickEntryByTitle(entries, title);
+        if (picked.duplicates > 0) {
+          this._log(
+            `${label} WARNING for ${channel} — ${picked.duplicates + 1} knowledge entries share the title ` +
+            `"${title}"; using the earliest. The duplicates should be merged manually.`
+          );
+        }
+        if (picked.entry) { entry = picked.entry; matchedTitle = title; break; }
+      }
+      if (!entry) return { available: true, state: 'absent', entryId: null, title: null, content: null, error: false };
+      // Cache ONLY a highest-precedence match. Caching a fallback (e.g. the
+      // workspace glossary) under the channel key would let the cached-id
+      // fast path skip the precedence check forever, permanently masking a
+      // channel-specific entry created later. Fallback users pay one extra
+      // list per message instead.
+      if (matchedTitle === titles[0]) cache[channel] = entry.id;
+      const full = await this.client.getKnowledge(this.workspaceId, this.token, entry.id, { timeout });
+      if (full && full.status && full.status !== 'active') {
+        // Deleted between the listing and the read.
+        delete cache[channel];
+        return { available: true, state: 'absent', entryId: null, title: null, content: null, error: false };
+      }
+      return { available: true, state: 'found', entryId: entry.id, title: matchedTitle, content: (full && full.content) || '', error: false };
+    } catch (e) {
+      this._log(`${label} fetch failed (${e.message}) — reusing last known state`);
+      const knownId = cache[channel] || null;
+      return { available: true, state: knownId ? 'found' : 'unknown', entryId: knownId, title: knownId ? titles[0] : null, content: null, error: true };
+    }
+  }
+
+  /** Read the channel's decision log. See _fetchPinnedEntry for the contract. */
+  async _fetchDecisionLog(channel) {
+    return this._fetchPinnedEntry(channel, [decisionLogTitle(channel)], this._decisionEntryIds, 'Decision log');
+  }
+
+  /**
+   * Read the channel's glossary — the channel-specific entry when it exists,
+   * else the workspace-wide fallback. See _fetchPinnedEntry for the contract.
+   * The result carries scope 'channel' | 'workspace' (null when not found)
+   * so prompts can treat the shared fallback as read-only.
+   */
+  async _fetchGlossary(channel) {
+    const res = await this._fetchPinnedEntry(
+      channel,
+      [glossaryTitle(channel), WORKSPACE_GLOSSARY_TITLE],
+      this._glossaryEntryIds,
+      'Glossary'
+    );
+    res.scope = res.title === WORKSPACE_GLOSSARY_TITLE ? 'workspace'
+      : res.title ? 'channel' : null;
+    return res;
+  }
+
+  /** Fetch everything pinnable for a channel: { decisions, glossary }. */
+  async _fetchPinnedContext(channel) {
+    const decisions = await this._fetchDecisionLog(channel);
+    const glossary = await this._fetchGlossary(channel);
+    return { decisions, glossary };
+  }
+
+  /**
+   * Refresh the pinned context ahead of _handleMessage for adapters that
+   * opted in (_usesPinnedContext). A transient read failure must not wipe
+   * the last successful pin — prompt-per-turn adapters would lose the
+   * authoritative definitions for that turn — so an errored entry keeps the
+   * previous good result; a thrown fetch keeps the previous context whole.
+   */
+  async _prefetchPinnedContext(channel) {
+    if (!this._usesPinnedContext) return;
+    try {
+      const fresh = await this._fetchPinnedContext(channel);
+      const prev = this._pinnedContext[channel];
+      if (prev) {
+        if (fresh.decisions && fresh.decisions.error && prev.decisions && !prev.decisions.error) {
+          fresh.decisions = prev.decisions;
+        }
+        if (fresh.glossary && fresh.glossary.error && prev.glossary && !prev.glossary.error) {
+          fresh.glossary = prev.glossary;
+        }
+      }
+      this._pinnedContext[channel] = fresh;
+    } catch (e) {
+      this._log(`Pinned-context fetch failed (${e && e.message ? e.message : e}) — reusing the last pinned context`);
+    }
+  }
+
+  /**
+   * Prompt-builder options ({ decisionLog, glossary }) derived from the last
+   * prefetch for the channel. Sync, so prompt builders can call it inline;
+   * returns {} when nothing was prefetched or nothing is usable.
+   */
+  pinnedPromptOpts(channel) {
+    const ctx = this._pinnedContext[channel];
+    if (!ctx) return {};
+    const opts = {};
+    const d = ctx.decisions;
+    if (d && d.available) {
+      opts.decisionLog = {
+        enabled: true,
+        state: d.state,
+        entryId: d.entryId,
+        content: d.error ? '' : (d.content || ''),
+      };
+    }
+    const g = ctx.glossary;
+    if (g && g.available && g.state === 'found' && g.content) {
+      opts.glossary = { enabled: true, entryId: g.entryId, content: g.content, scope: g.scope || 'channel' };
+    }
+    return opts;
+  }
+
   // ------------------------------------------------------------------
   // Auto-title helper
   // ------------------------------------------------------------------

package/src/adapters/claude.js

@@ -19,7 +19,7 @@ const { execSync, spawn } = require('child_process');
 const BaseAdapter = require('./base');
 const { formatAttachmentsForPrompt, SESSION_DEFAULT_RE, generateSessionTitle } = require('./utils');
 const { buildClaudeSystemPrompt, buildClaudeSkillMd, workspaceSkillName } = require('./workspace-prompt');
-const { decisionLogTitle, decisionFingerprint, pickDecisionEntry, sampleRecap } = require('./decision-log');
+const { pinnedFingerprint, sampleRecap } = require('./decision-log');
 const { defaultAgentWorkdir, whichBinary, whereBinary } = require('../paths');
 
 const IS_WINDOWS = process.platform === 'win32';
@@ -99,12 +99,9 @@ class ClaudeAdapter extends BaseAdapter {
     // a new message starts processing in the channel.
     this._stopNoticeSent = new Set();
     this._persistentProcs = {}; // channel → { proc, lineBuffer, pendingLines, idleTimer, messageResolve }
-    this._decisionEntryIds = {}; // channel → knowledge entry id of its decision log
-    // Decision-log reads happen on EVERY message, so they get a hard short
-    // deadline instead of the client's default 15s — a workspace hiccup must
-    // cost the turn a couple of seconds, not half a minute.
-    this._DECISION_FETCH_TIMEOUT_MS = 2000;
-    this._warnedKnowledgeDisabled = false;
+    // Knowledge pinning (decision log + glossary) lives in BaseAdapter; this
+    // adapter fetches directly in _handleMessage because the result also
+    // drives the persistent-process staleness check.
     this._IDLE_TIMEOUT_MS = 60 * 60 * 1000; // 1 hour
     this._WATCHDOG_INTERVAL_MS = 15_000; // 15s between checks
     this._WATCHDOG_MAX_TIMEOUTS = 20;    // 20 * 15s = 5 min of silence → kill
@@ -315,85 +312,6 @@ class ClaudeAdapter extends BaseAdapter {
     );
   }
 
-  /**
-   * Read the channel's decision log (a knowledge entry) with a short
-   * per-request deadline (worst case one list + one get, ~2x that budget).
-   * Returns { available, state, entryId, content, error }:
-   * - available=false  → knowledge module disabled, pinning inactive
-   * - state 'found'    → the entry exists (entryId set; content null when a
-   *                      transient error hid it this turn)
-   * - state 'absent'   → a successful listing confirmed no entry exists
-   * - state 'unknown'  → fetch failed before existence could be confirmed;
-   *                      the prompt must NOT claim the log is missing, or a
-   *                      recovered network mid-turn produces a duplicate
-   * - error=true       → transient failure; callers must NOT treat this as
-   *                      "log changed/empty"
-   * The matched entry id is cached per channel so the steady state is a
-   * single GET; a 404 or a soft-deleted entry (the backend keeps deleted
-   * rows readable by id with status "deleted") invalidates the cache and
-   * falls back to list+match, which only sees active entries.
-   */
-  async _fetchDecisionLog(channel) {
-    if (this.disabledModules.has('knowledge')) {
-      if (!this._warnedKnowledgeDisabled) {
-        this._warnedKnowledgeDisabled = true;
-        this._log(
-          'Knowledge module is disabled — decision-log pinning is INACTIVE. ' +
-          'Confirmed decisions will not survive context compaction or session resets.'
-        );
-      }
-      return { available: false, state: 'unknown', entryId: null, content: null, error: false };
-    }
-
-    const timeout = this._DECISION_FETCH_TIMEOUT_MS;
-    const cachedId = this._decisionEntryIds[channel];
-    if (cachedId) {
-      try {
-        const entry = await this.client.getKnowledge(this.workspaceId, this.token, cachedId, { timeout });
-        if (entry && entry.status && entry.status !== 'active') {
-          // Soft-deleted: still served by id, but dead for updates.
-          delete this._decisionEntryIds[channel];
-          // Fall through to list+match below.
-        } else {
-          return { available: true, state: 'found', entryId: cachedId, content: (entry && entry.content) || '', error: false };
-        }
-      } catch (e) {
-        if (/not found|HTTP 404/i.test(e.message || '')) {
-          delete this._decisionEntryIds[channel];
-          // Entry is gone — fall through to list+match below.
-        } else {
-          this._log(`Decision log read failed (${e.message}) — reusing last known state`);
-          return { available: true, state: 'found', entryId: cachedId, content: null, error: true };
-        }
-      }
-    }
-
-    try {
-      const data = await this.client.listKnowledge(this.workspaceId, this.token, { limit: 500, timeout });
-      const entries = (data && data.entries) || [];
-      const { entry, duplicates } = pickDecisionEntry(entries, channel);
-      if (duplicates > 0) {
-        this._log(
-          `Decision log WARNING for ${channel} — ${duplicates + 1} knowledge entries share the title ` +
-          `"${decisionLogTitle(channel)}"; using the earliest. The duplicates should be merged manually.`
-        );
-      }
-      if (!entry) return { available: true, state: 'absent', entryId: null, content: null, error: false };
-      this._decisionEntryIds[channel] = entry.id;
-      const full = await this.client.getKnowledge(this.workspaceId, this.token, entry.id, { timeout });
-      if (full && full.status && full.status !== 'active') {
-        // Deleted between the listing and the read.
-        delete this._decisionEntryIds[channel];
-        return { available: true, state: 'absent', entryId: null, content: null, error: false };
-      }
-      return { available: true, state: 'found', entryId: entry.id, content: (full && full.content) || '', error: false };
-    } catch (e) {
-      this._log(`Decision log fetch failed (${e.message}) — reusing last known state`);
-      const knownId = this._decisionEntryIds[channel] || null;
-      return { available: true, state: knownId ? 'found' : 'unknown', entryId: knownId, content: null, error: true };
-    }
-  }
-
   /**
    * Post "Execution stopped by user." at most once per channel for a given
    * stop. The control-action handler and the in-flight message handler both
@@ -530,7 +448,7 @@ class ClaudeAdapter extends BaseAdapter {
     return null;
   }
 
-  _buildClaudeCmd(prompt, channelName, { skipResume = false, browserEnabled = false, decisionLog = null } = {}) {
+  _buildClaudeCmd(prompt, channelName, { skipResume = false, browserEnabled = false, decisionLog = null, glossary = null } = {}) {
     const claudeBin = this._findClaudeBinary();
     if (!claudeBin) {
       throw new Error('claude CLI not found. Install with: curl -fsSL https://claude.ai/install.sh | bash');
@@ -547,6 +465,7 @@ class ClaudeAdapter extends BaseAdapter {
       browserEnabled,
       toolMode: this.toolMode,
       decisionLog,
+      glossary,
     });
 
     const cmd = [claudeBin, '-p', prompt, '--output-format', 'stream-json', '--verbose'];
@@ -637,6 +556,12 @@ class ClaudeAdapter extends BaseAdapter {
       mcpTools.push(`${pfx}workspace_image_search`);
       mcpWriteTools.push(`${pfx}workspace_image_save`);
     }
+    if (!this.disabledModules.has('knowledge')) {
+      // The decision-log/glossary protocol instructs these by name — they
+      // must be callable or the pinned knowledge silently stops updating.
+      mcpTools.push(`${pfx}workspace_list_knowledge`, `${pfx}workspace_read_knowledge`);
+      mcpWriteTools.push(`${pfx}workspace_write_knowledge`);
+    }
     if (!this.disabledModules.has('browser')) {
       mcpTools.push(
         `${pfx}workspace_fetch_url`,
@@ -679,6 +604,7 @@ class ClaudeAdapter extends BaseAdapter {
     ];
     if (this.disabledModules.has('files')) mcpArgs.push('--disable-files');
     if (this.disabledModules.has('browser')) mcpArgs.push('--disable-browser');
+    if (this.disabledModules.has('knowledge')) mcpArgs.push('--disable-knowledge');
 
     // Resolve the MCP server entry point
     let mcpCommand = this._findNodeBin();
@@ -1205,17 +1131,26 @@ class ClaudeAdapter extends BaseAdapter {
 
     await this.sendStatus(msgChannel, 'thinking...');
 
-    // Read the channel's decision log up front — the fast-path staleness
-    // check and any (re)spawn below both need it.
+    // Read the channel's pinned knowledge (decision log + glossary) up front
+    // — the fast-path staleness check and any (re)spawn below both need it.
     const decisions = await this._fetchDecisionLog(msgChannel);
-    // null fingerprint = fetch failed, current state unknown; never treat
+    const glossary = await this._fetchGlossary(msgChannel);
+    // null fingerprint = a fetch failed, current state unknown; never treat
     // that as a change (it would churn respawns on every workspace hiccup).
-    // The fingerprint covers entry id AND content — both are pinned into the
-    // prompt, and a recreated entry can change id without changing content.
-    const decisionHash = decisions.error ? null : decisionFingerprint(decisions.entryId, decisions.content);
+    // The fingerprint covers entry ids AND content — both are pinned into
+    // the prompt, and a recreated entry can change id without changing content.
+    const pinnedHash = (decisions.error || glossary.error)
+      ? null
+      : pinnedFingerprint([
+        { entryId: decisions.entryId, content: decisions.content },
+        { entryId: glossary.entryId, content: glossary.content },
+      ]);
     const decisionLogOpt = decisions.available
       ? { enabled: true, state: decisions.state, entryId: decisions.entryId, content: decisions.error ? '' : (decisions.content || '') }
       : null;
+    const glossaryOpt = (glossary.available && glossary.state === 'found' && glossary.content)
+      ? { enabled: true, entryId: glossary.entryId, content: glossary.content, scope: glossary.scope || 'channel' }
+      : null;
 
     // ── Persistent process fast-path ──
     // If we have a living persistent process for this channel, send via stdin
@@ -1226,17 +1161,17 @@ class ClaudeAdapter extends BaseAdapter {
       // system prompt AND the CLI permission flags (plan mode is read-only,
       // execute skips permissions) — so a process from the other mode can
       // never be reused. This check is deliberately independent of the
-      // decision fingerprint: a failed decision fetch must not keep a
+      // pinned fingerprint: a failed knowledge fetch must not keep a
       // read-only plan process serving execute requests.
       const modeStale = existingPP.spawnMode !== this._mode;
-      const decisionsStale = decisionHash !== null && existingPP.decisionHash !== decisionHash;
-      if (modeStale || decisionsStale) {
+      const pinnedStale = pinnedHash !== null && existingPP.pinnedHash !== pinnedHash;
+      if (modeStale || pinnedStale) {
         // Kill it and fall through to a fresh spawn: --resume keeps the
         // conversation (it lives in the CLI transcript), while the new spawn
-        // carries the current mode and re-pins the current decisions.
+        // carries the current mode and re-pins the current knowledge.
         this._log(modeStale
           ? `Mode changed to ${this._mode} for ${msgChannel} — respawning with resume`
-          : `Decision log changed for ${msgChannel} — respawning with resume to re-pin decisions`);
+          : `Pinned knowledge changed for ${msgChannel} — respawning with resume to re-pin it`);
         await this._killPersistentProc(msgChannel);
       } else {
         this._log(`Reusing persistent process for ${msgChannel}`);
@@ -1302,6 +1237,7 @@ class ClaudeAdapter extends BaseAdapter {
           skipResume: attempt > 0,
           browserEnabled,
           decisionLog: decisionLogOpt,
+          glossary: glossaryOpt,
         });
         cmd = built.cmd;
         mcpConfigFile = built.mcpConfigFile;
@@ -1313,11 +1249,14 @@ class ClaudeAdapter extends BaseAdapter {
       try {
         const pp = this._spawnPersistentProc(msgChannel, cmd, cleanEnv);
         // Remember the spawn-time configuration so the fast-path can detect
-        // staleness on later messages — the decision-log state and the mode
+        // staleness on later messages — the pinned knowledge and the mode
         // (which fixes both the system prompt and the permission flags).
-        pp.decisionHash = decisionLogOpt
-          ? decisionFingerprint(decisionLogOpt.entryId, decisionLogOpt.content)
-          : decisionFingerprint(null, null);
+        // When the fetch errored (pinnedHash null) hash what was actually
+        // pinned, so the next successful fetch triggers a re-pin.
+        pp.pinnedHash = pinnedHash !== null ? pinnedHash : pinnedFingerprint([
+          { entryId: decisionLogOpt && decisionLogOpt.entryId, content: decisionLogOpt && decisionLogOpt.content },
+          { entryId: glossaryOpt && glossaryOpt.entryId, content: glossaryOpt && glossaryOpt.content },
+        ]);
         pp.spawnMode = this._mode;
         this._log(`Spawned persistent process for ${msgChannel} (attempt ${attempt + 1})`);
 

package/src/adapters/codex.js

@@ -34,6 +34,8 @@ class CodexAdapter extends BaseAdapter {
   constructor(opts) {
     super(opts);
     this.disabledModules = opts.disabledModules || new Set();
+    // Pin the channel's decision log + glossary into the system prompt.
+    this._usesPinnedContext = true;
 
     const env = this.agentEnv || process.env;
     this._directApiKey = env.OPENAI_API_KEY || '';
@@ -174,6 +176,7 @@ class CodexAdapter extends BaseAdapter {
       token: this.token,
       mode: this._mode,
       disabledModules: this.disabledModules,
+      ...this.pinnedPromptOpts(channelName),
     });
     const skillsSection = this._buildInstalledSkillsSection();
     return skillsSection ? `${base}\n\n${skillsSection}` : base;

package/src/adapters/copilot.js

@@ -82,6 +82,8 @@ class CopilotAdapter extends BaseAdapter {
   constructor(opts) {
     super(opts);
     this.disabledModules = opts.disabledModules || new Set();
+    // Pin the channel's decision log + glossary into the system prompt.
+    this._usesPinnedContext = true;
 
     const env = this.agentEnv || process.env;
     // Official model env var (verified via `copilot help environment`).
@@ -325,6 +327,7 @@ class CopilotAdapter extends BaseAdapter {
       token: this.token,
       mode: this._mode,
       disabledModules: this.disabledModules,
+      ...this.pinnedPromptOpts(channelName),
     });
   }
 

package/src/adapters/decision-log.js

@@ -1,11 +1,17 @@
 /**
- * Pure helpers for the Claude adapter's decision log ("constraint pinning").
+ * Pure helpers for knowledge pinning ("constraint pinning").
  *
- * The decision log is a per-channel knowledge entry that records every
- * decision the user has confirmed. The adapter re-reads it on every message
- * and injects it into the CLI system prompt — the only position that survives
- * both the CLI's auto-compaction and a session reset. Everything here is
- * side-effect free so it can be unit tested without an adapter instance.
+ * Two kinds of knowledge entries get pinned into agent prompts:
+ * - The decision log: a per-channel entry recording every decision the user
+ *   has confirmed.
+ * - The glossary: a per-channel (or workspace-wide) entry defining shared
+ *   terms and fields, so agents collaborating on the same spec cannot drift
+ *   into different readings of the same name.
+ *
+ * Adapters re-read the pinned entries on every message and inject them into
+ * the prompt — the only position that survives both auto-compaction and a
+ * session reset. Everything here is side-effect free so it can be unit
+ * tested without an adapter instance.
  */
 
 'use strict';
@@ -27,6 +33,20 @@ function decisionLogTitle(channelName) {
   return `Decisions for channel ${channelName}`;
 }
 
+/**
+ * Canonical knowledge-entry title for a channel's glossary. Same exact-title
+ * matching rules as the decision log.
+ */
+function glossaryTitle(channelName) {
+  return `Glossary for channel ${channelName}`;
+}
+
+/**
+ * Workspace-wide glossary fallback: used when a channel has no glossary of
+ * its own, so one shared entry can serve every channel.
+ */
+const WORKSPACE_GLOSSARY_TITLE = 'Workspace glossary';
+
 /**
  * Stable hash of the decision log content. null/undefined and '' hash
  * identically so "no entry yet" never reads as a change.
@@ -49,13 +69,26 @@ function decisionFingerprint(entryId, content) {
 }
 
 /**
- * Pick the channel's decision entry from a knowledge listing: exact-title
- * matches only, earliest created_at wins (concurrent creates produce
- * duplicates — the earliest is the one other turns have been updating).
+ * Fingerprint of EVERYTHING pinned into a spawned process's prompt — an
+ * ordered list of { entryId, content } pairs (decision log first, then the
+ * glossary). Any id or content change in any pinned entry changes the
+ * fingerprint, which is what triggers a respawn-with-resume to re-pin.
+ */
+function pinnedFingerprint(parts) {
+  const h = crypto.createHash('sha256');
+  for (const p of parts || []) {
+    h.update(decisionFingerprint(p && p.entryId, p && p.content), 'utf-8');
+  }
+  return h.digest('hex');
+}
+
+/**
+ * Pick the entry with an exact title match from a knowledge listing;
+ * earliest created_at wins (concurrent creates produce duplicates — the
+ * earliest is the one other turns have been updating).
  * Returns { entry, duplicates } where duplicates counts the extra matches.
  */
-function pickDecisionEntry(entries, channelName) {
-  const title = decisionLogTitle(channelName);
+function pickEntryByTitle(entries, title) {
   const matches = (entries || []).filter((e) => e && e.title === title);
   if (matches.length === 0) return { entry: null, duplicates: 0 };
   const sorted = matches.slice().sort((a, b) => {
@@ -68,6 +101,11 @@ function pickDecisionEntry(entries, channelName) {
   return { entry: sorted[0], duplicates: matches.length - 1 };
 }
 
+/** Back-compat wrapper: pick a channel's decision-log entry by its title. */
+function pickDecisionEntry(entries, channelName) {
+  return pickEntryByTitle(entries, decisionLogTitle(channelName));
+}
+
 /**
  * Fit the decision log into a character budget without ever cutting a line
  * in half. Over budget, whole lines are kept from the head (earliest
@@ -170,10 +208,14 @@ function sampleRecap(headMsgs, tailMsgs, currentMessage, { headKeep = 5, tailKee
 module.exports = {
   PINNED_DECISIONS_MAX_CHARS,
   RECAP_LINE_MAX_CHARS,
+  WORKSPACE_GLOSSARY_TITLE,
   decisionLogTitle,
+  glossaryTitle,
   hashDecisions,
   decisionFingerprint,
+  pinnedFingerprint,
   pickDecisionEntry,
+  pickEntryByTitle,
   renderPinnedDecisions,
   isRecapEligible,
   formatRecapLine,