fauxnix-cli 0.9.3 → 0.11.0

package/dist/doctor.d.ts

@@ -0,0 +1,20 @@
+export type DoctorOptions = {
+    home?: string;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    nodeVersion?: string;
+    /** Injected MCP-module loader. Default: dynamic import of ./mcp.js (does not start the server). */
+    loadMcp?: () => Promise<unknown>;
+};
+export type DoctorReport = {
+    lines: string[];
+    ok: boolean;
+};
+export declare function collectDoctorReport(opts?: DoctorOptions): Promise<DoctorReport>;
+export declare function claudeUserConfigPath(home: string, env: NodeJS.ProcessEnv): string;
+export declare function codexConfigPath(home: string, env: NodeJS.ProcessEnv): string;
+export declare function openCodeConfigPath(home: string, env: NodeJS.ProcessEnv): string;
+export declare function hasCodexFauxnix(text: string): boolean;
+export declare function hasOpenCodeFauxnix(data: unknown): boolean;
+export declare function isServerMap(value: unknown): boolean;
+export declare function serverMapHasFauxnix(value: unknown): boolean;

package/dist/doctor.js

@@ -0,0 +1,251 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const VALUE_INDENT = '             ';
+export async function collectDoctorReport(opts = {}) {
+    const home = opts.home ?? homedir();
+    const cwd = opts.cwd ?? process.cwd();
+    const env = opts.env ?? process.env;
+    const nodeVersion = opts.nodeVersion ?? process.version;
+    const lines = [''];
+    lines.push(...encodingLines(env));
+    lines.push('');
+    lines.push(field('claude', detectClaude(home, cwd, env)));
+    lines.push(field('codex', detectCodex(home, env)));
+    lines.push(field('opencode', detectOpenCode(home, env)));
+    lines.push('');
+    const mcp = await mcpLines(nodeVersion, opts.loadMcp);
+    lines.push(...mcp.lines);
+    return { lines, ok: mcp.ok };
+}
+function field(label, value) {
+    return `${label.padEnd(10)} : ${value}`;
+}
+function encodingLines(env) {
+    const raw = env.FAUXNIX_NATIVE_ENCODING;
+    const current = raw === undefined || raw === ''
+        ? 'unset → utf8 (default)'
+        : raw === 'ansi'
+            ? 'ansi → GBK-native admin tools'
+            : `${raw} → utf8 (only ansi selects GBK)`;
+    return [
+        field('encoding', 'UTF-8 default for native-tool pipelines'),
+        VALUE_INDENT + `current FAUXNIX_NATIVE_ENCODING=${current}`,
+        VALUE_INDENT + 'set FAUXNIX_NATIVE_ENCODING=ansi for GBK-native admin tools (ipconfig, tasklist)',
+    ];
+}
+function detectClaude(home, cwd, env) {
+    const userPath = claudeUserConfigPath(home, env);
+    const projectPath = join(cwd, '.mcp.json');
+    const userExists = existsSync(userPath);
+    const projectExists = existsSync(projectPath);
+    let user;
+    let project;
+    if (userExists)
+        user = inspectClaudeJson(userPath);
+    if (projectExists) {
+        const inspected = inspectClaudeJson(projectPath);
+        // Project-scope Claude MCP is always a top-level mcpServers object.
+        if (!inspected.parseError && inspected.hasTopLevelMcpServers)
+            project = inspected;
+    }
+    if (!userExists && !project)
+        return 'not detected — see README';
+    if (user?.hasFauxnix)
+        return `fauxnix MCP configured (${userPath})`;
+    if (project?.hasFauxnix)
+        return `fauxnix MCP configured (${projectPath})`;
+    if (userExists && user?.parseError) {
+        return `found ${userPath} (unreadable JSON) — see README`;
+    }
+    if (userExists) {
+        return `found ${userPath}, fauxnix MCP not listed — run: claude mcp add fauxnix -- fauxnix mcp`;
+    }
+    return `found ${projectPath}, fauxnix MCP not listed — see README`;
+}
+export function claudeUserConfigPath(home, env) {
+    const dir = env.CLAUDE_CONFIG_DIR?.trim();
+    if (dir)
+        return join(dir, '.claude.json');
+    return join(home, '.claude.json');
+}
+export function codexConfigPath(home, env) {
+    const codexHome = env.CODEX_HOME?.trim() || join(home, '.codex');
+    return join(codexHome, 'config.toml');
+}
+export function openCodeConfigPath(home, env) {
+    const xdg = env.XDG_CONFIG_HOME?.trim() || join(home, '.config');
+    return join(xdg, 'opencode', 'opencode.json');
+}
+function inspectClaudeJson(path) {
+    const text = readText(path);
+    if (text === undefined) {
+        return { parseError: true, hasTopLevelMcpServers: false, hasFauxnix: false };
+    }
+    let data;
+    try {
+        data = JSON.parse(stripBom(text));
+    }
+    catch {
+        return { parseError: true, hasTopLevelMcpServers: false, hasFauxnix: false };
+    }
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+        return { parseError: true, hasTopLevelMcpServers: false, hasFauxnix: false };
+    }
+    const rec = data;
+    const hasTopLevelMcpServers = isServerMap(rec.mcpServers);
+    let hasFauxnix = hasTopLevelMcpServers && serverMapHasFauxnix(rec.mcpServers);
+    const projects = rec.projects;
+    if (projects && typeof projects === 'object' && !Array.isArray(projects)) {
+        for (const proj of Object.values(projects)) {
+            if (!proj || typeof proj !== 'object' || Array.isArray(proj))
+                continue;
+            const servers = proj.mcpServers;
+            if (isServerMap(servers) && serverMapHasFauxnix(servers))
+                hasFauxnix = true;
+        }
+    }
+    return { parseError: false, hasTopLevelMcpServers, hasFauxnix };
+}
+function detectCodex(home, env) {
+    const path = codexConfigPath(home, env);
+    if (!existsSync(path))
+        return 'not detected — see README';
+    const text = readText(path);
+    if (text === undefined)
+        return `found ${path} (unreadable) — see README`;
+    if (hasCodexFauxnix(stripBom(text)))
+        return `fauxnix MCP configured (${path})`;
+    return `found ${path}, fauxnix MCP not listed — run: codex mcp add fauxnix -- fauxnix mcp`;
+}
+export function hasCodexFauxnix(text) {
+    if (/^\s*\[mcp_servers\.(?:fauxnix|"fauxnix"|'fauxnix')\]/im.test(text))
+        return true;
+    const tables = text.split(/^\s*\[/m);
+    for (const table of tables) {
+        if (!/^mcp_servers\./i.test(table))
+            continue;
+        const header = (table.split(/[\]\r\n]/, 1)[0] ?? '').trim();
+        if (/^mcp_servers\.(?:fauxnix|"fauxnix"|'fauxnix')$/i.test(header))
+            return true;
+        const cmd = /^\s*command\s*=\s*(?:"([^"]*)"|'([^']*)')/im.exec(table);
+        const command = cmd?.[1] ?? cmd?.[2];
+        if (command && isFauxnixExecutable(command))
+            return true;
+        const args = /^\s*args\s*=\s*\[([^\]]*)\]/im.exec(table);
+        if (args) {
+            const items = [...args[1].matchAll(/"([^"]*)"|'([^']*)'/g)].map((m) => m[1] ?? m[2] ?? '');
+            if (items.some(isFauxnixExecutable))
+                return true;
+        }
+    }
+    return false;
+}
+function detectOpenCode(home, env) {
+    const path = openCodeConfigPath(home, env);
+    if (!existsSync(path))
+        return 'not detected — see README';
+    const text = readText(path);
+    if (text === undefined)
+        return `found ${path} (unreadable) — see README`;
+    let data;
+    try {
+        data = JSON.parse(stripBom(text));
+    }
+    catch {
+        return `found ${path} (unreadable JSON) — see README`;
+    }
+    if (hasOpenCodeFauxnix(data))
+        return `fauxnix MCP configured (${path})`;
+    return `found ${path}, fauxnix MCP not listed — add mcp.fauxnix (see README)`;
+}
+export function hasOpenCodeFauxnix(data) {
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return false;
+    const mcp = data.mcp;
+    if (!isServerMap(mcp))
+        return false;
+    if (serverMapHasFauxnix(mcp))
+        return true;
+    const nested = mcp.servers;
+    return isServerMap(nested) && serverMapHasFauxnix(nested);
+}
+export function isServerMap(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+export function serverMapHasFauxnix(value) {
+    if (!isServerMap(value))
+        return false;
+    for (const [name, cfg] of Object.entries(value)) {
+        if (name === 'servers')
+            continue;
+        if (looksLikeFauxnixServer(name, cfg))
+            return true;
+    }
+    return false;
+}
+function looksLikeFauxnixServer(name, cfg) {
+    if (/^fauxnix(-cli)?$/i.test(name))
+        return true;
+    if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg))
+        return false;
+    const rec = cfg;
+    const chunks = [];
+    if (typeof rec.command === 'string')
+        chunks.push(rec.command);
+    if (Array.isArray(rec.command)) {
+        for (const part of rec.command)
+            if (typeof part === 'string')
+                chunks.push(part);
+    }
+    if (Array.isArray(rec.args)) {
+        for (const part of rec.args)
+            if (typeof part === 'string')
+                chunks.push(part);
+    }
+    return chunks.some(isFauxnixExecutable);
+}
+function isFauxnixExecutable(s) {
+    const base = s.replace(/\\/g, '/').split('/').pop()?.trim() ?? '';
+    return /^fauxnix(-cli)?(\.cmd|\.exe)?$/i.test(base);
+}
+async function mcpLines(nodeVersion, loadMcp) {
+    const major = nodeMajor(nodeVersion);
+    const nodeOk = major >= 18;
+    let moduleOk = false;
+    let moduleDetail = '';
+    try {
+        const mod = await (loadMcp ?? defaultLoadMcp)();
+        moduleOk =
+            !!mod && typeof mod.startMcpServer === 'function';
+        if (!moduleOk)
+            moduleDetail = 'startMcpServer export missing';
+    }
+    catch (e) {
+        moduleDetail = e instanceof Error ? e.message : String(e);
+    }
+    const lines = [
+        field('node', `${nodeVersion.startsWith('v') ? nodeVersion : 'v' + nodeVersion}${nodeOk ? ' (>=18 required)' : '  FAILED (requires >=18)'}`),
+        field('mcp', moduleOk ? 'module loads' : `FAILED to load${moduleDetail ? ': ' + moduleDetail : ''}`),
+        VALUE_INDENT + 'start with: fauxnix mcp',
+    ];
+    return { lines, ok: nodeOk && moduleOk };
+}
+async function defaultLoadMcp() {
+    return import('./mcp.js');
+}
+function nodeMajor(version) {
+    const m = /^v?(\d+)/.exec(version);
+    return m ? Number(m[1]) : 0;
+}
+function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+function readText(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/install.d.ts

@@ -0,0 +1,15 @@
+export type InstallOptions = {
+    home?: string;
+    /** Accepted for parity with collectDoctorReport; install writes user-level configs only. */
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+};
+export type InstallReport = {
+    lines: string[];
+    ok: boolean;
+};
+export declare const INSTALL_FLAGS: readonly ["claude", "codex", "opencode", "kimi", "qwen"];
+export type HarnessName = (typeof INSTALL_FLAGS)[number];
+export declare function kimiConfigPath(home: string, env: NodeJS.ProcessEnv): string;
+export declare function qwenConfigPath(home: string, env: NodeJS.ProcessEnv): string;
+export declare function runInstall(argv: string[], opts?: InstallOptions): InstallReport;

package/dist/install.js

@@ -0,0 +1,206 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { claudeUserConfigPath, codexConfigPath, hasCodexFauxnix, hasOpenCodeFauxnix, isServerMap, openCodeConfigPath, serverMapHasFauxnix, } from './doctor.js';
+export const INSTALL_FLAGS = ['claude', 'codex', 'opencode', 'kimi', 'qwen'];
+const STDIO = { command: 'fauxnix', args: ['mcp'] };
+const OPENCODE_STDIO = { type: 'local', command: ['fauxnix', 'mcp'] };
+export function kimiConfigPath(home, env) {
+    const root = env.KIMI_CODE_HOME?.trim() || join(home, '.kimi-code');
+    return join(root, 'mcp.json');
+}
+export function qwenConfigPath(home, env) {
+    return join(home, '.qwen', 'settings.json');
+}
+export function runInstall(argv, opts = {}) {
+    const parsed = parseHarnessFlags(argv);
+    if (parsed.help)
+        return { lines: installUsageLines(), ok: true };
+    if (parsed.error)
+        return { lines: [parsed.error, ...installUsageLines()], ok: false };
+    const ctx = {
+        home: opts.home ?? homedir(),
+        env: opts.env ?? process.env,
+    };
+    const lines = [];
+    let ok = true;
+    for (const name of parsed.harnesses) {
+        const one = installHarness(name, ctx);
+        lines.push(one.line);
+        if (!one.ok)
+            ok = false;
+    }
+    return { lines, ok };
+}
+function parseHarnessFlags(argv) {
+    if (argv.some((a) => a === '--help' || a === '-h'))
+        return { help: true, harnesses: [] };
+    if (argv.length === 0) {
+        return { error: 'select a harness: --claude --codex --opencode --kimi --qwen', harnesses: [] };
+    }
+    const harnesses = [];
+    const seen = new Set();
+    for (const a of argv) {
+        if (!a.startsWith('--') || a === '--') {
+            return { error: `unknown argument: ${a}`, harnesses: [] };
+        }
+        const name = a.slice(2);
+        if (!isHarness(name))
+            return { error: `unknown harness: ${a}`, harnesses: [] };
+        if (!seen.has(name)) {
+            seen.add(name);
+            harnesses.push(name);
+        }
+    }
+    return { harnesses };
+}
+function isHarness(s) {
+    return INSTALL_FLAGS.includes(s);
+}
+function installUsageLines() {
+    return ['Usage:', '  fauxnix install --claude|--codex|--opencode|--kimi|--qwen'];
+}
+function installHarness(name, ctx) {
+    switch (name) {
+        case 'claude':
+            return patchMcpServers(claudeUserConfigPath(ctx.home, ctx.env), 'claude');
+        case 'codex':
+            return patchCodex(codexConfigPath(ctx.home, ctx.env));
+        case 'opencode':
+            return patchOpenCode(openCodeConfigPath(ctx.home, ctx.env));
+        case 'kimi':
+            return patchMcpServers(kimiConfigPath(ctx.home, ctx.env), 'kimi');
+        case 'qwen':
+            return patchMcpServers(qwenConfigPath(ctx.home, ctx.env), 'qwen');
+    }
+}
+function patchMcpServers(path, harness) {
+    const read = readJsonObject(path);
+    if (read.state === 'invalid') {
+        return { ok: false, line: `${harness}: ${path} is ${read.reason} — not modified` };
+    }
+    const existed = read.state !== 'missing';
+    const data = read.state === 'ok' ? read.data : {};
+    if (serverMapHasFauxnix(data.mcpServers)) {
+        return { ok: true, line: `${harness}: already configured (${path})` };
+    }
+    if (data.mcpServers != null && !isServerMap(data.mcpServers)) {
+        return { ok: false, line: `${harness}: ${path} mcpServers is not an object — not modified` };
+    }
+    if (!isServerMap(data.mcpServers))
+        data.mcpServers = {};
+    data.mcpServers.fauxnix = {
+        command: STDIO.command,
+        args: [...STDIO.args],
+    };
+    return writeJson(path, data, harness, existed, 'added mcpServers.fauxnix');
+}
+function patchOpenCode(path) {
+    const read = readJsonObject(path);
+    if (read.state === 'invalid') {
+        return { ok: false, line: `opencode: ${path} is ${read.reason} — not modified` };
+    }
+    const existed = read.state !== 'missing';
+    const data = read.state === 'ok' ? read.data : {};
+    if (hasOpenCodeFauxnix(data)) {
+        return { ok: true, line: `opencode: already configured (${path})` };
+    }
+    if (data.mcp != null && !isServerMap(data.mcp)) {
+        return { ok: false, line: `opencode: ${path} mcp is not an object — not modified` };
+    }
+    if (!isServerMap(data.mcp))
+        data.mcp = {};
+    const mcp = data.mcp;
+    const payload = { type: OPENCODE_STDIO.type, command: [...OPENCODE_STDIO.command] };
+    if (isServerMap(mcp.servers)) {
+        mcp.servers.fauxnix = payload;
+        return writeJson(path, data, 'opencode', existed, 'added mcp.servers.fauxnix');
+    }
+    mcp.fauxnix = payload;
+    return writeJson(path, data, 'opencode', existed, 'added mcp.fauxnix');
+}
+function patchCodex(path) {
+    const existed = existsSync(path);
+    if (!existed) {
+        const written = writeText(path, tomlTable('\n'));
+        if (!written.ok)
+            return { ok: false, line: `codex: failed to write ${path}: ${written.error}` };
+        return { ok: true, line: `codex: created ${path}` };
+    }
+    const text = readText(path);
+    if (text === undefined) {
+        return { ok: false, line: `codex: ${path} is unreadable — not modified` };
+    }
+    if (hasCodexFauxnix(stripBom(text))) {
+        return { ok: true, line: `codex: already configured (${path})` };
+    }
+    const nl = text.includes('\r\n') ? '\r\n' : '\n';
+    if (stripBom(text).trim() === '') {
+        const written = writeText(path, tomlTable(nl));
+        if (!written.ok)
+            return { ok: false, line: `codex: failed to write ${path}: ${written.error}` };
+        return { ok: true, line: `codex: patched ${path} (appended [mcp_servers.fauxnix])` };
+    }
+    let body = text;
+    if (!body.endsWith('\n'))
+        body += nl;
+    if (!body.endsWith(nl + nl))
+        body += nl;
+    const written = writeText(path, body + tomlTable(nl));
+    if (!written.ok)
+        return { ok: false, line: `codex: failed to write ${path}: ${written.error}` };
+    return { ok: true, line: `codex: patched ${path} (appended [mcp_servers.fauxnix])` };
+}
+function tomlTable(nl) {
+    return `[mcp_servers.fauxnix]${nl}command = "fauxnix"${nl}args = ["mcp"]${nl}`;
+}
+function writeJson(path, data, harness, existed, change) {
+    const written = writeText(path, JSON.stringify(data, null, 2) + '\n');
+    if (!written.ok) {
+        return { ok: false, line: `${harness}: failed to write ${path}: ${written.error}` };
+    }
+    if (existed)
+        return { ok: true, line: `${harness}: patched ${path} (${change})` };
+    return { ok: true, line: `${harness}: created ${path}` };
+}
+function writeText(path, contents) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, contents, 'utf8');
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+function readJsonObject(path) {
+    if (!existsSync(path))
+        return { state: 'missing' };
+    const text = readText(path);
+    if (text === undefined)
+        return { state: 'invalid', reason: 'unreadable' };
+    const stripped = stripBom(text).trim();
+    if (stripped === '')
+        return { state: 'empty' };
+    try {
+        const data = JSON.parse(stripped);
+        if (!data || typeof data !== 'object' || Array.isArray(data)) {
+            return { state: 'invalid', reason: 'not a JSON object' };
+        }
+        return { state: 'ok', data: data };
+    }
+    catch {
+        return { state: 'invalid', reason: 'not valid JSON' };
+    }
+}
+function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+function readText(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/mcp.d.ts

@@ -19,5 +19,11 @@ export declare function bashToolResult(r: ExecResult, sessionId: string, infra:
         sessionId: string;
     };
 };
+export declare function positionalCountFromEnv(env: Record<string, string>): number;
+export declare function formatSessionStatus(session: {
+    cwd: string | null;
+    env: Record<string, string>;
+    id: string;
+}): string;
 export declare function startMcpServer(): Promise<void>;
 export { translatePipelineBody };

package/dist/mcp.js

@@ -31,11 +31,10 @@ const TOOL_DESCRIPTION = `Execute a Linux/bash-style command on this Windows mac
 Commands are deterministically translated to PowerShell and executed natively — no WSL or VM.
 Output is formatted to look like GNU/Linux tooling (ls -l, ps aux, df -h ...), errors look like bash errors, and text encoding (UTF-8/GBK) is handled automatically.
 
-Supported: pipes (|), && / || / ;, redirections (> >> 2> 2>&1 < /dev/null), variables ($VAR $HOME ~), command substitution $(...), and ${registeredNames().length}+ coreutils-style commands (${registeredNames().slice(0, 18).join(', ')}...).
+Supported: pipes (|), && / || / ;, redirections (> >> 2> 2>&1 < /dev/null), variables ($VAR $HOME $1 $# "$@" ~), set -- / shift, array assignment A=(x y z), \${name[n]} \${#name[@]} \${name//pat/str} \${name:off:len}, command substitution $(...), and ${registeredNames().length}+ coreutils-style commands (${registeredNames().slice(0, 18).join(', ')}...).
 Unknown commands (git, node, npm, python, cargo...) are passed through and executed natively with argv-style quoting.
-Not supported: heredocs, while/until/case, env -i/--ignore-environment, background jobs. if/then/elif/else/fi, for-in loops, and word-level \$((...)) arithmetic expansion are supported.
-
-CWD, environment variables, export/unset and cd persist across calls within this session — a resident PowerShell 5.1 host is started when the MCP session begins (and after reset), so the first bash tool call is already warm.
+Not supported: heredocs, env -i/--ignore-environment, background jobs. if/then/elif/else/fi, for-in loops, while/until, case ... esac, and word-level \$((...)) arithmetic expansion are supported.
+CWD, environment variables, export/unset, cd, and positional parameters (set -- / $1 / "$@") persist across calls within this session — a resident PowerShell 5.1 host is started when the MCP session begins (and after reset), so the first bash tool call is already warm.
 Exit codes follow bash conventions (0 ok, 1 fail, 2 usage/serious, 127 command not found, 124 timeout, 130 cancelled). The tool also returns structuredContent (schemaVersion 1) with stdout/stderr/exitCode/timedOut/cancelled/truncated/sessionId.
 
 Platform requirement: the execution backend is native Windows PowerShell 5.1+. On hosts without PowerShell on PATH (e.g. Linux containers/sandboxes), the bash tool returns exit code 127 with an actionable error instead of running the command.`;
@@ -70,7 +69,35 @@ export function bashToolResult(r, sessionId, infra) {
         ...(infra ? { isError: true } : {}),
     };
 }
+/** Packed FAUXNIX_POS uses char-30 separators (same as array sidecar). */
+const POS_SEP = '\x1e';
+export function positionalCountFromEnv(env) {
+    let packed;
+    for (const [k, v] of Object.entries(env)) {
+        if (k.toUpperCase() === 'FAUXNIX_POS') {
+            packed = v;
+            break;
+        }
+    }
+    if (packed == null || packed === '')
+        return 0;
+    return packed.split(POS_SEP).length;
+}
+export function formatSessionStatus(session) {
+    const envKeys = Object.keys(session.env).sort();
+    return ('cwd: ' +
+        (session.cwd ?? '(inherit from server start)') +
+        '\nenv keys: ' +
+        (envKeys.length ? envKeys.join(', ') : '(none tracked)') +
+        '\npositionals: ' +
+        positionalCountFromEnv(session.env) +
+        '\nsession: ' +
+        session.id +
+        '\ncommands registered: ' +
+        registeredNames().length);
+}
 export async function startMcpServer() {
+    process.env.FAUXNIX_ARG0 = TOOL_NAME;
     const server = new McpServer({ name: 'fauxnix', version: packageVersion }, { capabilities: { tools: {} } });
     const session = new FauxnixSession();
     await session.prewarm();
@@ -117,22 +144,17 @@ export async function startMcpServer() {
             return { content: [{ type: 'text', text: msg }], isError: true };
         }
     });
-    server.tool('fauxnix_session', 'Inspect or reset the persistent fauxnix shell session (current directory, environment, session id). Actions: "status" (default) or "reset".', {
+    server.tool('fauxnix_session', 'Inspect or reset the persistent fauxnix shell session (current directory, environment, positional count, session id). Actions: "status" (default) or "reset".', {
         action: z
             .enum(['status', 'reset'])
             .default('status')
-            .describe('"status" shows the session state (cwd, tracked env keys); "reset" clears it back to a fresh shell'),
+            .describe('"status" shows the session state (cwd, tracked env keys, positional count); "reset" clears it back to a fresh shell'),
     }, SESSION_ANNOTATIONS, async ({ action }) => {
         if (action === 'reset') {
             await session.reset();
             return { content: [{ type: 'text', text: 'fauxnix: session reset' }] };
         }
-        const envKeys = Object.keys(session.env).sort();
-        const text = 'cwd: ' + (session.cwd ?? '(inherit from server start)') +
-            '\nenv keys: ' + (envKeys.length ? envKeys.join(', ') : '(none tracked)') +
-            '\nsession: ' + session.id +
-            '\ncommands registered: ' + registeredNames().length;
-        return { content: [{ type: 'text', text }] };
+        return { content: [{ type: 'text', text: formatSessionStatus(session) }] };
     });
     const transport = new StdioServerTransport();
     let shuttingDown = false;