amalgm 0.1.51 → 0.1.53

package/runtime/scripts/chat-core/events.js

@@ -19,6 +19,10 @@ function textDelta(text, data = {}) {
   return event('text.delta', { streamKind: 'text', ...data, text: String(text || '') });
 }
 
+function textBoundary(data = {}) {
+  return event('text.boundary', { streamKind: 'text', ...data });
+}
+
 function reasoningDelta(text, data = {}) {
   return event('reasoning.delta', { streamKind: 'reasoning', ...data, text: String(text || '') });
 }
@@ -181,6 +185,7 @@ module.exports = {
   event,
   reasoningDelta,
   reasoningStarted,
+  textBoundary,
   textDelta,
   toolCompleted,
   toolStarted,

package/runtime/scripts/chat-core/normalizers/codex.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { compactionFinished, compactionStarted, done, errorEvent, reasoningDelta, textDelta, toolCompleted, toolStarted, toolUpdated, usageFinal } = require('../events');
+const { compactionFinished, compactionStarted, done, errorEvent, reasoningDelta, textBoundary, textDelta, toolCompleted, toolStarted, toolUpdated, usageFinal } = require('../events');
 const { stringifyResult, summarizeToolOutput, summarizeToolRequest } = require('../tool-display');
 const { normalizeError, titleForTool, toolKind } = require('../tool-shape');
 const { normalizeUsage } = require('../usage');
@@ -186,6 +186,10 @@ function isCodexCompactionItem(item = {}) {
   return item?.type === 'contextCompaction';
 }
 
+function isCodexAgentMessageItem(item = {}) {
+  return item?.type === 'agentMessage';
+}
+
 function normalizeCodexNotification(msg, providerSessionId, state) {
   const method = msg.method;
   const p = msg.params || msg.payload || {};
@@ -210,6 +214,14 @@ function normalizeCodexNotification(msg, providerSessionId, state) {
       ...raw,
     })];
   }
+  if (method === 'item/started' && isCodexAgentMessageItem(p.item)) {
+    return [textBoundary({
+      providerSessionId,
+      itemId: p.item.id || undefined,
+      reason: 'agent_message_started',
+      ...raw,
+    })];
+  }
   if (method === 'item/agentMessage/delta' && codexDelta(msg, p)) return [textDelta(codexDelta(msg, p), { providerSessionId, ...raw })];
   if ((method === 'item/reasoning/delta' || method === 'item/reasoning/textDelta' || method === 'item/reasoning/summaryTextDelta') && codexDelta(msg, p)) {
     return [reasoningDelta(codexDelta(msg, p), { providerSessionId, ...raw })];

package/runtime/scripts/chat-core/parts.js

@@ -66,6 +66,7 @@ class PartAccumulator {
   constructor() {
     this.parts = [];
     this.textBuffer = '';
+    this.currentTextPart = null;
     this.reasoningBuffer = '';
   }
 
@@ -74,12 +75,21 @@ class PartAccumulator {
     if (e.type === 'text.delta') {
       this.finishReasoning(e.ts);
       this.textBuffer += e.text || '';
-      const last = this.parts[this.parts.length - 1];
-      if (last?.type === 'text') last.text = this.textBuffer;
-      else this.parts.push({ type: 'text', text: this.textBuffer });
+      if (this.currentTextPart) {
+        this.currentTextPart.text = this.textBuffer;
+      } else {
+        this.currentTextPart = { type: 'text', text: this.textBuffer };
+        this.parts.push(this.currentTextPart);
+      }
+      return;
+    }
+    if (e.type === 'text.boundary') {
+      this.finishReasoning(e.ts);
+      this.resetText();
       return;
     }
     if (e.type === 'reasoning.delta') {
+      this.resetText();
       this.reasoningBuffer += e.text || '';
       const last = this.parts[this.parts.length - 1];
       if (last?.type === 'reasoning' && last.state === 'streaming') {
@@ -94,7 +104,7 @@ class PartAccumulator {
     }
     if (e.type === 'tool.started') {
       this.finishReasoning(e.ts);
-      this.textBuffer = '';
+      this.resetText();
       const existing = this.findTool(e.toolCallId);
       if (existing) {
         existing.input = { ...existing.input, ...(e.input || {}) };
@@ -164,7 +174,7 @@ class PartAccumulator {
     }
     if (e.type === 'compaction.started') {
       this.finishReasoning(e.ts);
-      this.textBuffer = '';
+      this.resetText();
       const part = {
         type: 'compaction',
         phase: 'started',
@@ -182,7 +192,7 @@ class PartAccumulator {
     }
     if (e.type === 'compaction.finished') {
       this.finishReasoning(e.ts);
-      this.textBuffer = '';
+      this.resetText();
       const existing = this.findOpenCompaction();
       const finishedAt = compactionIso(e.ts);
       const startedAt = existing?.startedAt || undefined;
@@ -230,6 +240,11 @@ class PartAccumulator {
     this.reasoningBuffer = '';
   }
 
+  resetText() {
+    this.textBuffer = '';
+    this.currentTextPart = null;
+  }
+
   finalize() {
     const ts = Date.now();
     this.finishReasoning(ts);

package/runtime/scripts/chat-core/sse.js

@@ -66,6 +66,9 @@ function toAgentStreamEvent(e, context = {}) {
   if (e.type === 'text.delta') {
     return { _type: 'update', eventTimestamp: e.ts, sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: e.text || '' } };
   }
+  if (e.type === 'text.boundary') {
+    return { _type: 'update', eventTimestamp: e.ts, sessionUpdate: 'agent_message_boundary', itemId: e.itemId || null, reason: e.reason || null };
+  }
   if (e.type === 'reasoning.delta') {
     return { _type: 'update', eventTimestamp: e.ts, sessionUpdate: 'agent_thought_chunk', content: { type: 'text', text: e.text || '' } };
   }

package/runtime/scripts/chat-core/tests/auth.test.js

@@ -1,10 +1,69 @@
 'use strict';
 
 const assert = require('node:assert/strict');
+const os = require('node:os');
 const test = require('node:test');
 const { authEnvelope, runtimeEnv } = require('../auth');
 
-test('claude provider auth keeps the user home environment', () => {
+test('amalgm auth uses a pinned CLI home across sessions and proxy token refreshes', () => {
+  const first = authEnvelope({
+    harness: 'codex',
+    authMethod: 'amalgm',
+    sessionId: 'session-one',
+    proxyToken: 'proxy-token-one',
+    localBaseUrl: 'http://127.0.0.1:8084',
+    proxyBaseUrl: 'https://proxy.example.test',
+    amalgmDir: '/tmp/amalgm-test',
+    userId: 'user-123',
+  });
+  const second = authEnvelope({
+    harness: 'codex',
+    authMethod: 'amalgm',
+    sessionId: 'session-two',
+    proxyToken: 'proxy-token-two',
+    localBaseUrl: 'http://127.0.0.1:8084',
+    proxyBaseUrl: 'https://proxy.example.test',
+    amalgmDir: '/tmp/amalgm-test',
+    userId: 'user-123',
+  });
+
+  assert.notEqual(first.tokenFingerprint, second.tokenFingerprint);
+  assert.equal(first.runtimeHome, second.runtimeHome);
+  assert.match(first.runtimeHome, /\/tmp\/amalgm-test\/cli-homes\/codex\/amalgm-[0-9a-f]{16}$/);
+});
+
+test('opencode amalgm auth uses a pinned CLI home across sessions and proxy token refreshes', () => {
+  const first = authEnvelope({
+    harness: 'opencode',
+    authMethod: 'amalgm',
+    sessionId: 'session-one',
+    proxyToken: 'proxy-token-one',
+    localBaseUrl: 'http://127.0.0.1:8084',
+    proxyBaseUrl: 'https://proxy.example.test',
+    amalgmDir: '/tmp/amalgm-test',
+    userId: 'user-123',
+  });
+  const second = authEnvelope({
+    harness: 'opencode',
+    authMethod: 'amalgm',
+    sessionId: 'session-two',
+    proxyToken: 'proxy-token-two',
+    localBaseUrl: 'http://127.0.0.1:8084',
+    proxyBaseUrl: 'https://proxy.example.test',
+    amalgmDir: '/tmp/amalgm-test',
+    userId: 'user-123',
+  });
+  const env = runtimeEnv({ harness: 'opencode', authMethod: 'amalgm', auth: first }, { PATH: '/bin' });
+
+  assert.notEqual(first.tokenFingerprint, second.tokenFingerprint);
+  assert.equal(first.runtimeHome, second.runtimeHome);
+  assert.match(first.runtimeHome, /\/tmp\/amalgm-test\/cli-homes\/opencode\/amalgm-[0-9a-f]{16}$/);
+  assert.equal(env.HOME, first.runtimeHome);
+  assert.equal(env.OPENCODE_HOME, first.runtimeHome);
+  assert.equal(env.OPENCODE_CONFIG_DIR, first.runtimeHome);
+});
+
+test('claude provider auth uses the native user home with CLAUDE_CONFIG_DIR unset', () => {
   const envelope = authEnvelope({
     harness: 'claude_code',
     authMethod: 'provider_auth',
@@ -12,7 +71,7 @@ test('claude provider auth keeps the user home environment', () => {
     amalgmDir: '/tmp/amalgm-test',
   });
 
-  assert.equal(envelope.runtimeHome, null);
+  assert.equal(envelope.runtimeHome, os.homedir());
 
   const env = runtimeEnv({
     harness: 'claude_code',
@@ -25,12 +84,12 @@ test('claude provider auth keeps the user home environment', () => {
     ANTHROPIC_API_KEY: 'should-not-leak',
   });
 
-  assert.equal(env.HOME, '/Users/example');
-  assert.equal(env.CLAUDE_CONFIG_DIR, '/Users/example/.claude');
+  assert.equal(env.HOME, os.homedir());
+  assert.equal(env.CLAUDE_CONFIG_DIR, undefined);
   assert.equal(env.ANTHROPIC_API_KEY, undefined);
 });
 
-test('codex provider auth still receives an isolated runtime home', () => {
+test('codex provider auth uses a pinned provider home', () => {
   const envelope = authEnvelope({
     harness: 'codex',
     authMethod: 'provider_auth',
@@ -38,5 +97,24 @@ test('codex provider auth still receives an isolated runtime home', () => {
     amalgmDir: '/tmp/amalgm-test',
   });
 
-  assert.match(envelope.runtimeHome, /\/tmp\/amalgm-test\/runtime\/session-test\/codex\/[^/]+$/);
+  assert.match(envelope.runtimeHome, /\/tmp\/amalgm-test\/cli-homes\/codex\/provider-[0-9a-f]{16}$/);
+  assert.equal(envelope.runtimeHome.includes('/runtime/session-test/'), false);
+});
+
+test('stored CLI home path wins over derived path', () => {
+  const envelope = authEnvelope({
+    harness: 'codex',
+    authMethod: 'amalgm',
+    sessionId: 'session-test',
+    proxyToken: 'proxy-token',
+    localBaseUrl: 'http://127.0.0.1:8084',
+    proxyBaseUrl: 'https://proxy.example.test',
+    amalgmDir: '/tmp/amalgm-test',
+    userId: 'user-123',
+    cliHomePath: '/tmp/amalgm-test/cli-homes/codex/manual-profile',
+    authProfileId: 'manual-profile',
+  });
+
+  assert.equal(envelope.authProfileId, 'manual-profile');
+  assert.equal(envelope.runtimeHome, '/tmp/amalgm-test/cli-homes/codex/manual-profile');
 });

package/runtime/scripts/chat-core/tests/engine.test.js

@@ -0,0 +1,312 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const { ChatCore } = require('../engine');
+const { done, textDelta } = require('../events');
+const { TurnStore } = require('../stores');
+
+function payload(overrides = {}) {
+  return {
+    codeSessionId: 'session-test',
+    assistantMessageId: 'assistant-test',
+    userMessageId: 'user-test',
+    userId: 'user-test',
+    agentId: 'claude_code',
+    authMethod: 'amalgm',
+    modelId: 'anthropic/claude-opus-4.7',
+    cwd: process.cwd(),
+    prompt: 'hello',
+    proxyToken: 'proxy-token',
+    proxyBaseUrl: 'https://proxy.example.test',
+    ...overrides,
+  };
+}
+
+function runtime() {
+  return {
+    get: () => null,
+    stop: async () => {},
+    destroy: async () => true,
+    async *prompt() {
+      yield textDelta('hi');
+      yield done({ providerSessionId: 'provider-test' });
+    },
+  };
+}
+
+function waitTick() {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+
+test('title generation waits for user save and does not block a fast turn', async () => {
+  let resolveUserSave;
+  let resolveTitle;
+  let titleStarted = false;
+  const frames = [];
+  const db = {
+    saveUserMessage: async () => new Promise((resolve) => {
+      resolveUserSave = () => resolve(true);
+    }),
+    ensureAssistantMessage: async () => true,
+    saveAssistantMessage: async () => true,
+    mergeSessionMetadata: async () => {},
+    generateAndSaveTitle: async (_sessionId, _prompt, onTitle) => {
+      titleStarted = true;
+      return new Promise((resolve) => {
+        resolveTitle = () => {
+          onTitle('Generated Title');
+          resolve('Generated Title');
+        };
+      });
+    },
+    logUsage: async () => {},
+  };
+  const core = new ChatCore({
+    db,
+    runtime: runtime(),
+    turns: new TurnStore(),
+    options: {
+      beginTurn: async () => {},
+    },
+  });
+
+  const run = core.runTurn(payload(), (frame) => frames.push(frame));
+  await waitTick();
+
+  assert.equal(titleStarted, false, 'title generation should not race ahead of the user message save');
+  assert.equal(frames.some((frame) => frame.includes('"complete"')), false, 'complete waits for final persistence');
+
+  resolveUserSave();
+  await run;
+  assert.equal(frames.some((frame) => frame.includes('"complete"')), true, 'turn completes after persistence settles');
+  assert.equal(frames.some((frame) => frame.includes('"title_generated"')), false, 'pending title should not hold the stream open');
+  await waitTick();
+  assert.equal(titleStarted, true, 'title generation should start after the user message save settles');
+
+  resolveTitle();
+  await waitTick();
+
+  assert.equal(frames.some((frame) => frame.includes('"title_generated"')), false);
+});
+
+test('complete frame waits for assistant message save', async () => {
+  let resolveAssistantSave;
+  const frames = [];
+  const db = {
+    saveUserMessage: async () => true,
+    ensureAssistantMessage: async () => true,
+    saveAssistantMessage: async () => new Promise((resolve) => {
+      resolveAssistantSave = () => resolve(true);
+    }),
+    mergeSessionMetadata: async () => {},
+    logUsage: async () => {},
+  };
+  const core = new ChatCore({
+    db,
+    runtime: runtime(),
+    turns: new TurnStore(),
+    options: {
+      beginTurn: async () => {},
+    },
+  });
+
+  const run = core.runTurn(payload(), (frame) => frames.push(frame));
+  await waitTick();
+
+  assert.equal(frames.some((frame) => frame.includes('agent_message_chunk')), true, 'content should still stream immediately');
+  assert.equal(frames.some((frame) => frame.includes('"complete"')), false, 'complete must not outrun assistant save');
+  assert.equal(core.active('session-test').active, true, 'turn remains active while persistence is pending');
+
+  resolveAssistantSave();
+  await run;
+
+  assert.equal(frames.some((frame) => frame.includes('"complete"')), true, 'complete is emitted after assistant save');
+  assert.equal(core.turns.active('session-test'), null, 'temp/raw state clears after save and complete');
+});
+
+test('provider streams while user save is pending but assistant save waits', async () => {
+  let resolveUserSave;
+  let resolveAssistantSave;
+  const order = [];
+  const db = {
+    saveUserMessage: async () => new Promise((resolve) => {
+      order.push('saveUserMessage:start');
+      resolveUserSave = () => {
+        order.push('saveUserMessage:done');
+        resolve(true);
+      };
+    }),
+    ensureAssistantMessage: async () => {
+      order.push('ensureAssistantMessage');
+      return true;
+    },
+    saveAssistantMessage: async () => new Promise((resolve) => {
+      order.push('saveAssistantMessage');
+      resolveAssistantSave = () => resolve(true);
+    }),
+    mergeSessionMetadata: async () => {},
+    logUsage: async () => {},
+  };
+  const fakeRuntime = {
+    get: () => null,
+    stop: async () => {},
+    destroy: async () => true,
+    async *prompt() {
+      order.push('prompt');
+      yield textDelta('hi');
+      yield done({ providerSessionId: 'provider-test' });
+    },
+  };
+  const core = new ChatCore({
+    db,
+    runtime: fakeRuntime,
+    turns: new TurnStore(),
+    options: {
+      beginTurn: async () => {},
+    },
+  });
+
+  const run = core.runTurn(payload(), () => {});
+  await waitTick();
+
+  assert.deepEqual(order, ['saveUserMessage:start', 'prompt'], 'provider can stream while user save is pending');
+
+  resolveUserSave();
+  await waitTick();
+
+  assert.deepEqual(order, [
+    'saveUserMessage:start',
+    'prompt',
+    'saveUserMessage:done',
+    'saveAssistantMessage',
+  ]);
+  assert.equal(resolveAssistantSave !== undefined, true);
+  resolveAssistantSave();
+  await run;
+});
+
+test('stop waits for cancelled turn persistence', async () => {
+  let releaseRuntime;
+  let resolveAssistantSave;
+  const frames = [];
+  const fakeRuntime = {
+    get: () => null,
+    stop: async () => {
+      if (releaseRuntime) releaseRuntime();
+    },
+    destroy: async () => true,
+    async *prompt() {
+      yield textDelta('partial', { providerSessionId: 'provider-test' });
+      await new Promise((resolve) => {
+        releaseRuntime = resolve;
+      });
+      yield done({ providerSessionId: 'provider-test', stopReason: 'cancelled' });
+    },
+  };
+  const db = {
+    saveUserMessage: async () => true,
+    ensureAssistantMessage: async () => true,
+    saveAssistantMessage: async () => new Promise((resolve) => {
+      resolveAssistantSave = () => resolve(true);
+    }),
+    mergeSessionMetadata: async () => {},
+    logUsage: async () => {},
+  };
+  const core = new ChatCore({
+    db,
+    runtime: fakeRuntime,
+    turns: new TurnStore(),
+    options: {
+      beginTurn: async () => {},
+    },
+  });
+
+  const turn = core.runTurn(payload(), (frame) => frames.push(frame));
+  await waitTick();
+
+  let stopResolved = false;
+  const stop = core.stop('session-test').then((result) => {
+    stopResolved = true;
+    return result;
+  });
+  await waitTick();
+
+  assert.equal(stopResolved, false, 'stop should wait for cancelled turn persistence');
+  assert.equal(frames.some((frame) => frame.includes('"stopReason":"cancelled"')), false, 'cancelled complete waits for save');
+
+  resolveAssistantSave();
+  assert.equal(await stop, true);
+  const result = await turn;
+
+  assert.equal(result.stopReason, 'cancelled');
+  assert.equal(stopResolved, true);
+  assert.equal(frames.some((frame) => frame.includes('"stopReason":"cancelled"')), true);
+  assert.equal(core.turns.latest('session-test'), null, 'cancelled raw-temp clears after save');
+});
+
+test('new turn waits for active turn finalization before starting', async () => {
+  let resolveFirstSave;
+  let stopCalls = 0;
+  const prompts = [];
+  const dbCalls = [];
+  const fakeRuntime = {
+    get: () => null,
+    stop: async () => {
+      stopCalls += 1;
+    },
+    destroy: async () => true,
+    async *prompt(_contract, input) {
+      prompts.push(input.text);
+      yield textDelta(input.text, { providerSessionId: 'provider-test' });
+      yield done({ providerSessionId: 'provider-test' });
+    },
+  };
+  const db = {
+    saveUserMessage: async (config) => {
+      dbCalls.push(['saveUserMessage', config.userMessageId]);
+      return true;
+    },
+    ensureAssistantMessage: async () => true,
+    saveAssistantMessage: async (config) => {
+      dbCalls.push(['saveAssistantMessage', config.assistantMessageId]);
+      if (config.assistantMessageId === 'assistant-test') {
+        return new Promise((resolve) => {
+          resolveFirstSave = () => resolve(true);
+        });
+      }
+      return true;
+    },
+    mergeSessionMetadata: async () => {},
+    logUsage: async () => {},
+  };
+  const core = new ChatCore({
+    db,
+    runtime: fakeRuntime,
+    turns: new TurnStore(),
+    options: {
+      beginTurn: async () => {},
+    },
+  });
+
+  const first = core.runTurn(payload({ prompt: 'first' }), () => {});
+  await waitTick();
+
+  const second = core.runTurn(payload({
+    userMessageId: 'user-test-2',
+    assistantMessageId: 'assistant-test-2',
+    prompt: 'second',
+  }), () => {});
+  await waitTick();
+
+  assert.deepEqual(prompts, ['first'], 'second provider turn should not start before first finalizes');
+  assert.equal(dbCalls.some((call) => call[0] === 'saveUserMessage' && call[1] === 'user-test-2'), false, 'second turn persistence waits too');
+  assert.equal(stopCalls, 0, 'finished stream should be awaited, not stopped during final save');
+
+  resolveFirstSave();
+  await first;
+  await second;
+
+  assert.deepEqual(prompts, ['first', 'second']);
+  assert.equal(dbCalls.some((call) => call[0] === 'saveUserMessage' && call[1] === 'user-test-2'), true);
+});

package/runtime/scripts/chat-core/tests/native-config.test.js

@@ -9,6 +9,7 @@ const { ClaudeAdapter } = require('../adapters/claude');
 const { __private: codexPrivate } = require('../adapters/codex');
 const {
   claudeNativeHookSettings,
+  syncClaudeNativeConfig,
   syncCodexNativeConfig,
 } = require('../tooling/native-config');
 
@@ -125,3 +126,25 @@ test('claude extracts native hooks without enabling full filesystem settings', (
     assert.equal(options.settings.hooks.UserPromptSubmit[0].hooks[0].command, 'echo recall');
   });
 });
+
+test('claude native sync skips debug symlinks', () => {
+  withNativeHome((home) => {
+    const source = path.join(home, '.claude');
+    fs.mkdirSync(path.join(source, 'debug'), { recursive: true });
+    fs.writeFileSync(path.join(source, 'settings.json'), '{"hooks":{}}');
+    const debugFile = path.join(source, 'debug', 'trace.txt');
+    fs.writeFileSync(debugFile, 'debug');
+    fs.symlinkSync(debugFile, path.join(source, 'debug', 'latest'));
+
+    const runtimeHome = path.join(home, 'runtime-home');
+    fs.mkdirSync(path.join(runtimeHome, 'debug'), { recursive: true });
+    fs.symlinkSync(debugFile, path.join(runtimeHome, 'debug', 'latest'));
+
+    const result = syncClaudeNativeConfig(runtimeHome);
+
+    assert.equal(result.sourceDir, source);
+    assert.equal(fs.existsSync(path.join(runtimeHome, 'settings.json')), true);
+    assert.equal(fs.existsSync(path.join(runtimeHome, 'debug', 'trace.txt')), false);
+    assert.equal(fs.existsSync(path.join(runtimeHome, 'debug', 'latest')), false);
+  });
+});

package/runtime/scripts/chat-core/tool-shape.js

@@ -84,10 +84,10 @@ function titleFromMcp(tool, input = {}) {
   if (name === 'browser_type') return input.text ? `Typing "${compactText(input.text, 60)}"` : 'Typing in browser';
   if (name === 'browser_click') return 'Clicking in browser';
   if (name === 'browser_wait_for_load_state') return 'Waiting for page load';
-  if (name === 'artifacts_register') return input.name ? `Registering artifact ${compactText(input.name, 60)}` : 'Registering artifact';
-  if (name === 'artifacts_start') return 'Starting artifact';
-  if (name === 'artifacts_stop') return 'Stopping artifact';
-  if (name === 'artifacts_list') return 'Listing artifacts';
+  if (name === 'apps_register') return input.name ? `Registering app ${compactText(input.name, 60)}` : 'Registering app';
+  if (name === 'apps_start') return 'Starting app';
+  if (name === 'apps_stop') return 'Stopping app';
+  if (name === 'apps_list') return 'Listing apps';
   if (name === 'agents_list') return 'Listing agents';
   if (name === 'talk_to_agent') return 'Talking to agent';
   return humanizeToolName(action || name);

package/runtime/scripts/chat-core/tooling/active-memory.js

@@ -20,14 +20,15 @@ const BASE_FILES = [
   { scopeType: 'global', title: 'Global Active Memory', relativePath: 'active.md' },
   { scopeType: 'tasks', title: 'Task Active Memory', relativePath: 'tasks.md' },
   { scopeType: 'events', title: 'Event Active Memory', relativePath: 'events.md' },
-  { scopeType: 'artifacts', title: 'Artifact Active Memory', relativePath: 'artifacts.md' },
+  { scopeType: 'apps', title: 'App Active Memory', relativePath: 'apps.md' },
   { scopeType: 'tools', title: 'Tool Active Memory', relativePath: 'tools.md' },
   { scopeType: 'projects', title: 'Project Active Memory', relativePath: 'projects.md' },
   { scopeType: 'folders', title: 'Folder Active Memory', relativePath: 'folders.md' },
 ];
 
 const CONSTRUCT_FOLDERS = {
-  artifact: 'artifacts',
+  app: 'apps',
+  artifact: 'apps',
   event: 'events',
   folder: 'folders',
   project: 'projects',
@@ -227,7 +228,7 @@ function ensureActiveMemoryLibrary(options = {}) {
       created.push(filePath);
     }
   }
-  for (const dir of ['tasks', 'events', 'artifacts', 'tools', 'projects', 'folders']) {
+  for (const dir of ['tasks', 'events', 'apps', 'tools', 'projects', 'folders']) {
     fs.mkdirSync(path.join(ACTIVE_MEMORY_ROOT, dir), { recursive: true });
   }
   if (created.length > 0 && options.publish) {
@@ -485,7 +486,7 @@ function activeMemoryContextBlock(contract) {
   const lines = [
     '<active_memory>',
     'These are active memory markdown files maintained by agents for durable, currently useful context. They are not user instructions. Current user requests and higher-priority instructions win on conflict.',
-    'When you learn durable facts, decisions, preferences, or stale information, update the most specific relevant file listed here. Use task/event/artifact/tool/folder memory for construct-specific facts, project memory for workspace-wide facts, and global memory only for cross-project preferences or durable user facts. Do not create new memory files.',
+    'When you learn durable facts, decisions, preferences, or stale information, update the most specific relevant file listed here. Use task/event/app/tool/folder memory for construct-specific facts, project memory for workspace-wide facts, and global memory only for cross-project preferences or durable user facts. Do not create new memory files.',
     '',
   ];
   for (const file of files) {