kenaz 0.0.0-stage → 0.3.2

package/core/dev/scripts/kenaz-session.js

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+/**
+ * kenaz-session.js — launch an interactive Ansuz session named
+ * <Project>-<Word>-<Animal> so cross-session messages (SendMessage /
+ * ListAgents) show which project each session is bound to (TASK_2079).
+ *
+ * Problem: every sub-project Ansuz runs with cwd = kenaz-core (the bundled
+ * core ships dev/, sub-projects only carry .kenaz/), so Claude Code's
+ * default session name `<cwd basename>-<2 chars>` is always "kenaz-core-xx"
+ * regardless of which project is actually pinned via the `/Ansuz [專案: ...]`
+ * prefix. `claude -n <name>` both sets the display name AND the
+ * SendMessage address, so a launcher that derives the name from the
+ * *project*, not cwd, fixes this without any Claude Code core change.
+ *
+ * Usage:
+ *   node dev/scripts/kenaz-session.js [project] [-- <extra claude args>]
+ *   node dev/scripts/kenaz-session.js [project] --dry-run
+ *
+ * `project` resolves against ~/.kenaz/projects.json (GEN-008: path built via
+ * os.homedir(), never hard-coded). No argument -> currentProjectId entry.
+ * The core entry (is_core / path "__kenaz_core__") is allowed and means no
+ * `[專案: ...]` pin.
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const cp = require('child_process');
+const crypto = require('crypto');
+
+// ---- NATO alphabet (Alfa..Zulu) and a fixed animal list, both matching
+// /^[A-Z][a-z]+$/ so buildSessionName's output matches
+// /^[A-Za-z0-9-]+-[A-Z][a-z]+-[A-Z][a-z]+$/. NATO's official "X-ray" has a
+// hyphen and would break that shape, so it is spelled "Xray" here.
+const NATO_WORDS = [
+  'Alfa', 'Bravo', 'Charlie', 'Delta', 'Echo', 'Foxtrot', 'Golf', 'Hotel',
+  'India', 'Juliett', 'Kilo', 'Lima', 'Mike', 'November', 'Oscar', 'Papa',
+  'Quebec', 'Romeo', 'Sierra', 'Tango', 'Uniform', 'Victor', 'Whiskey',
+  'Xray', 'Yankee', 'Zulu',
+];
+
+const ANIMALS = [
+  'Raptor', 'Falcon', 'Otter', 'Badger', 'Heron', 'Lynx', 'Cobra', 'Panther',
+  'Wolf', 'Fox', 'Bear', 'Eagle', 'Hawk', 'Owl', 'Tiger', 'Leopard', 'Jaguar',
+  'Cheetah', 'Wolverine', 'Mongoose', 'Ferret', 'Weasel', 'Marten', 'Ocelot',
+  'Puma', 'Cougar', 'Bobcat', 'Kestrel', 'Osprey', 'Peregrine',
+];
+
+const CORE_PATH_TOKEN = '__kenaz_core__';
+
+// ---- project resolution (R1) ----
+
+function projectsJsonPath(homeDir) {
+  return path.join(homeDir || os.homedir(), '.kenaz', 'projects.json');
+}
+
+function readProjectsJson(homeDir) {
+  const file = projectsJsonPath(homeDir);
+  try {
+    if (!fs.existsSync(file)) return null;
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (e) {
+    return null;
+  }
+}
+
+function isCoreEntry(entry) {
+  return !!(entry && (entry.is_core === true || entry.path === CORE_PATH_TOKEN));
+}
+
+function toResolvedProject(entry) {
+  return {
+    name: entry.name || path.basename(String(entry.path || '')),
+    path: isCoreEntry(entry) ? null : entry.path,
+    isCore: isCoreEntry(entry),
+  };
+}
+
+function unknownProjectError(arg, projects) {
+  const names = projects.map((p) => p.name).filter(Boolean);
+  const list = names.length ? names.join(', ') : '(none registered)';
+  return new Error(`kenaz-session: unknown project "${arg}". Known projects: ${list}`);
+}
+
+/**
+ * Resolve a project argument against a parsed projects.json document.
+ * Priority: no arg -> currentProjectId; exact name (case-insensitive);
+ * basename(entry.path) (case-insensitive); an existing directory path taken
+ * directly. Throws with the known-names list on no match.
+ * @param {string|undefined} arg
+ * @param {{currentProjectId?:string, projects?:object[]}|null} data
+ */
+function resolveProject(arg, data) {
+  const projects = data && Array.isArray(data.projects) ? data.projects : [];
+
+  if (!arg) {
+    const currentId = data && data.currentProjectId;
+    const entry = projects.find((p) => p.id === currentId);
+    if (entry) return toResolvedProject(entry);
+    throw unknownProjectError(arg || '(current)', projects);
+  }
+
+  const lower = arg.toLowerCase();
+
+  const byName = projects.find((p) => p.name && p.name.toLowerCase() === lower);
+  if (byName) return toResolvedProject(byName);
+
+  const byBasename = projects.find((p) => {
+    if (!p.path || p.path === CORE_PATH_TOKEN) return false;
+    return path.basename(p.path).toLowerCase() === lower;
+  });
+  if (byBasename) return toResolvedProject(byBasename);
+
+  let isDir = false;
+  try {
+    isDir = fs.statSync(arg).isDirectory();
+  } catch (e) {
+    isDir = false;
+  }
+  if (isDir) {
+    const resolved = path.resolve(arg);
+    return { name: path.basename(resolved), path: resolved, isCore: false };
+  }
+
+  throw unknownProjectError(arg, projects);
+}
+
+// ---- session name (R2) ----
+
+/**
+ * Collapse every run of characters outside [A-Za-z0-9] to a single '-' and
+ * trim leading/trailing '-'. Pure; may return '' (caller decides fallback).
+ */
+function sanitizeProjectPart(name) {
+  return String(name || '')
+    .replace(/[^A-Za-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function defaultRng(max) {
+  return crypto.randomInt(max);
+}
+
+/**
+ * Build "<ProjectPart>-<Word>-<Animal>". Pure given `rng(max)` returning an
+ * int in [0, max). Throws if projectName sanitizes to '' (never produce a
+ * name starting with '-').
+ * @param {string} projectName
+ * @param {(max: number) => number} [rng]
+ */
+function buildSessionName(projectName, rng) {
+  rng = rng || defaultRng;
+  const part = sanitizeProjectPart(projectName);
+  if (!part) {
+    throw new Error(`kenaz-session: project name "${projectName}" sanitizes to empty`);
+  }
+  const word = NATO_WORDS[rng(NATO_WORDS.length)];
+  const animal = ANIMALS[rng(ANIMALS.length)];
+  return `${part}-${word}-${animal}`;
+}
+
+/**
+ * Derive the ProjectPart to feed buildSessionName: sanitize the resolved
+ * project's name, falling back to sanitize(basename(project.path)) if the
+ * name alone sanitizes to '' (e.g. a name of all-punctuation like "___") —
+ * A2's negative control: never let the fallback produce a leading '-'.
+ * @param {{name:string, path:string|null}} project
+ */
+function deriveProjectPart(project) {
+  const fromName = sanitizeProjectPart(project.name);
+  if (fromName) return fromName;
+  if (project.path) return sanitizeProjectPart(path.basename(project.path));
+  return '';
+}
+
+// ---- claude argv (R3) ----
+
+/**
+ * Build claude's argv: ['-n', name, '/Ansuz [專案: <abs path>]', ...extra],
+ * or ['-n', name, '/Ansuz', ...extra] for the core project (no pin). Pure;
+ * the pin (with spaces/brackets/CJK) stays a single array element.
+ * @param {string} name
+ * @param {string|null} projectPath
+ * @param {boolean} isCore
+ * @param {string[]} [extra]
+ */
+function buildClaudeArgs(name, projectPath, isCore, extra) {
+  extra = extra || [];
+  const ansuzArg = isCore ? '/Ansuz' : `/Ansuz [\u5c08\u6848: ${path.resolve(projectPath)}]`;
+  return ['-n', name, ansuzArg, ...extra];
+}
+
+// ---- CLI arg parsing ----
+
+/**
+ * Split `[project] [--dry-run] [-- extra...]` from a raw argv slice.
+ * @param {string[]} argv
+ */
+function parseCliArgs(argv) {
+  const sepIndex = argv.indexOf('--');
+  const head = sepIndex === -1 ? argv.slice() : argv.slice(0, sepIndex);
+  const extra = sepIndex === -1 ? [] : argv.slice(sepIndex + 1);
+  const dryRunIndex = head.indexOf('--dry-run');
+  const dryRun = dryRunIndex !== -1;
+  if (dryRun) head.splice(dryRunIndex, 1);
+  const project = head.length > 0 ? head[0] : undefined;
+  return { project, dryRun, extra };
+}
+
+// ---- Windows executable resolution + cmd.exe quoting (R4) ----
+
+/**
+ * `where claude` on Windows; prefer a .exe (spawn shell:false), else fall
+ * back to the first .cmd found (or the literal "claude.cmd") via shell:true.
+ * @param {() => string} [whereFn] injectable for tests
+ */
+function resolveExecutableWindows(whereFn) {
+  whereFn = whereFn || function runWhere() {
+    try {
+      return cp.execSync('where claude', { encoding: 'utf8' });
+    } catch (e) {
+      return '';
+    }
+  };
+  const out = whereFn() || '';
+  const candidates = out.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+  const exe = candidates.find((c) => /\.exe$/i.test(c));
+  if (exe) return { command: exe, useShell: false };
+  const cmd = candidates.find((c) => /\.cmd$/i.test(c));
+  return { command: cmd || 'claude.cmd', useShell: true };
+}
+
+/**
+ * @param {{platform?:string, whereFn?:() => string}} [options]
+ */
+function resolveExecutable(options) {
+  options = options || {};
+  const platform = options.platform || process.platform;
+  if (platform === 'win32') return resolveExecutableWindows(options.whereFn);
+  return { command: 'claude', useShell: false };
+}
+
+// cmd.exe argument quoting, based on the algorithm at https://qntm.org/cmd
+// (also used by npm's cross-spawn): quotes are load-bearing because cmd.exe
+// re-processes metachars even inside quotes, which is exactly the failure
+// class noted for '/Ansuz [專案: C:\Users\x\My Project]' (spaces, brackets,
+// CJK must arrive as ONE argv element).
+const CMD_META_CHARS_RE = /([()%!^"<>&|;,\s])/g;
+
+function escapeCmdArg(arg) {
+  let s = String(arg);
+  s = s.replace(/(\\*)"/g, '$1$1\\"');
+  s = s.replace(/(\\*)$/, '$1$1');
+  s = `"${s}"`;
+  s = s.replace(CMD_META_CHARS_RE, '^$1');
+  return s;
+}
+
+function escapeCmdExe(exe) {
+  return /[\s&()%!^<>|"]/.test(exe) ? `"${String(exe).replace(/"/g, '""')}"` : exe;
+}
+
+function launch(exec, cwd, argv) {
+  if (exec.useShell) {
+    return cp.spawn(escapeCmdExe(exec.command), argv.map(escapeCmdArg), {
+      cwd,
+      stdio: 'inherit',
+      shell: true,
+    });
+  }
+  return cp.spawn(exec.command, argv, { cwd, stdio: 'inherit', shell: false });
+}
+
+// ---- main ----
+
+function main() {
+  const { project: projectArg, dryRun, extra } = parseCliArgs(process.argv.slice(2));
+
+  const data = readProjectsJson(os.homedir());
+  let project;
+  try {
+    project = resolveProject(projectArg, data);
+  } catch (e) {
+    process.stderr.write(`${e.message}\n`);
+    process.exit(1);
+    return;
+  }
+
+  const projectPart = deriveProjectPart(project);
+  if (!projectPart) {
+    process.stderr.write(
+      `kenaz-session: cannot derive a session name for project "${project.name}"\n`
+    );
+    process.exit(1);
+    return;
+  }
+
+  let sessionName;
+  try {
+    sessionName = buildSessionName(projectPart);
+  } catch (e) {
+    process.stderr.write(`${e.message}\n`);
+    process.exit(1);
+    return;
+  }
+
+  const coreRoot = path.resolve(__dirname, '..', '..');
+  const displayPath = project.isCore ? coreRoot : path.resolve(project.path);
+  console.log(`kenaz-session: ${sessionName} -> ${displayPath}`);
+
+  const claudeArgv = buildClaudeArgs(sessionName, project.path, project.isCore, extra);
+  const exec = resolveExecutable();
+
+  if (dryRun) {
+    console.log(JSON.stringify(
+      { executable: exec.command, useShell: exec.useShell, cwd: coreRoot, argv: claudeArgv },
+      null,
+      2
+    ));
+    return;
+  }
+
+  const child = launch(exec, coreRoot, claudeArgv);
+  child.on('exit', (code, signal) => {
+    process.exit(code != null ? code : (signal ? 1 : 1));
+  });
+  child.on('error', (e) => {
+    process.stderr.write(`kenaz-session: failed to launch claude: ${e.message}\n`);
+    process.exit(1);
+  });
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  NATO_WORDS,
+  ANIMALS,
+  projectsJsonPath,
+  readProjectsJson,
+  isCoreEntry,
+  resolveProject,
+  sanitizeProjectPart,
+  buildSessionName,
+  deriveProjectPart,
+  buildClaudeArgs,
+  parseCliArgs,
+  resolveExecutable,
+  resolveExecutableWindows,
+  escapeCmdArg,
+  escapeCmdExe,
+};

package/core/dev/scripts/kenaz-session.test.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+// TASK_2079: unit tests for kenaz-session.js's pure resolution/build
+// functions (project resolution, session-name shape, claude argv, cmd.exe
+// executable resolution). No real launch happens here — A3 (live dry-run /
+// real launch check) is verified by hand, not by this suite.
+//
+// Run: node --test dev/scripts/kenaz-session.test.js
+
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const mod = require('./kenaz-session.js');
+
+// Builds a temp HOME with a fixture ~/.kenaz/projects.json. currentProjectId
+// intentionally points at the non-core entry so the "no argument" test and
+// the "core entry" test exercise genuinely different code paths.
+function makeFixtureHome() {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kenaz-session-test-'));
+  const kenazDir = path.join(homeDir, '.kenaz');
+  fs.mkdirSync(kenazDir, { recursive: true });
+  const subProjectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kenaz-session-subproj-'));
+  const data = {
+    currentProjectId: 'proj_1',
+    projects: [
+      {
+        id: 'default',
+        name: 'Kenaz',
+        path: '__kenaz_core__',
+        core_path: '__kenaz_core__',
+        is_core: true,
+      },
+      {
+        id: 'proj_1',
+        name: 'GameAsset_auto/blender_model',
+        path: subProjectDir,
+        core_path: '__kenaz_core__',
+        is_core: false,
+      },
+    ],
+  };
+  fs.writeFileSync(path.join(kenazDir, 'projects.json'), JSON.stringify(data, null, 2), 'utf8');
+  return { homeDir, subProjectDir, data };
+}
+
+test('readProjectsJson: reads fixture from a temp HOME (GEN-008: no hard-coded path)', () => {
+  const { homeDir } = makeFixtureHome();
+  const data = mod.readProjectsJson(homeDir);
+  assert.equal(data.currentProjectId, 'proj_1');
+  assert.equal(data.projects.length, 2);
+});
+
+test('resolveProject: exact name match, case-insensitive', () => {
+  const { homeDir, subProjectDir } = makeFixtureHome();
+  const data = mod.readProjectsJson(homeDir);
+  const result = mod.resolveProject('gameasset_auto/blender_model', data);
+  assert.equal(result.name, 'GameAsset_auto/blender_model');
+  assert.equal(result.path, subProjectDir);
+  assert.equal(result.isCore, false);
+});
+
+test('resolveProject: basename(entry.path) match, case-insensitive', () => {
+  const { homeDir, subProjectDir } = makeFixtureHome();
+  const data = mod.readProjectsJson(homeDir);
+  const result = mod.resolveProject(path.basename(subProjectDir).toUpperCase(), data);
+  assert.equal(result.path, subProjectDir);
+  assert.equal(result.isCore, false);
+});
+
+test('resolveProject: existing directory path accepted directly', () => {
+  const { homeDir } = makeFixtureHome();
+  const otherDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kenaz-session-other-'));
+  const data = mod.readProjectsJson(homeDir);
+  const result = mod.resolveProject(otherDir, data);
+  assert.equal(result.path, path.resolve(otherDir));
+  assert.equal(result.name, path.basename(otherDir));
+  assert.equal(result.isCore, false);
+});
+
+test('resolveProject: no argument -> currentProjectId entry', () => {
+  const { homeDir, subProjectDir } = makeFixtureHome();
+  const data = mod.readProjectsJson(homeDir);
+  const result = mod.resolveProject(undefined, data);
+  assert.equal(result.name, 'GameAsset_auto/blender_model');
+  assert.equal(result.path, subProjectDir);
+  assert.equal(result.isCore, false);
+});
+
+test('resolveProject: core entry (is_core / "__kenaz_core__") -> isCore true, path null (no pin)', () => {
+  const { homeDir } = makeFixtureHome();
+  const data = mod.readProjectsJson(homeDir);
+  const result = mod.resolveProject('Kenaz', data);
+  assert.equal(result.isCore, true);
+  assert.equal(result.path, null);
+});
+
+test('resolveProject: unknown project -> throws listing known names', () => {
+  const { homeDir } = makeFixtureHome();
+  const data = mod.readProjectsJson(homeDir);
+  assert.throws(
+    () => mod.resolveProject('NoSuchProject', data),
+    (err) => {
+      assert.match(err.message, /unknown project/i);
+      assert.match(err.message, /Kenaz/);
+      assert.match(err.message, /GameAsset_auto\/blender_model/);
+      return true;
+    }
+  );
+});
+
+test('buildSessionName: sanitizes "GameAsset_auto/blender_model" -> "GameAsset-auto-blender-model"', () => {
+  const rng = () => 0; // seeded: always the first NATO word / animal
+  const name = mod.buildSessionName('GameAsset_auto/blender_model', rng);
+  assert.equal(name, `GameAsset-auto-blender-model-${mod.NATO_WORDS[0]}-${mod.ANIMALS[0]}`);
+  assert.match(name, /^[A-Za-z0-9-]+-[A-Z][a-z]+-[A-Z][a-z]+$/);
+});
+
+test('buildSessionName: seeded rng deterministically picks word/animal by index', () => {
+  let call = 0;
+  const rng = () => {
+    call += 1;
+    return call === 1 ? 2 : 5;
+  };
+  const name = mod.buildSessionName('Ashfall', rng);
+  assert.equal(name, `Ashfall-${mod.NATO_WORDS[2]}-${mod.ANIMALS[5]}`);
+});
+
+// Negative control (A2): a project name that sanitizes to '' must never
+// silently produce a name starting with '-'. buildSessionName rejects it.
+test('buildSessionName: negative control -- "___" sanitizes to empty and is rejected', () => {
+  assert.throws(() => mod.buildSessionName('___', () => 0), /sanitizes to empty/);
+});
+
+// Negative control (A2), full path: the higher-level deriveProjectPart falls
+// back to basename(project.path) instead of producing a leading '-'.
+test('deriveProjectPart: falls back to basename(path) when name sanitizes to empty (A2)', () => {
+  const projectPath = path.join(os.tmpdir(), 'my_real_project');
+  const part = mod.deriveProjectPart({ name: '___', path: projectPath });
+  assert.equal(part, 'my-real-project');
+  assert.ok(!part.startsWith('-'));
+  const sessionName = mod.buildSessionName(part, () => 0);
+  assert.ok(!sessionName.startsWith('-'));
+  assert.match(sessionName, /^[A-Za-z0-9-]+-[A-Z][a-z]+-[A-Z][a-z]+$/);
+});
+
+test('deriveProjectPart: no path to fall back to -> empty string (caller must reject)', () => {
+  const part = mod.deriveProjectPart({ name: '___', path: null });
+  assert.equal(part, '');
+});
+
+test('buildClaudeArgs: keeps the /Ansuz pin as a single argv element (spaces + CJK)', () => {
+  const projectPath = 'C:\\Users\\x\\My Project';
+  const argv = mod.buildClaudeArgs('Ashfall-Charlie-Raptor', projectPath, false, []);
+  assert.equal(argv.length, 3);
+  assert.deepEqual(argv.slice(0, 2), ['-n', 'Ashfall-Charlie-Raptor']);
+  assert.equal(argv[2], `/Ansuz [\u5c08\u6848: ${path.resolve(projectPath)}]`);
+  assert.ok(argv[2].includes(' ') && argv[2].includes('\u5c08\u6848'));
+});
+
+test('buildClaudeArgs: core project -> "/Ansuz" with no pin', () => {
+  const argv = mod.buildClaudeArgs('Kenaz-Delta-Otter', null, true, []);
+  assert.deepEqual(argv, ['-n', 'Kenaz-Delta-Otter', '/Ansuz']);
+});
+
+test('buildClaudeArgs: extra args after "--" are appended in order', () => {
+  const argv = mod.buildClaudeArgs('X-Y-Z', '/tmp/p', false, ['--foo', 'bar']);
+  assert.deepEqual(argv.slice(-2), ['--foo', 'bar']);
+});
+
+test('parseCliArgs: project, --dry-run, and extra args after --', () => {
+  const { project, dryRun, extra } = mod.parseCliArgs(['Alaya', '--dry-run', '--', '--resume']);
+  assert.equal(project, 'Alaya');
+  assert.equal(dryRun, true);
+  assert.deepEqual(extra, ['--resume']);
+});
+
+test('parseCliArgs: no project, no --dry-run, no extra', () => {
+  const { project, dryRun, extra } = mod.parseCliArgs([]);
+  assert.equal(project, undefined);
+  assert.equal(dryRun, false);
+  assert.deepEqual(extra, []);
+});
+
+test('escapeCmdArg: wraps an argument with spaces, brackets, and CJK in one quoted token', () => {
+  const raw = '/Ansuz [\u5c08\u6848: C:\\Users\\x\\My Project]';
+  const escaped = mod.escapeCmdArg(raw);
+  // The wrapping quotes are themselves cmd.exe metachars, so the ^-escaping
+  // pass (needed because cmd.exe re-processes metachars even inside quotes)
+  // turns the literal wrapping `"`s into `^"`. Strip the carets to check the
+  // underlying quoting structure is intact.
+  const withoutCarets = escaped.replace(/\^/g, '');
+  assert.ok(withoutCarets.startsWith('"') && withoutCarets.endsWith('"'));
+  assert.ok(escaped.includes('\u5c08\u6848'));
+});
+
+test('resolveExecutable: windows prefers a discovered .exe over .cmd (shell:false)', () => {
+  const exec = mod.resolveExecutable({
+    platform: 'win32',
+    whereFn: () => 'C:\\npm\\claude.cmd\r\nC:\\WinGet\\claude.exe\r\n',
+  });
+  assert.equal(exec.command, 'C:\\WinGet\\claude.exe');
+  assert.equal(exec.useShell, false);
+});
+
+test('resolveExecutable: windows falls back to .cmd via shell when no .exe found', () => {
+  const exec = mod.resolveExecutable({
+    platform: 'win32',
+    whereFn: () => 'C:\\npm\\claude.cmd\r\n',
+  });
+  assert.equal(exec.command, 'C:\\npm\\claude.cmd');
+  assert.equal(exec.useShell, true);
+});
+
+test('resolveExecutable: windows with no "where" output falls back to literal claude.cmd', () => {
+  const exec = mod.resolveExecutable({ platform: 'win32', whereFn: () => '' });
+  assert.equal(exec.command, 'claude.cmd');
+  assert.equal(exec.useShell, true);
+});
+
+test('resolveExecutable: non-windows spawns "claude" directly (shell:false)', () => {
+  const exec = mod.resolveExecutable({ platform: 'darwin' });
+  assert.deepEqual(exec, { command: 'claude', useShell: false });
+});
+
+// require.main guard: requiring the module here must not spawn/launch anything.
+test('requiring the module has no side effects (require.main guard)', () => {
+  assert.equal(typeof mod.buildSessionName, 'function');
+  assert.equal(typeof mod.buildClaudeArgs, 'function');
+  assert.equal(typeof mod.resolveProject, 'function');
+});

package/core/dev/scripts/legacy/README.md

@@ -0,0 +1,39 @@
+# Legacy Scripts
+
+This directory contains deprecated scripts that have been replaced by Rust implementations.
+
+## Archived Scripts
+
+### dev_agent_scheduler.ps1.bak
+- **Original Location**: `dev/scripts/dev_agent_scheduler.ps1`
+- **Archived Date**: 2026-02-05
+- **Replacement**: Rust Self-Enhancement Scheduler module
+- **New Location**: `dashboard/src-tauri/src/cmd_modules/self_enhancement/`
+
+**Reason for deprecation:**
+1. The PowerShell script required external process spawning from Tauri, which had reliability issues on Windows
+2. Cross-platform compatibility was limited
+3. The Rust implementation provides better integration with the Tauri event system
+4. Real-time status updates and proper state management through the dashboard UI
+
+**How to use the new system:**
+- Via Dashboard: Quick Actions > Self-Enhancement Card
+- Via Tauri Commands: `start_self_enhancement`, `stop_self_enhancement`, `get_self_enhancement_status`
+
+### multi_agent_scheduler.ps1.bak
+- **Original Location**: `dev/scripts/multi_agent_scheduler.ps1`
+- **Archived Date**: 2026-02-03
+- **Replacement**: Rust Multi-Agent Scheduler module
+- **New Location**: `dashboard/src-tauri/src/cmd_modules/scheduler/`
+
+## Rollback Instructions
+
+If you need to use the legacy PowerShell scripts:
+
+1. Copy the `.bak` file back to its original location (remove `.bak` extension)
+2. Run the script directly via PowerShell:
+   ```powershell
+   .\dev\scripts\dev_agent_scheduler.ps1 -InitialDelaySeconds 30 -IntervalMinutes 20
+   ```
+
+Note: The legacy scripts are kept for reference and emergency rollback only. They are no longer maintained.