@notis_ai/cli 0.2.0-beta.136.1 → 0.2.0-beta.139.1

package/src/runtime/agent-memory-state.js

@@ -0,0 +1,126 @@
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+const MAX_SEEN_HASHES = 500;
+const MAX_PROMPT_CHARS = 12_000;
+
+function hash(value) {
+  return createHash('sha256').update(String(value || '')).digest('hex').slice(0, 24);
+}
+
+function statePath(sessionId, home = homedir()) {
+  if (!sessionId) return null;
+  return join(home, '.notis', 'agent-memory-hooks', `${hash(sessionId)}.json`);
+}
+
+function readState(sessionId, home) {
+  const filePath = statePath(sessionId, home);
+  if (!filePath || !existsSync(filePath)) return { seen: [], pending: null };
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, 'utf-8'));
+    return parsed && typeof parsed === 'object'
+      ? {
+          seen: Array.isArray(parsed.seen) ? parsed.seen.filter((item) => typeof item === 'string') : [],
+          pending: parsed.pending && typeof parsed.pending === 'object' ? parsed.pending : null,
+          identity: parsed.identity && typeof parsed.identity === 'object' ? parsed.identity : null,
+        }
+      : { seen: [], pending: null };
+  } catch {
+    return { seen: [], pending: null };
+  }
+}
+
+function inputIdentity(input) {
+  const profile = typeof input?.profile_name === 'string' ? input.profile_name : '';
+  const account = typeof input?.account_id === 'string' ? input.account_id : '';
+  const apiBase = typeof input?.api_base === 'string' ? input.api_base : '';
+  return profile && account && apiBase ? { profile, account, apiBase } : null;
+}
+
+function identityMatches(left, right) {
+  return (!left && !right) || Boolean(
+    left && right
+      && left.profile === right.profile
+      && left.account === right.account
+      && left.apiBase === right.apiBase,
+  );
+}
+
+function stateForInput(sessionId, input, home) {
+  const state = readState(sessionId, home);
+  const identity = inputIdentity(input);
+  if (identityMatches(state.identity, identity)) return state;
+  return { seen: [], pending: null, identity };
+}
+
+function writeState(sessionId, state, home) {
+  const filePath = statePath(sessionId, home);
+  if (!filePath) return;
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+  const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temporaryPath, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+  renameSync(temporaryPath, filePath);
+}
+
+export function rememberPendingTurn(input, home = homedir()) {
+  const sessionId = input?.session_id;
+  const prompt = typeof input?.prompt === 'string' ? input.prompt.trim() : '';
+  if (!sessionId || !prompt || ['/', '!', '#'].includes(prompt[0])) return;
+  const state = stateForInput(sessionId, input, home);
+  state.pending = {
+    prompt: prompt.slice(0, MAX_PROMPT_CHARS),
+    turn_id: typeof input?.turn_id === 'string' ? input.turn_id : null,
+    cwd: typeof input?.cwd === 'string' ? input.cwd : null,
+    recorded_at: new Date().toISOString(),
+  };
+  writeState(sessionId, state, home);
+}
+
+export function pendingTurn(input, home = homedir()) {
+  const sessionId = input?.session_id;
+  const state = readState(sessionId, home);
+  const identity = inputIdentity(input);
+  if (!identityMatches(state.identity, identity)) {
+    if (sessionId) writeState(sessionId, { seen: [], pending: null, identity }, home);
+    return null;
+  }
+  if (!state.pending) return null;
+  if (state.pending.turn_id && input?.turn_id && state.pending.turn_id !== input.turn_id) return null;
+  return state.pending;
+}
+
+export function completePendingTurn(input, home = homedir()) {
+  const sessionId = input?.session_id;
+  if (!sessionId) return;
+  const filePath = statePath(sessionId, home);
+  if (!filePath || !existsSync(filePath)) return;
+  const state = readState(sessionId, home);
+  if (!state.pending) return;
+  state.pending = null;
+  writeState(sessionId, state, home);
+}
+
+export function freshRecallItems(input, items, home = homedir()) {
+  const sessionId = input?.session_id;
+  if (!sessionId) return items;
+  const state = stateForInput(sessionId, input, home);
+  const seen = new Set(state.seen);
+  const fresh = [];
+  for (const item of items) {
+    const fingerprint = hash(item);
+    if (seen.has(fingerprint)) continue;
+    seen.add(fingerprint);
+    fresh.push(item);
+  }
+  state.seen = [...seen].slice(-MAX_SEEN_HASHES);
+  writeState(sessionId, state, home);
+  return fresh;
+}

package/src/runtime/agent-setup.js

@@ -0,0 +1,383 @@
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const INSTRUCTIONS_PATH = join(HERE, '..', '..', 'skills', 'notis-cli', 'AGENT_INSTRUCTIONS.md');
+const HOOK_BUNDLE_PATH = join(HERE, '..', '..', 'dist', 'agent-hooks', 'notis-agent-hook.mjs');
+const START_MARKER = '<!-- notis-cli:instructions:start -->';
+const END_MARKER = '<!-- notis-cli:instructions:end -->';
+const LEGACY_SENTINEL = 'Use the Notis CLI (`npx --package @notis_ai/cli@latest -- notis ...`)';
+const MANAGED_HOOK_MARKER = '--notis-managed-agent-hook';
+const LEGACY_MANAGED_HOOK_MARKER = 'NOTIS_MANAGED_AGENT_HOOK=1';
+
+export const AGENT_IDS = Object.freeze(['codex', 'claude-code']);
+
+function atomicWrite(filePath, contents, mode = 0o600) {
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+  const temporaryPath = `${filePath}.notis-${process.pid}-${Date.now()}.tmp`;
+  writeFileSync(temporaryPath, contents, { mode });
+  renameSync(temporaryPath, filePath);
+}
+
+function readText(filePath) {
+  return existsSync(filePath) ? readFileSync(filePath, 'utf-8') : '';
+}
+
+function activeCodexInstructionsPath(home) {
+  const overridePath = join(home, '.codex', 'AGENTS.override.md');
+  if (existsSync(overridePath) && readText(overridePath).trim()) {
+    return overridePath;
+  }
+  return join(home, '.codex', 'AGENTS.md');
+}
+
+function upsertInstructionBlock(filePath, block) {
+  const existing = readText(filePath);
+  const managedBlockPattern = new RegExp(
+    `${START_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${END_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`,
+    'g',
+  );
+  const managedBlocks = [...existing.matchAll(managedBlockPattern)];
+  let next;
+  let status;
+
+  if (managedBlocks.length) {
+    let replaced = false;
+    next = existing.replace(managedBlockPattern, () => {
+      if (replaced) return '';
+      replaced = true;
+      return block;
+    });
+    status = next === existing ? 'unchanged' : 'updated';
+  } else if (existing.includes(LEGACY_SENTINEL)) {
+    // An unmarked block belongs to the user or another installer. Do not risk
+    // rewriting adjacent personal instructions merely to take ownership of it.
+    return { path: filePath, status: 'already_present_unmanaged' };
+  } else {
+    const prefix = existing.trimEnd();
+    next = `${prefix ? `${prefix}\n\n` : ''}${block.trim()}\n`;
+    status = 'installed';
+  }
+
+  if (status !== 'unchanged') {
+    atomicWrite(filePath, next);
+  }
+  return { path: filePath, status };
+}
+
+function readJsonObject(filePath) {
+  if (!existsSync(filePath)) return {};
+  const raw = readFileSync(filePath, 'utf-8');
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('root value must be an object');
+    }
+    return parsed;
+  } catch (error) {
+    throw new Error(`Refusing to modify invalid JSON at ${filePath}: ${error.message}`);
+  }
+}
+
+function isManagedNotisHookCommand(command) {
+  if (typeof command !== 'string') return false;
+  if (
+    command.includes(MANAGED_HOOK_MARKER)
+    || command.includes(LEGACY_MANAGED_HOOK_MARKER)
+  ) return true;
+  if (
+    command.includes('.notis/agent-hooks/bin/notis-agent-hook')
+    && /\sagent-(?:context|capture)\b/.test(command)
+  ) return true;
+  // Supported legacy installers used either this package's bin/notis.js path
+  // or the exact public npx package. Do not claim arbitrary commands merely
+  // because they happen to use the same subcommand words.
+  return (
+    /(?:^|\s)(?:'[^']*|"[^"]*"|\S*)bin\/notis\.js(?:'|")?\s[^\n]*\sagent-(?:context|capture)\b/.test(command)
+    || /@notis_ai\/cli@[^\s]+\s+--\s+notis\s[^\n]*\sagent-(?:context|capture)\b/.test(command)
+    || /^\s*notis\s+(?:--[^\s]+\s+)*agent-(?:context|capture)\b/.test(command)
+  );
+}
+
+function objectHasManagedNotisHook(value) {
+  if (Array.isArray(value)) return value.some(objectHasManagedNotisHook);
+  if (!value || typeof value !== 'object') return false;
+  if (isManagedNotisHookCommand(value.command)) return true;
+  return Object.values(value).some(objectHasManagedNotisHook);
+}
+
+function fileHasManagedNotisHook(filePath) {
+  try {
+    return objectHasManagedNotisHook(readJsonObject(filePath));
+  } catch {
+    return false;
+  }
+}
+
+function removePriorNotisPromptHooks(groups) {
+  if (!Array.isArray(groups)) return [];
+  const kept = [];
+  for (const group of groups) {
+    if (!group || typeof group !== 'object' || !Array.isArray(group.hooks)) {
+      kept.push(group);
+      continue;
+    }
+    const hooks = group.hooks.filter((hook) => !isManagedNotisHookCommand(hook?.command));
+    if (hooks.length) kept.push({ ...group, hooks });
+  }
+  return kept;
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+
+export function installManagedHookRuntime({
+  home = homedir(),
+  bundlePath = HOOK_BUNDLE_PATH,
+  nodePath = process.execPath,
+  platform = process.platform,
+} = {}) {
+  const bundle = readFileSync(bundlePath);
+  const digest = createHash('sha256').update(bundle).digest('hex');
+  const runtimePath = join(
+    home,
+    '.notis',
+    'agent-hooks',
+    'runtime',
+    digest,
+    'notis-agent-hook.mjs',
+  );
+  const existingDigest = existsSync(runtimePath)
+    ? createHash('sha256').update(readFileSync(runtimePath)).digest('hex')
+    : null;
+  if (existingDigest !== digest) atomicWrite(runtimePath, bundle, 0o500);
+  chmodSync(runtimePath, 0o500);
+
+  const launcherPath = join(
+    home,
+    '.notis',
+    'agent-hooks',
+    'bin',
+    platform === 'win32' ? 'notis-agent-hook.cmd' : 'notis-agent-hook',
+  );
+  const launcher = platform === 'win32'
+    ? [
+        '@echo off',
+        `if not exist "${nodePath}" (`,
+        '  >&2 echo Notis memory hook runtime needs repair; run notis agents install again.',
+        '  exit /b 1',
+        ')',
+        `"${nodePath}" "${runtimePath}" %*`,
+        '',
+      ].join('\r\n')
+    : [
+        '#!/bin/sh',
+        `if [ -x ${shellQuote(nodePath)} ]; then`,
+        `  exec ${shellQuote(nodePath)} ${shellQuote(runtimePath)} "$@"`,
+        'fi',
+        `echo 'Notis memory hook runtime needs repair; run notis agents install again.' >&2`,
+        'exit 1',
+        '',
+      ].join('\n');
+  if (readText(launcherPath) !== launcher) {
+    // Windows maps the owner write bit to the read-only file attribute. A
+    // launcher installed by an older CLI is deliberately read-only, so make
+    // our owned file replaceable before the atomic rename used for upgrades.
+    if (platform === 'win32' && existsSync(launcherPath)) {
+      chmodSync(launcherPath, 0o700);
+    }
+    atomicWrite(launcherPath, launcher, 0o500);
+  }
+  chmodSync(launcherPath, 0o500);
+  return { launcherPath, runtimePath, digest };
+}
+
+function shellHookCommand(launcherPath, profileName, command, agentId = null, platform = process.platform) {
+  // Stored profile names follow a shell-safe grammar enforced by the CLI.
+  const agentFlag = agentId ? ` --agent ${agentId}` : '';
+  const quotedLauncher = platform === 'win32'
+    ? `"${launcherPath}"`
+    : shellQuote(launcherPath);
+  return `${quotedLauncher} ${MANAGED_HOOK_MARKER} --profile ${profileName} --timeout-ms 30000 ${command}${agentFlag}`;
+}
+
+function contextHandler(agentId, profileName, launcherPath, platform) {
+  return {
+    type: 'command',
+    command: shellHookCommand(launcherPath, profileName, 'agent-context', null, platform),
+    timeout: 30,
+    statusMessage: 'Loading relevant Notis memory',
+    ...(agentId === 'codex' ? { additionalContextLimit: 2500 } : {}),
+  };
+}
+
+function captureHandler(agentId, profileName, launcherPath, platform) {
+  return {
+    type: 'command',
+    command: shellHookCommand(launcherPath, profileName, 'agent-capture', agentId, platform),
+    timeout: 30,
+    statusMessage: 'Saving durable Notis context',
+  };
+}
+
+function upsertPromptHooks(
+  filePath,
+  agentId,
+  profileName,
+  enabled,
+  launcherPath = '',
+  platform = process.platform,
+) {
+  const settings = readJsonObject(filePath);
+  const hooks = settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks)
+    ? { ...settings.hooks }
+    : {};
+  let removedManagedHook = false;
+  for (const event of ['SessionStart', 'UserPromptSubmit', 'Stop']) {
+    const previousGroups = Array.isArray(hooks[event]) ? hooks[event] : [];
+    const groups = removePriorNotisPromptHooks(previousGroups);
+    if (JSON.stringify(groups) !== JSON.stringify(previousGroups)) removedManagedHook = true;
+    if (enabled) {
+      groups.push({ hooks: [event === 'Stop'
+        ? captureHandler(agentId, profileName, launcherPath, platform)
+        : contextHandler(agentId, profileName, launcherPath, platform)] });
+    }
+    if (groups.length) hooks[event] = groups;
+    else delete hooks[event];
+  }
+  const next = { ...settings, hooks };
+  const serialized = `${JSON.stringify(next, null, 2)}\n`;
+  const existing = readText(filePath);
+  if (!enabled && !removedManagedHook) return { path: filePath, status: 'unchanged' };
+  if (existing === serialized) return { path: filePath, status: 'unchanged' };
+  atomicWrite(filePath, serialized);
+  return {
+    path: filePath,
+    status: enabled
+      ? existsSync(filePath) && existing ? 'updated' : 'installed'
+      : 'removed',
+  };
+}
+
+function agentPaths(agentId, home) {
+  if (agentId === 'codex') {
+    return {
+      root: join(home, '.codex'),
+      instructions: activeCodexInstructionsPath(home),
+      hooks: join(home, '.codex', 'hooks.json'),
+    };
+  }
+  if (agentId === 'claude-code') {
+    return {
+      root: join(home, '.claude'),
+      instructions: join(home, '.claude', 'CLAUDE.md'),
+      hooks: join(home, '.claude', 'settings.json'),
+    };
+  }
+  throw new Error(`Unsupported agent: ${agentId}`);
+}
+
+export function shouldInstallLocalAgentSetup(env = process.env, home = homedir()) {
+  if (env.NOTIS_JWT || env.NOTIS_AGENT === '1' || env.NOTIS_DELEGATED_CONTEXT === '1') return false;
+  if (env.CONDUCTOR_IS_LOCAL === '0') return false;
+  if (existsSync('/vercel/sandbox')) return false;
+  return Boolean(home);
+}
+
+export function installAgentSetup({
+  profileName,
+  agents = AGENT_IDS,
+  memoryHooks = true,
+  onlyExisting = false,
+  detectedAgents = null,
+  home = homedir(),
+  platform = process.platform,
+} = {}) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(String(profileName || ''))) {
+    throw new Error('A valid authenticated Notis profile is required for agent setup');
+  }
+  const instructions = readFileSync(INSTRUCTIONS_PATH, 'utf-8').trim();
+  const results = [];
+  const shouldRepairManagedHooks = memoryHooks === true || (
+    memoryHooks === null
+    && agents.some((agentId) => fileHasManagedNotisHook(agentPaths(agentId, home).hooks))
+  );
+  const hookRuntime = shouldRepairManagedHooks
+    ? installManagedHookRuntime({ home, platform })
+    : null;
+
+  for (const agentId of agents) {
+    const paths = agentPaths(agentId, home);
+    const detected = Array.isArray(detectedAgents)
+      ? detectedAgents.includes(agentId)
+      : existsSync(paths.root);
+    if (onlyExisting && !detected) {
+      results.push({ agent: agentId, status: 'not_detected' });
+      continue;
+    }
+    const result = {
+      agent: agentId,
+      instructions: upsertInstructionBlock(paths.instructions, instructions),
+      memory_hook: null,
+    };
+    if (memoryHooks === null && !fileHasManagedNotisHook(paths.hooks)) {
+      result.memory_hook = { path: paths.hooks, status: 'preserved' };
+    } else {
+      try {
+        result.memory_hook = upsertPromptHooks(
+          paths.hooks,
+          agentId,
+          profileName,
+          memoryHooks !== false,
+          hookRuntime?.launcherPath,
+          platform,
+        );
+      } catch (error) {
+        result.memory_hook = {
+          path: paths.hooks,
+          status: 'error',
+          message: error instanceof Error ? error.message : String(error),
+        };
+      }
+    }
+    results.push(result);
+  }
+  return results;
+}
+
+export function detectedAgentIds(home = homedir()) {
+  return AGENT_IDS.filter((agentId) => {
+    const root = agentPaths(agentId, home).root;
+    if (!existsSync(root)) return false;
+    try {
+      const entries = readdirSync(root, { withFileTypes: true });
+      if (entries.some((entry) => entry.name !== 'skills')) return true;
+      const skillsRoot = join(root, 'skills');
+      if (!existsSync(skillsRoot)) return false;
+      // Base reconciliation intentionally creates every supported vendor root.
+      // A root containing only our three links is not evidence that the vendor
+      // itself is installed; any other skill entry is a genuine user signal.
+      return readdirSync(skillsRoot).some((name) => (
+        !['notis-apps', 'notis-query', 'notis-cli'].includes(name)
+      ));
+    } catch {
+      return false;
+    }
+  });
+}
+
+export function instructionTemplatePath() {
+  return INSTRUCTIONS_PATH;
+}

package/src/runtime/base-skills.d.ts

@@ -0,0 +1,20 @@
+export interface BaseSkillReconcileResult {
+  installed: number;
+  linked: number;
+  unchanged: number;
+  backups: string[];
+  skills: string[];
+}
+
+export const BASE_SKILL_NAMES: readonly string[];
+
+export function resolveBundledBaseSkillsRoot(options?: {
+  resourcesPath?: string;
+}): string;
+
+export function reconcileBaseSkills(options?: {
+  home?: string;
+  userId?: string | null;
+  sourceRoot?: string;
+  now?: number;
+}): BaseSkillReconcileResult;

package/src/runtime/base-skills.js

@@ -0,0 +1,167 @@
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readlinkSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const BASE_SKILL_NAMES = Object.freeze([
+  'notis-apps',
+  'notis-query',
+  'notis-cli',
+]);
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export function resolveBundledBaseSkillsRoot({ resourcesPath = process.resourcesPath } = {}) {
+  const sourceCheckout = resolve(HERE, '../../../../server/skills');
+  const packaged = resolve(HERE, '../../dist/base-skills');
+  const desktopResource = resourcesPath ? join(resourcesPath, 'base-skills') : null;
+  // Electron Packager copies each extraResource directory under its basename,
+  // so the three skill folders sit directly in process.resourcesPath.
+  const desktopPackagerRoot = resourcesPath || null;
+  for (const candidate of [sourceCheckout, packaged, desktopResource, desktopPackagerRoot]) {
+    if (
+      candidate
+      && BASE_SKILL_NAMES.every((name) => existsSync(join(candidate, name, 'SKILL.md')))
+    ) {
+      return candidate;
+    }
+  }
+  return packaged;
+}
+
+export function getBaseSkillPaths({ home = homedir(), userId = null } = {}) {
+  const notisRoot = join(home, '.notis', 'skills');
+  const targetRoots = [
+    join(home, '.agents', 'skills'),
+    join(home, '.codex', 'skills'),
+    join(home, '.cursor', 'skills'),
+    join(home, '.claude', 'skills'),
+  ];
+  if (userId) {
+    targetRoots.push(join(notisRoot, 'users', userId, 'skills'));
+  }
+  return {
+    baseRoot: join(notisRoot, 'base'),
+    backupRoot: join(notisRoot, 'backups'),
+    targetRoots,
+  };
+}
+
+function sameLinkTarget(linkPath, expectedTarget) {
+  try {
+    if (!lstatSync(linkPath).isSymbolicLink()) return false;
+    return resolve(dirname(linkPath), readlinkSync(linkPath)) === resolve(expectedTarget);
+  } catch {
+    return false;
+  }
+}
+
+function backupConflict(linkPath, backupRoot, targetLabel, skillName, now) {
+  const backupPath = join(backupRoot, String(now), targetLabel, skillName);
+  mkdirSync(dirname(backupPath), { recursive: true, mode: 0o700 });
+  renameSync(linkPath, backupPath);
+  return backupPath;
+}
+
+function replaceDirectory(source, destination) {
+  mkdirSync(dirname(destination), { recursive: true, mode: 0o700 });
+  const temporary = `${destination}.tmp-${process.pid}-${Date.now()}`;
+  const previous = `${destination}.previous-${process.pid}-${Date.now()}`;
+  rmSync(temporary, { recursive: true, force: true });
+  cpSync(source, temporary, { recursive: true });
+  let movedPrevious = false;
+  try {
+    if (existsSync(destination)) {
+      renameSync(destination, previous);
+      movedPrevious = true;
+    }
+    renameSync(temporary, destination);
+    if (movedPrevious) rmSync(previous, { recursive: true, force: true });
+  } catch (error) {
+    rmSync(temporary, { recursive: true, force: true });
+    if (movedPrevious && !existsSync(destination) && existsSync(previous)) {
+      renameSync(previous, destination);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Install the three CLI-owned system skills and expose them to every supported
+ * local agent. This intentionally does not consult the account sync setting:
+ * that setting controls only Electron's repeating account-skill refresh.
+ */
+export function reconcileBaseSkills({
+  home = homedir(),
+  userId = null,
+  sourceRoot = resolveBundledBaseSkillsRoot(),
+  now = Date.now(),
+} = {}) {
+  const paths = getBaseSkillPaths({ home, userId });
+  const result = {
+    installed: 0,
+    linked: 0,
+    unchanged: 0,
+    backups: [],
+    skills: [...BASE_SKILL_NAMES],
+  };
+
+  for (const name of BASE_SKILL_NAMES) {
+    const source = join(sourceRoot, name);
+    if (!existsSync(join(source, 'SKILL.md'))) {
+      throw new Error(`Bundled base skill is missing: ${name}`);
+    }
+    replaceDirectory(source, join(paths.baseRoot, name));
+    result.installed += 1;
+  }
+
+  for (const targetRoot of paths.targetRoots) {
+    mkdirSync(targetRoot, { recursive: true, mode: 0o700 });
+    const targetLabel = relative(home, targetRoot).replaceAll('/', '_') || 'home';
+    for (const name of BASE_SKILL_NAMES) {
+      const skillTarget = join(paths.baseRoot, name);
+      const linkPath = join(targetRoot, name);
+      if (sameLinkTarget(linkPath, skillTarget)) {
+        result.unchanged += 1;
+        continue;
+      }
+      if (existsSync(linkPath) || (() => {
+        try { lstatSync(linkPath); return true; } catch { return false; }
+      })()) {
+        // sameLinkTarget already accepted links owned by this installer. Every
+        // other path, including a user-created symlink, is a conflict whose
+        // identity and target must remain recoverable.
+        result.backups.push(backupConflict(linkPath, paths.backupRoot, targetLabel, name, now));
+      }
+      const relativeTarget = relative(targetRoot, skillTarget) || '.';
+      symlinkSync(
+        process.platform === 'win32' ? skillTarget : relativeTarget,
+        linkPath,
+        process.platform === 'win32' ? 'junction' : undefined,
+      );
+      result.linked += 1;
+    }
+  }
+
+  return result;
+}
+
+export function reconcileBaseSkillsBestEffort(options = {}) {
+  try {
+    return reconcileBaseSkills(options);
+  } catch (error) {
+    if (process.env.NOTIS_DEBUG_BASE_SKILLS === '1') {
+      process.stderr.write(`[notis] Base skill reconciliation failed: ${error.message}\n`);
+    }
+    return null;
+  }
+}