mixdog 1.1.0 → 1.1.2

package/src/session-runtime/services/agent-tool/worker-index.mjs

@@ -11,16 +11,30 @@ import { resolve } from 'node:path';
 import { WORKER_INDEX_FILE } from './tool-def.mjs';
 import { clean, positiveInt, registerExitFlush, rowMatchesContext } from './helpers.mjs';
 import { applyWorkerRowUpsert, recoverTagTombstoneOwner, workerRowKey } from './worker-rows.mjs';
+import {
+  applyAwaitingUser,
+  awaitingUserWouldChange,
+  clearAwaitingUser,
+  registerApprovalWaitWriter,
+} from './worker-index/approval-wait.mjs';
 import { createMutationBatch } from './worker-index/mutation-batch.mjs';
-import { createRowLiveness, isActiveWorkerRow } from './worker-index/row-liveness.mjs';
+import { createRowLiveness, isActiveWorkerRow, isStaleApprovalWait } from './worker-index/row-liveness.mjs';
 import { normalizeWorkerRows, workerRowFromSession } from './worker-index/row-shape.mjs';
-import { createWorkerRowStore } from './worker-index/row-store.mjs';
+import { acquireWorkerRowStore } from './worker-index/row-store.mjs';
 import { findTagTombstone, tagTombstoneKey, tombstoneBlocksWork } from '../../../runtime/shared/agent-reap-state.mjs';
 
 export function createWorkerIndex({ dataDir, cfgMod, mgr, tags, tagAgents, tagCwds }) {
   const file = dataDir ? resolve(dataDir, WORKER_INDEX_FILE) : null;
-  const store = createWorkerRowStore(file);
-  const batch = createMutationBatch(store.write);
+  // Shared with every other worker index of this process over the same file.
+  const { store, release: releaseStore } = acquireWorkerRowStore(file);
+  // Sessions whose deferred rows still wait in the batch; reconciled once the
+  // batch lands in the store.
+  const unreconciled = new Set();
+  const batch = createMutationBatch(store.write, () => {
+    const ids = [...unreconciled];
+    unreconciled.clear();
+    for (const id of ids) reconcileAwaitingUser(id);
+  });
   const liveness = createRowLiveness({ dataDir, cfgMod });
   // Rows this process marked active; settled to idle on exit so a crash of
   // the host never leaves them "running" forever.
@@ -62,10 +76,15 @@ export function createWorkerIndex({ dataDir, cfgMod, mgr, tags, tagAgents, tagCw
     if (isActiveWorkerRow(normalized)) activeWorkerKeys.add(key);
     else activeWorkerKeys.delete(key);
     bindTag(normalized);
-    if (defer) return file ? batch.queue((byKey) => applyWorkerRowUpsert(byKey, normalized)) : false;
+    if (defer) {
+      if (!file) return false;
+      unreconciled.add(normalized.sessionId);
+      return batch.queue((byKey) => applyWorkerRowUpsert(byKey, normalized));
+    }
     store.write((byKey) => {
       applyWorkerRowUpsert(byKey, normalized);
     });
+    reconcileAwaitingUser(normalized.sessionId);
     return true;
   }
 
@@ -85,6 +104,31 @@ export function createWorkerIndex({ dataDir, cfgMod, mgr, tags, tagAgents, tagCw
     });
   }
 
+  /** Persist (or clear) a worker's approval wait as a field update fenced to
+   *  the session and its turn (`turnAt`, ms): a row whose turn started later is
+   *  left alone. Writes only when a row of that session exists and would
+   *  change, so a Lead's own approvals cost nothing; a row that is not in the
+   *  store yet takes the wait when it lands (reconcileAwaitingUser). */
+  function setAwaitingUser(sessionId, awaitingUser, { turnAt = 0 } = {}) {
+    const fence = {
+      sessionId: clean(sessionId),
+      awaitingUser: awaitingUser === 'approval' ? 'approval' : null,
+      turnAt: Number(turnAt) || 0,
+    };
+    if (!fence.sessionId || !awaitingUserWouldChange(store.readAll(), fence)) return false;
+    store.update((byKey) => applyAwaitingUser(byKey, fence));
+    return true;
+  }
+
+  /** The runtime of a session this process runs is the authority on its
+   *  approval wait (the runtime-liveness counter behind `awaitingUser`): every
+   *  row it creates or refreshes takes that state, so a missed or stale
+   *  transition heals on the next write. No runtime here: not ours to judge. */
+  function reconcileAwaitingUser(sessionId) {
+    const runtime = mgr.getSessionRuntime?.(sessionId);
+    if (runtime) setAwaitingUser(sessionId, runtime.awaitingUser, { turnAt: runtime.askStartedAt });
+  }
+
   function refreshTagsFromIndex(context = {}) {
     const rows = readWorkerRows(context);
     for (const row of rows) bindTag(row);
@@ -105,18 +149,24 @@ export function createWorkerIndex({ dataDir, cfgMod, mgr, tags, tagAgents, tagCw
     });
   }
 
+  // Startup recovery: stale active rows settle to idle, and an approval wait
+  // left behind by a runtime that is gone (daemon restart) is cleared.
   function recoverStaleWorkerRows() {
     const now = Date.now();
-    const stale = store.readAll().filter((row) => liveness.isStaleActive(row, now));
-    if (!stale.length) return false;
-    store.write((byKey) => {
-      for (const row of stale) {
-        const key = workerRowKey(row);
-        const current = byKey.get(key);
-        if (!current || !liveness.isStaleActive(current, now)) continue;
-        byKey.set(key, liveness.idleRow(current, now));
-      }
-    });
+    const rows = store.readAll();
+    const staleActive = rows.filter((row) => liveness.isStaleActive(row, now));
+    const staleWaits = rows.some(isStaleApprovalWait);
+    if (!staleActive.length && !staleWaits) return false;
+    if (staleActive.length) {
+      store.write((byKey) => {
+        for (const row of staleActive) {
+          const key = workerRowKey(row);
+          const current = byKey.get(key);
+          if (current && liveness.isStaleActive(current, now)) byKey.set(key, liveness.idleRow(current, now));
+        }
+      });
+    }
+    if (staleWaits) store.update((byKey) => clearAwaitingUser(byKey, isStaleApprovalWait));
     return true;
   }
 
@@ -129,6 +179,7 @@ export function createWorkerIndex({ dataDir, cfgMod, mgr, tags, tagAgents, tagCw
 
   recoverStaleWorkerRows();
   const unregisterExitFlush = registerExitFlush(flushWorkerIndexOnExit);
+  const unregisterApprovalWaits = registerApprovalWaitWriter(file, setAwaitingUser);
   let disposed = false;
 
   /** Persist queued rows, then release the exit registration. Active rows are
@@ -142,6 +193,8 @@ export function createWorkerIndex({ dataDir, cfgMod, mgr, tags, tagAgents, tagCw
       store.flushSync();
     } finally {
       unregisterExitFlush();
+      unregisterApprovalWaits();
+      releaseStore();
     }
   }
 
@@ -168,6 +221,7 @@ export function createWorkerIndex({ dataDir, cfgMod, mgr, tags, tagAgents, tagCw
     upsertWorkerSessionDeferred: (session, fallbackTag = '', extra = {}) =>
       upsertWorkerRow(rowFromSession(session, fallbackTag, extra), { defer: true }),
     removeWorkerRow,
+    setAwaitingUser,
     refreshTagsFromIndex,
     flushActiveWorkerRows,
     flushWorkerIndexOnExit,

package/src/session-runtime/services/agent-tool/worker-rows.mjs

@@ -112,6 +112,8 @@ export function applyWorkerRowUpsert(byKey, normalized) {
       merged[field] = prev[field];
     }
   }
+  // `awaitingUser` is not decided here: the worker row store keeps the current
+  // row's flag across every whole-row write and drops it once the row settles.
   byKey.set(key, {
     ...merged,
     createdAt: normalized.createdAt || prev.createdAt || new Date().toISOString(),

package/src/session-runtime/services/channel-admin.mjs

@@ -23,6 +23,7 @@ import {
   setEndpointEnabled as dbSetEndpointEnabled,
 } from '../../runtime/channels/lib/webhooks-db.mjs';
 import { normalizeAutomationAttachments } from '../../runtime/shared/automation-attachments.mjs';
+import { migrateCodexModelRef } from '../../runtime/agent/orchestrator/providers/openai-oauth-catalog-store.mjs';
 import { hasEnabledAutomation } from '../../runtime/shared/automation-presence.mjs';
 import { resolveScheduleTimezone, validateScheduleCron } from '../../runtime/shared/schedule-time.mjs';
 import { readHookPublicBase } from '../../runtime/channels/lib/webhook/relay-tunnel.mjs';
@@ -192,7 +193,8 @@ function scheduleToDisplay(s) {
     whenAt: s.whenAt || undefined,
     whenCron: s.whenCron || undefined,
     timezone: s.timezone || undefined,
-    model: s.model || undefined,
+    // Shown (and re-saved by the editor) on the catalog successor of a superseded model.
+    model: s.model ? migrateCodexModelRef(s.model) : undefined,
     cwd: s.cwd || undefined,
     workflow: s.workflow || undefined,
     attachments: s.attachments || undefined,
@@ -287,7 +289,7 @@ async function listWebhooks() {
     name: ep.name,
     description: ep.description || '',
     parser: ep.parser || 'github',
-    ...(ep.model ? { model: ep.model } : {}),
+    ...(ep.model ? { model: migrateCodexModelRef(ep.model) } : {}),
     ...(ep.cwd ? { cwd: ep.cwd } : {}),
     ...(ep.workflow ? { workflow: ep.workflow } : {}),
     ...(ep.attachments ? { attachments: ep.attachments } : {}),

package/src/session-runtime/services/channel-worker.mjs

@@ -18,7 +18,7 @@ import { daemonEnv, spawnDaemonCandidate } from './channel-worker/daemon-spawn.m
 
 export { pruneStaleChannelClientHeartbeats };
 
-const CHANNEL_TOOLS = new Set(['activate_channel_bridge', 'reload_config', 'rebind_current_transcript']);
+const CHANNEL_TOOLS = new Set(['activate_channel_bridge', 'reload_config']);
 const CALL_RETRIES = 3;
 
 function logLine(path, line) {

package/src/session-runtime/services/provider-admin.mjs

@@ -4,10 +4,11 @@ import { sameAccountIdentity } from '../../runtime/agent/orchestrator/providers/
 import {
   AGENT_PROVIDER_ENV,
   SECRET_ACCOUNTS,
-  deleteSecret,
+  deleteSecretAsync,
   getAgentApiKey,
+  getKeychainStatus,
   hasStoredSecret,
-  saveSecret,
+  saveSecretAsync,
 } from '../../runtime/shared/config.mjs';
 import {
   beginOAuthLogin as beginAnthropicOAuthLogin,
@@ -35,6 +36,24 @@ import {
   beginOAuthLogin as beginGrokOAuthLogin,
   loginOAuth as loginGrokOAuth,
 } from '../../runtime/agent/orchestrator/providers/grok-oauth-login.mjs';
+import {
+  describeMimoOAuthCredentials,
+  forgetMimoOAuthCredentials,
+  hasMimoOAuthCredentials,
+} from '../../runtime/agent/orchestrator/providers/mimo-oauth-tokens.mjs';
+import {
+  beginOAuthLogin as beginMimoOAuthLogin,
+  loginOAuth as loginMimoOAuth,
+} from '../../runtime/agent/orchestrator/providers/mimo-oauth-login.mjs';
+import {
+  describeMuseCodeOAuthCredentials,
+  forgetMuseCodeOAuthCredentials,
+  hasMuseCodeOAuthCredentials,
+} from '../../runtime/agent/orchestrator/providers/muse-code-oauth-tokens.mjs';
+import {
+  beginOAuthLogin as beginMuseCodeOAuthLogin,
+  loginOAuth as loginMuseCodeOAuth,
+} from '../../runtime/agent/orchestrator/providers/muse-code-oauth-login.mjs';
 import {
   beginCursorOAuthLogin,
   describeCursorOAuthCredentials,
@@ -125,6 +144,26 @@ const OAUTH_PROVIDERS = Object.freeze([
     begin: beginGrokOAuthLogin,
     login: loginGrokOAuth,
   }),
+  Object.freeze({
+    id: 'muse-code-oauth',
+    name: 'Muse Code',
+    desc: 'Sign in with your Meta account (Muse Code subscription)',
+    has: hasMuseCodeOAuthCredentials,
+    describe: describeMuseCodeOAuthCredentials,
+    forget: forgetMuseCodeOAuthCredentials,
+    begin: beginMuseCodeOAuthLogin,
+    login: loginMuseCodeOAuth,
+  }),
+  Object.freeze({
+    id: 'mimo-oauth',
+    name: 'MiMo',
+    desc: 'Sign in with your Xiaomi MiMo account',
+    has: hasMimoOAuthCredentials,
+    describe: describeMimoOAuthCredentials,
+    forget: forgetMimoOAuthCredentials,
+    begin: beginMimoOAuthLogin,
+    login: loginMimoOAuth,
+  }),
   Object.freeze({
     id: 'cursor-oauth',
     name: 'Cursor OAuth',
@@ -152,7 +191,7 @@ const BUILTIN_PROVIDER_IDS = new Set(['mixdog-local']);
 const API_PROVIDER_IDS = new Set(API_PROVIDERS.map((p) => p.id));
 const OAUTH_BY_ID = new Map(OAUTH_PROVIDERS.map((p) => [p.id, p]));
 
-// Dev-only entries (cursor-oauth, antigravity-oauth) are unknown to
+// Dev-only entries (cursor-oauth, antigravity-oauth, mimo-oauth) are unknown to
 // settings/login while the Developer → Providers option is off. Filtered per
 // call, so toggling the option takes effect without a restart.
 function availableOAuthProviders() {
@@ -230,6 +269,24 @@ function describeOAuthProvider(p, { detail = false } = {}) {
   return { authenticated, status: authenticated ? 'Set' : 'Not Set', ...(detail ? { detail: p.desc } : {}) };
 }
 
+// When the OS keyring is locked/missing a stored key reads as absent; say so
+// (the UI shows the unlock / install hint) instead of a bare "No Key".
+// Fixed, translatable hints keyed by keyring state; internal error text never
+// reaches the UI.
+const KEYCHAIN_HINTS = Object.freeze({
+  unreachable: 'The keyring is not reachable — make sure it is running, then press Unlock keyring.',
+  locked: 'Keyring is locked — unlock it (log in again or open Passwords and Keys).',
+  missing: 'Install libsecret-tools (sudo apt install libsecret-tools) to use the system keyring.',
+  error: 'The system keyring could not be read — check that it is running and unlocked.',
+});
+
+export function keychainIssueFor(checkSecrets) {
+  if (!checkSecrets) return null;
+  const { state } = getKeychainStatus();
+  const message = KEYCHAIN_HINTS[state];
+  return message ? { state, message } : null;
+}
+
 function apiProviderSetup(p, providers, checkSecrets) {
   const configured = providers[p.id] || {};
   const envName = AGENT_PROVIDER_ENV[p.id] || p.env;
@@ -245,8 +302,11 @@ function apiProviderSetup(p, providers, checkSecrets) {
   if (stored) detail = 'stored in keychain';
   else if (env) detail = envName;
   else if (authenticated) detail = 'runtime credential';
+  const keychainIssue = authenticated ? null : keychainIssueFor(checkSecrets);
+  if (keychainIssue) detail = keychainIssue.message;
   return {
     ...p,
+    ...(keychainIssue ? { keychainIssue } : {}),
     group: 'api',
     type: 'api-key',
     enabled: configuredEnabled || authenticated,
@@ -406,7 +466,9 @@ function customProviderRows(providers, checkSecrets) {
 export async function providerSetup(config = {}, options = {}) {
   const providers = config.providers || {};
   const checkSecrets = options?.checkSecrets !== false;
+  const keychain = checkSecrets ? keychainIssueFor(true) : null;
   return {
+    ...(keychain ? { keychain } : {}),
     api: [
       ...API_PROVIDERS.map((p) => apiProviderSetup(p, providers, checkSecrets)),
       ...customProviderRows(providers, checkSecrets),
@@ -500,7 +562,7 @@ export async function authenticateProvider(provider, secret) {
   }
   const value = String(secret || '').trim();
   if (!value) throw new Error(`API key is required for ${id}`);
-  saveSecret(SECRET_ACCOUNTS.agentApiKey(id), value);
+  await saveSecretAsync(SECRET_ACCOUNTS.agentApiKey(id), value);
   return { provider: id, type: 'api-key', authenticated: true };
 }
 
@@ -638,6 +700,7 @@ export async function beginOAuthProviderLogin(cfgMod, provider, options = {}) {
     type: 'oauth',
     url: started.url,
     manualUrl: started.manualUrl || null,
+    userCode: started.userCode || null,
     waitForCallback: started.waitForCallback?.then(finish),
     cancel: () => {
       cancelled = true;
@@ -704,12 +767,12 @@ export function updateProviderAccounts(provider, change) {
   return listProviderAccounts(provider);
 }
 
-export function saveProviderApiKey(cfgMod, provider, secret) {
+export async function saveProviderApiKey(cfgMod, provider, secret) {
   const id = String(provider || '').trim();
   if (!API_PROVIDER_IDS.has(id)) throw new Error(`unknown API-key provider "${id}"`);
   const value = String(secret || '').trim();
   if (!value) throw new Error(`API key is required for ${id}`);
-  saveSecret(SECRET_ACCOUNTS.agentApiKey(id), value);
+  await saveSecretAsync(SECRET_ACCOUNTS.agentApiKey(id), value);
   updateConfigProvider(cfgMod, id, { enabled: true });
   return { provider: id, type: 'api-key', authenticated: true };
 }
@@ -813,7 +876,7 @@ export async function saveCustomProvider(cfgMod, rawInput) {
   const entry = { ...config, type: 'custom', enabled: config.enabled !== false };
   const account = SECRET_ACCOUNTS.agentApiKey(id);
   const previousKey = typed && existingId ? getAgentApiKey(id) : null;
-  if (typed) saveSecret(account, typed);
+  if (typed) await saveSecretAsync(account, typed);
   try {
     const current = cfgMod.loadConfig();
     cfgMod.saveConfig(
@@ -822,8 +885,8 @@ export async function saveCustomProvider(cfgMod, rawInput) {
     );
   } catch (error) {
     if (typed) {
-      if (previousKey) saveSecret(account, previousKey);
-      else deleteSecret(account);
+      if (previousKey) await saveSecretAsync(account, previousKey);
+      else await deleteSecretAsync(account);
     }
     throw error;
   }
@@ -912,13 +975,13 @@ export async function updateCustomProviderModel(cfgMod, rawId, rawModelId, patch
   return customProviderRow(id, saved);
 }
 
-export function removeCustomProvider(cfgMod, rawId) {
+export async function removeCustomProvider(cfgMod, rawId) {
   const id = String(rawId || '').trim();
   existingCustomEntry(cfgMod, id);
   const current = cfgMod.loadConfig();
   const { [id]: _removed, ...providers } = current.providers || {};
   cfgMod.saveConfig({ ...current, providers }, { baseConfig: current });
-  deleteSecret(SECRET_ACCOUNTS.agentApiKey(id));
+  await deleteSecretAsync(SECRET_ACCOUNTS.agentApiKey(id));
   return { provider: id, type: 'custom', removed: true };
 }
 
@@ -977,15 +1040,15 @@ function discoveryErrorView(error, apiKey) {
   };
 }
 
-export function saveOpenAIUsageSessionKey(cfgMod, secret) {
+export async function saveOpenAIUsageSessionKey(cfgMod, secret) {
   const value = String(secret || '').trim();
   if (!value) throw new Error('OpenAI usage session key is required for credit lookup');
-  saveSecret(SECRET_ACCOUNTS.openaiUsageSessionKey, value);
+  await saveSecretAsync(SECRET_ACCOUNTS.openaiUsageSessionKey, value);
   updateConfigProvider(cfgMod, 'openai', { enabled: true });
   return { provider: 'openai', type: 'usage-auth', authenticated: true };
 }
 
-export function saveOpenCodeGoUsageAuth(cfgMod, { apiKey } = {}) {
+export async function saveOpenCodeGoUsageAuth(cfgMod, { apiKey } = {}) {
   const secret = String(apiKey || '').trim();
   if (!secret) throw new Error('OpenCode console API key is required for usage lookup');
   // Subscription meters are read with a console service-account key holding the
@@ -993,7 +1056,7 @@ export function saveOpenCodeGoUsageAuth(cfgMod, { apiKey } = {}) {
   // rejecting anything else here keeps unusable auth out of the keychain.
   if (!/^(?:oc_sk_|sk-)/.test(secret))
     throw new Error('OpenCode usage auth must be a console API key (oc_sk_… or sk-…) with all permissions');
-  saveSecret(SECRET_ACCOUNTS.opencodeGoConsoleKey, secret);
+  await saveSecretAsync(SECRET_ACCOUNTS.opencodeGoConsoleKey, secret);
   // Usage auth may be a different key from the inference key. Only flip the
   // model provider on when a model key actually exists; otherwise usage-only
   // setups get routed to the provider with apiKey 'no-key' and fail with 401s.
@@ -1001,7 +1064,7 @@ export function saveOpenCodeGoUsageAuth(cfgMod, { apiKey } = {}) {
   return { provider: 'opencode-go', type: 'usage-auth', authenticated: true };
 }
 
-export function forgetProviderAuth(cfgModOrProvider, maybeProvider, requestedAccountId) {
+export async function forgetProviderAuth(cfgModOrProvider, maybeProvider, requestedAccountId) {
   const cfgMod = maybeProvider === undefined ? null : cfgModOrProvider;
   const id = String(maybeProvider === undefined ? cfgModOrProvider : maybeProvider || '').trim();
   const oauth = availableOAuthProvider(id);
@@ -1022,7 +1085,7 @@ export function forgetProviderAuth(cfgModOrProvider, maybeProvider, requestedAcc
   if (!API_PROVIDER_IDS.has(id)) {
     throw new Error(`unknown provider "${id}"`);
   }
-  deleteSecret(SECRET_ACCOUNTS.agentApiKey(id));
+  await deleteSecretAsync(SECRET_ACCOUNTS.agentApiKey(id));
   if (cfgMod) updateConfigProvider(cfgMod, id, { enabled: false });
   return { provider: id, type: 'api-key', forgotten: true };
 }

package/src/session-runtime/services/seeds.mjs

@@ -59,16 +59,13 @@ function cleanupRetiredChannelSecrets(dataDir) {
   const marker = join(dataDir, '.retired-channel-secrets-cleaned');
   if (existsSync(marker)) return;
   void import('../../runtime/shared/config.mjs')
-    .then(({ deleteSecret }) => {
-      try {
-        deleteSecret('discord.token');
-      } catch {
-        /* best-effort */
-      }
-      try {
-        deleteSecret('telegram.token');
-      } catch {
-        /* best-effort */
+    .then(async ({ deleteSecretAsync }) => {
+      for (const account of ['discord.token', 'telegram.token']) {
+        try {
+          await deleteSecretAsync(account);
+        } catch {
+          /* best-effort */
+        }
       }
       try {
         writeFileSync(marker, `${new Date().toISOString()}\n`);

package/src/session-runtime/services/usage-dashboard-model.mjs

@@ -234,6 +234,10 @@ function providerDescription(id, group) {
       return 'Anthropic OAuth subscription quota';
     case 'grok-oauth':
       return 'Grok Build subscription quota';
+    case 'muse-code-oauth':
+      return 'Muse Code subscription quota';
+    case 'mimo-oauth':
+      return 'MiMo Token Plan subscription quota';
     case 'antigravity-oauth':
       return 'Antigravity subscription quota';
     case 'opencode-go':
@@ -338,6 +342,8 @@ const PROVIDER_RANKS = {
   'openai-oauth': 10,
   'anthropic-oauth': 20,
   'grok-oauth': 30,
+  'muse-code-oauth': 33,
+  'mimo-oauth': 34,
   'cursor-oauth': 35,
   'antigravity-oauth': 36,
   'opencode-go': 40,

package/src/session-runtime/settings-builtin-tools-api.mjs

@@ -8,6 +8,10 @@ import {
   setBuiltinInstalledInConfig,
 } from '../runtime/agent/orchestrator/runtime-core/builtin-features.mjs';
 import { LOCAL_PROVIDER_ID } from '../runtime/local-provider/managed-runtime.mjs';
+import {
+  INSTRUCTION_FILES_MODES,
+  normalizeInstructionFilesMode,
+} from '../runtime/shared/instruction-files-mode.mjs';
 import { getEmbeddingInfo } from '../runtime/memory/lib/embedding-provider.mjs';
 import { onnxRuntimeSupported } from '../runtime/shared/onnx-runtime-support.mjs';
 import {
@@ -79,6 +83,7 @@ export function createBuiltinToolSettings(
       const localProvider = getLocalProviderStatus?.() || {};
       const localProviderRuntimeInstalled = localProvider?.runtime?.installed === true;
       return {
+        instructionFiles: normalizeInstructionFilesMode(config?.instructionFiles),
         webSearch: { enabled: webSearchEnabled() },
         memory: {
           enabled: memoryToolsEnabledFn(),
@@ -118,6 +123,16 @@ export function createBuiltinToolSettings(
       await refreshEmptySessionToolPolicy?.();
       return this.getToolModuleSettings();
     },
+    /** Which user instruction files (AGENTS.md / CLAUDE.md) new sessions load:
+     *  'all' | 'agents' | 'claude' | 'off'. The empty session rebuilds now. */
+    async setInstructionFiles(mode) {
+      if (!INSTRUCTION_FILES_MODES.includes(mode)) {
+        throw new TypeError(`Instruction files must be one of ${INSTRUCTION_FILES_MODES.join(', ')}.`);
+      }
+      saveConfigAndAdopt({ ...getConfig(), instructionFiles: mode });
+      await refreshEmptySessionToolPolicy?.();
+      return this.getToolModuleSettings();
+    },
     async setMemoryToolsEnabled(enabled) {
       const config = getConfig();
       const memoryEnabled = enabled !== false;

package/src/session-runtime/settings-profile-api.mjs

@@ -1,6 +1,13 @@
 // Onboarding, the user profile (/profile) and the disabled-skill list. Methods
 // reference `this.*` so cross-member calls resolve against the facade object
 // these are spread into.
+import {
+  mergeStarterGuide,
+  requiredStarterGuideState,
+  storedStarterGuide,
+  withStarterGuideOnCompletion,
+} from './starter-guide-state.mjs';
+
 export function createProfileSettings({
   getConfig,
   adoptConfig,
@@ -19,21 +26,39 @@ export function createProfileSettings({
         version: nextConfig?.onboarding?.version || 0,
         default: nextConfig?.default || null,
         workflowRoutes: summarizeWorkflowRoutes(nextConfig),
+        starterGuide: storedStarterGuide(nextConfig?.onboarding?.starterGuide),
       };
     },
+    // Persist the desktop "Getting started" guide state beside the onboarding
+    // flags so it survives a lost renderer localStorage. Malformed input is
+    // rejected; a valid save merges forward, so a stale one cannot reopen a
+    // closed guide or forget a visited step.
+    saveStarterGuideState(state) {
+      const next = requiredStarterGuideState(state);
+      const config = getConfig();
+      const onboarding = config.onboarding || {};
+      saveConfigAndAdopt({
+        ...config,
+        onboarding: {
+          ...onboarding,
+          starterGuide: mergeStarterGuide(storedStarterGuide(onboarding.starterGuide), next),
+        },
+      });
+      return this.getOnboardingStatus();
+    },
     // Mark onboarding as done WITHOUT touching routes/agents/provider. Used by
     // the TUI "skip" (Esc) path so the wizard doesn't reappear next launch,
     // while leaving any existing config routes untouched.
     skipOnboarding() {
       const config = getConfig();
       const nextConfig = { ...config };
-      nextConfig.onboarding = {
+      nextConfig.onboarding = withStarterGuideOnCompletion(config.onboarding, {
         ...(nextConfig.onboarding || {}),
         completed: true,
         version: ONBOARDING_VERSION,
         completedAt: new Date().toISOString(),
         skipped: true,
-      };
+      });
       saveConfigAndAdopt(nextConfig);
       return this.getOnboardingStatus();
     },

package/src/session-runtime/setup-tool/executor.mjs

@@ -5,6 +5,7 @@
  *  registers the tool executor before it finishes assembling the API object. */
 import { builtinFeatureActive } from '../../runtime/agent/orchestrator/runtime-core/builtin-features.mjs';
 import { ORCHESTRATION_MODES } from '../../runtime/shared/orchestration.mjs';
+import { INSTRUCTION_FILES_MODES } from '../../runtime/shared/instruction-files-mode.mjs';
 import { MEDIA_KINDS } from '../../runtime/media/tool-defs.mjs';
 import { SETUP_DESKTOP_DOMAINS, SETUP_HANDOFFS } from './settings-contract.mjs';
 import { executeExtendedSetupAction, publicAutomation, publicHookRule, validateMcpInput } from './extended-actions.mjs';
@@ -205,6 +206,8 @@ async function featureStatus(rt, getConfig) {
   return {
     ...Object.fromEntries(
       Object.entries(rt.getToolModuleSettings?.() || {}).map(([name, settings]) => {
+        // Scalar settings (instructionFiles mode) pass through as-is.
+        if (!settings || typeof settings !== 'object') return [name, settings];
         const keys = [...FEATURE_STATUS_KEYS, ...(FEATURE_EXTRA_STATUS_KEYS[name] || [])];
         return [name, Object.fromEntries(Object.entries(settings).filter(([key]) => keys.includes(key)))];
       })
@@ -448,6 +451,8 @@ const SETUP_ACTION_HANDLERS = {
   set_memory_enabled: (rt, args) => rt.setMemoryToolsEnabled(requireBoolean(args.enabled)),
   set_recap_enabled: (rt, args) => rt.setRecapEnabled(requireBoolean(args.enabled)),
   set_web_search_enabled: (rt, args) => rt.setWebSearchEnabled(requireBoolean(args.enabled)),
+  set_instruction_files: (rt, args) =>
+    rt.setInstructionFiles(requireEnum(args.instructionFiles, INSTRUCTION_FILES_MODES, 'instructionFiles')),
   set_builtin_enabled: (rt, args, { requestDesktop }) => {
     const name = requireEnum(args.name, SETUP_BUILTIN_TOGGLE_FEATURES, 'name');
     if (DESKTOP_HOSTED_FEATURES.includes(name)) return requestDesktop(args);

package/src/session-runtime/setup-tool/tool-defs.mjs

@@ -5,6 +5,7 @@ import {
   SETUP_MCP_SCHEMA,
 } from './settings-contract.mjs';
 import { MEDIA_KINDS } from '../../runtime/media/tool-defs.mjs';
+import { INSTRUCTION_FILES_MODES } from '../../runtime/shared/instruction-files-mode.mjs';
 
 /** Built-in `setup` tool: the model's handle on a Mixdog user's persisted
  *  configuration. The description is a contract only; how to use each action
@@ -78,6 +79,7 @@ export const SETUP_ACTION_FIELDS = Object.freeze({
   set_memory_enabled: 'enabled',
   set_recap_enabled: 'enabled',
   set_web_search_enabled: 'enabled',
+  set_instruction_files: 'instructionFiles',
   set_builtin_enabled: 'name enabled',
   install_builtin: 'name',
   install_local_model: 'modelId',
@@ -212,6 +214,12 @@ export const SETUP_TOOL_DEFS = Object.freeze([
           description:
             'Boolean setters (set_*_enabled, set_compaction, set_auto_update, set_mcp_enabled, set_plugin_enabled).',
         },
+        instructionFiles: {
+          type: 'string',
+          enum: [...INSTRUCTION_FILES_MODES],
+          description:
+            'set_instruction_files: which user instruction files new sessions load (global ~/.codex/AGENTS.md, ~/.claude/CLAUDE.md, then the Project root\'s AGENTS.md/CLAUDE.md).',
+        },
         name: {
           type: 'string',
           description: `set_builtin_enabled: ${SETUP_BUILTIN_TOGGLE_FEATURES.join('|')}; install_builtin also accepts memory. Memory toggles use set_memory_enabled. revoke_linked_device: client id from status connection, not its display name; set_developer_option: option id from status developer; read_definition/delete_definition: the definition id; else MCP/plugin/provider id.`,