zelari-code 1.44.0 → 1.46.1

package/dist/cli/ast/engine.js

@@ -10,9 +10,13 @@
  * wrapped) edit path — instead of fragile whole-file string matching.
  *
  * `typescript` is loaded lazily via dynamic import and kept OUT of the CLI
- * bundle (it's ~7MB, marked external in bundle-cli.mjs). Everything here is
- * best-effort: if `typescript` can't be loaded, the file can't be read, or it
- * isn't a TS/JS file, the functions return empty/null rather than throwing.
+ * bundle (it's ~7MB, marked external in bundle-cli.mjs).
+ *
+ * Loud degradation (v0.10.0 "loud tool errors"): `parseFileSymbolsDiag` is
+ * the primary entry point and returns a DISCRIMINATED result, so an empty
+ * outcome can never be confused with an unavailable backend. The legacy
+ * `parseFileSymbols`/`astOutline`/`findSymbol` helpers remain as quiet
+ * compatibility wrappers (empty/null on any non-ok status).
  */
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
@@ -31,30 +35,76 @@ function loadTs() {
     }
     return tsPromise;
 }
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 /**
  * Parse a TS/JS file into its top-level + nested declarations (with exact
- * source text). Returns [] for unsupported files, read errors, or when the
- * TypeScript compiler API is unavailable.
+ * source text), reporting WHY on every failure path.
+ *
+ * Relative paths resolve against `cwd ?? process.cwd()` (same rule as
+ * grep_content, see core builtin search.ts). Read errors distinguish ENOENT
+ * (`file-not-found`, reports the resolved absolute path) from anything else
+ * (`read-error`, propagates the message); a failing `createSourceFile`
+ * surfaces as `parse-error`.
  */
-export async function parseFileSymbols(file) {
-    if (!isAstSupported(file))
-        return [];
+export async function parseFileSymbolsDiag(file, cwd) {
+    const resolvedPath = path.isAbsolute(file)
+        ? file
+        : path.join(cwd ?? process.cwd(), file);
+    const extension = path.extname(resolvedPath).toLowerCase();
+    if (!TS_EXTENSIONS.has(extension)) {
+        return {
+            status: 'unsupported-extension',
+            extension: extension || '(none)',
+            resolvedPath,
+            recoverable: false,
+            recommendedFallback: 'read_file',
+        };
+    }
     const ts = await loadTs();
-    if (!ts)
-        return [];
+    if (!ts) {
+        return {
+            status: 'typescript-unavailable',
+            resolvedPath,
+            recoverable: true,
+            recommendedFallback: 'read_file',
+        };
+    }
     let text;
     try {
-        text = await readFile(file, 'utf8');
+        text = await readFile(resolvedPath, 'utf8');
     }
-    catch {
-        return [];
+    catch (err) {
+        const code = err?.code;
+        if (code === 'ENOENT') {
+            return {
+                status: 'file-not-found',
+                resolvedPath,
+                recoverable: false,
+                recommendedFallback: 'grep_content',
+            };
+        }
+        return {
+            status: 'read-error',
+            resolvedPath,
+            message: errMessage(err),
+            recoverable: true,
+            recommendedFallback: 'read_file',
+        };
     }
     let source;
     try {
-        source = ts.createSourceFile(path.basename(file), text, ts.ScriptTarget.Latest, true);
+        source = ts.createSourceFile(path.basename(resolvedPath), text, ts.ScriptTarget.Latest, true);
     }
-    catch {
-        return [];
+    catch (err) {
+        return {
+            status: 'parse-error',
+            resolvedPath,
+            message: errMessage(err),
+            recoverable: false,
+            recommendedFallback: 'read_file',
+        };
     }
     const out = [];
     const lineOf = (pos) => source.getLineAndCharacterOfPosition(pos).line + 1;
@@ -107,20 +157,33 @@ export async function parseFileSymbols(file) {
         ts.forEachChild(node, visit);
     };
     visit(source);
-    return out;
+    return { status: 'ok', symbols: out };
+}
+/**
+ * Compatibility wrapper over {@link parseFileSymbolsDiag}: same quiet
+ * contract as before (empty array on any non-ok status). New callers should
+ * prefer the diag version.
+ */
+export async function parseFileSymbols(file) {
+    const r = await parseFileSymbolsDiag(file);
+    return r.status === 'ok' ? r.symbols : [];
 }
-/** Outline: all declarations in a file (no source text). */
+/** Outline: all declarations in a file (no source text). Quiet on failure. */
 export async function astOutline(file) {
-    const symbols = await parseFileSymbols(file);
-    return symbols.map(({ text: _text, ...rest }) => rest);
+    const r = await parseFileSymbolsDiag(file);
+    if (r.status !== 'ok')
+        return [];
+    return r.symbols.map(({ text: _text, ...rest }) => rest);
 }
 /**
  * Find a named declaration and return its exact source text + range. When
  * several declarations share a name (overloads, a method and a function),
- * returns the first by source order.
+ * returns the first by source order. Quiet (null) on any non-ok status.
  */
 export async function findSymbol(file, name) {
-    const symbols = await parseFileSymbols(file);
-    return symbols.find((s) => s.name === name) ?? null;
+    const r = await parseFileSymbolsDiag(file);
+    if (r.status !== 'ok')
+        return null;
+    return r.symbols.find((s) => s.name === name) ?? null;
 }
 //# sourceMappingURL=engine.js.map

package/dist/cli/ast/engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../../src/cli/ast/engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../../src/cli/ast/engine.ts"],"names":[],"mappings":"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"}

package/dist/cli/ast/engine.test.js

@@ -0,0 +1,101 @@
+/**
+ * S2.1/S2.3 — unit tests for the loud, discriminated parse result of
+ * ast/engine (plan: .zelari/docs/piano-loud-tool-errors-ast-diag-readonly-shell.md §2).
+ */
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { vi, describe, it, expect } from 'vitest';
+import { parseFileSymbolsDiag, parseFileSymbols, astOutline, findSymbol, } from './engine.js';
+const SAMPLE = [
+    'export interface Shape { kind: string }',
+    'export class Circle implements Shape {',
+    '  kind = "circle";',
+    '  area(): number { return 1; }',
+    '}',
+    'export const area = (r: number): number => r * r;',
+    'const hidden = 1;',
+    '',
+].join('\n');
+describe('parseFileSymbolsDiag', () => {
+    it('resolves relative paths against the injected cwd and parses symbols', async () => {
+        const dir = await mkdtemp(path.join(tmpdir(), 'zelari-ast-'));
+        await writeFile(path.join(dir, 'sample.ts'), SAMPLE, 'utf8');
+        const r = await parseFileSymbolsDiag('sample.ts', dir);
+        expect(r.status).toBe('ok');
+        if (r.status !== 'ok')
+            return;
+        const names = r.symbols.map((s) => s.name);
+        expect(names).toContain('Shape');
+        expect(names).toContain('Circle');
+        expect(names).toContain('area'); // arrow function → kind 'function'
+        expect(names).toContain('hidden');
+        const circle = r.symbols.find((s) => s.name === 'Circle');
+        expect(circle.exported).toBe(true);
+        expect(circle.text).toContain('area(): number');
+    });
+    it('reports file-not-found with the ABSOLUTE resolved path', async () => {
+        const dir = await mkdtemp(path.join(tmpdir(), 'zelari-ast-'));
+        const r = await parseFileSymbolsDiag('missing.ts', dir);
+        expect(r.status).toBe('file-not-found');
+        if (r.status !== 'file-not-found')
+            return;
+        expect(r.resolvedPath).toBe(path.join(dir, 'missing.ts'));
+        expect(path.isAbsolute(r.resolvedPath)).toBe(true);
+        expect(r.recoverable).toBe(false);
+        expect(r.recommendedFallback).toBe('grep_content');
+    });
+    it('reports unsupported-extension with the extension it saw', async () => {
+        const dir = await mkdtemp(path.join(tmpdir(), 'zelari-ast-'));
+        await writeFile(path.join(dir, 'script.py'), 'def f(): pass\n', 'utf8');
+        const r = await parseFileSymbolsDiag('script.py', dir);
+        expect(r.status).toBe('unsupported-extension');
+        if (r.status !== 'unsupported-extension')
+            return;
+        expect(r.extension).toBe('.py');
+        expect(r.resolvedPath).toBe(path.join(dir, 'script.py'));
+    });
+    it('reports typescript-unavailable when the compiler API cannot load', async () => {
+        const dir = await mkdtemp(path.join(tmpdir(), 'zelari-ast-'));
+        await writeFile(path.join(dir, 'sample.ts'), SAMPLE, 'utf8');
+        // Fresh module graph where the dynamic `import('typescript')` rejects.
+        vi.resetModules();
+        vi.doMock('typescript', () => {
+            throw new Error('simulated: typescript not installed');
+        });
+        try {
+            const fresh = await import('./engine.js');
+            const r = await fresh.parseFileSymbolsDiag('sample.ts', dir);
+            expect(r.status).toBe('typescript-unavailable');
+            if (r.status !== 'typescript-unavailable')
+                return;
+            expect(r.recoverable).toBe(true);
+            expect(r.recommendedFallback).toBe('read_file');
+        }
+        finally {
+            vi.doUnmock('typescript');
+        }
+    });
+});
+describe('quiet compatibility wrappers', () => {
+    it('parseFileSymbols: [] on non-ok, symbols on ok', async () => {
+        const dir = await mkdtemp(path.join(tmpdir(), 'zelari-ast-'));
+        const file = path.join(dir, 'sample.ts');
+        await writeFile(file, SAMPLE, 'utf8');
+        // No cwd → resolves against process.cwd(); absolute path keeps it exact.
+        expect(await parseFileSymbols(path.join(dir, 'missing.ts'))).toEqual([]);
+        expect((await parseFileSymbols(file)).length).toBeGreaterThan(0);
+    });
+    it('astOutline drops text; findSymbol round-trips exact text', async () => {
+        const dir = await mkdtemp(path.join(tmpdir(), 'zelari-ast-'));
+        const file = path.join(dir, 'sample.ts');
+        await writeFile(file, SAMPLE, 'utf8');
+        const outline = await astOutline(file);
+        expect(outline.every((s) => !('text' in s))).toBe(true);
+        const sym = await findSymbol(file, 'Circle');
+        expect(sym?.text.startsWith('export class Circle')).toBe(true);
+        expect(await findSymbol(file, 'DoesNotExist')).toBeNull();
+        expect(await findSymbol(path.join(dir, 'missing.ts'), 'X')).toBeNull();
+    });
+});
+//# sourceMappingURL=engine.test.js.map

package/dist/cli/ast/engine.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.test.js","sourceRoot":"","sources":["../../../src/cli/ast/engine.test.ts"],"names":[],"mappings":"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"}

package/dist/cli/ast/tools.js

@@ -7,34 +7,85 @@
  * named declaration's EXACT source span + text, so the agent can target it and
  * edit reliably through the normal edit tools instead of fuzzy string matching.
  *
- * Read-only: neither tool writes. Both are best-effort (empty result when
- * TypeScript is unavailable or the file isn't TS/JS).
+ * Read-only: neither tool writes.
+ *
+ * Loud degradation (v0.10.0 "loud tool errors"): every empty outcome carries a
+ * discriminated `status` (file-not-found / typescript-unavailable /
+ * unsupported-extension / read-error / parse-error) plus machine-readable
+ * `resolvedPath` / `recoverable` / `recommendedFallback` fields. `found: false`
+ * is only ever reported when the file was read AND parsed successfully.
  */
 import { z } from 'zod';
 import { typedOk } from '@zelari/core/harness/tools/toolTypes';
-import { astOutline, findSymbol } from './engine.js';
+import { parseFileSymbolsDiag, } from './engine.js';
 /** Cap the returned declaration text so a huge class can't flood the context. */
 const MAX_TEXT_CHARS = 4000;
-export function createAstTools() {
+/**
+ * Build the loud, machine-readable payload shared by every non-ok status.
+ * `recommendedFallback` is a hint for the model — never auto-executed.
+ */
+function degradedPayload(r) {
+    return {
+        status: r.status,
+        resolvedPath: r.resolvedPath,
+        recoverable: r.recoverable,
+        recommendedFallback: r.recommendedFallback,
+    };
+}
+/** Human-facing note for each non-ok status — one cause, no "maybe" lists. */
+function degradedNote(r) {
+    switch (r.status) {
+        case 'file-not-found':
+            return `file not found — looked at ${r.resolvedPath} (relative paths resolve against the workspace root)`;
+        case 'typescript-unavailable':
+            return 'TypeScript compiler API unavailable — the "typescript" package could not be loaded. ' +
+                'AST tools need it; disable them with ZELARI_AST=0 or fall back to read_file/grep_content.';
+        case 'unsupported-extension':
+            return `unsupported file extension "${r.extension}" — ast_outline/find_symbol only parse TS/JS files (.ts/.tsx/.js/.jsx/.mjs/.cjs)`;
+        case 'read-error':
+            return `could not read ${r.resolvedPath}: ${r.message}`;
+        case 'parse-error':
+            return `TypeScript failed to parse ${r.resolvedPath}: ${r.message}`;
+    }
+}
+/**
+ * Create the AST tools bound to a workspace `root` (S2.0: the root is
+ * propagated by the registry, which already has it in scope). At call time
+ * relative paths resolve against `ctx.cwd` first (aligned with grep_content),
+ * falling back to `root`.
+ */
+export function createAstTools(root) {
     const outline = {
         name: 'ast_outline',
         description: 'Structural outline of a TS/JS file: every declaration (function, class, ' +
             'method, interface, type, enum, variable) with its line range and whether ' +
             "it's exported. Faster and more precise than reading the whole file to find " +
-            'where things are. TS/JS only.',
+            'where things are. Relative paths resolve against the working directory. ' +
+            'TS/JS only.',
         permissions: ['read'],
         inputSchema: z.object({
             path: z.string().min(1).describe('Path to the TS/JS file to outline.'),
         }),
-        execute: async (args) => {
+        execute: async (args, ctx) => {
             const { path: file } = args;
-            const symbols = await astOutline(file);
-            if (symbols.length === 0) {
-                return typedOk({ symbols: [], note: 'no declarations found (or not a TS/JS file / TypeScript unavailable)' });
+            const r = await parseFileSymbolsDiag(file, ctx?.cwd ?? root);
+            if (r.status !== 'ok') {
+                return typedOk({ symbols: [], note: degradedNote(r), ...degradedPayload(r) });
+            }
+            if (r.symbols.length === 0) {
+                // Genuinely empty file (or only ambient/implicit declarations):
+                // the file WAS read and parsed, so this is a true empty — say so.
+                return typedOk({
+                    status: 'ok',
+                    count: 0,
+                    symbols: [],
+                    note: 'file parsed successfully but contains no declarations',
+                });
             }
             return typedOk({
-                count: symbols.length,
-                symbols: symbols.map((s) => `${s.exported ? 'export ' : ''}${s.kind} ${s.name} (lines ${s.line}-${s.endLine})`),
+                status: 'ok',
+                count: r.symbols.length,
+                symbols: r.symbols.map((s) => `${s.exported ? 'export ' : ''}${s.kind} ${s.name} (lines ${s.line}-${s.endLine})`),
             });
         },
     };
@@ -43,21 +94,32 @@ export function createAstTools() {
         description: "Locate a named declaration in a TS/JS file and return its EXACT source " +
             'text and line range. Use this to grab a function/class/method verbatim so ' +
             'you can edit_file it reliably (node-accurate) instead of guessing the ' +
-            'surrounding text. TS/JS only.',
+            'surrounding text. Relative paths resolve against the working directory. ' +
+            'TS/JS only.',
         permissions: ['read'],
         inputSchema: z.object({
             path: z.string().min(1).describe('Path to the TS/JS file.'),
             name: z.string().min(1).describe('The declaration name to find (function/class/method/etc).'),
         }),
-        execute: async (args) => {
+        execute: async (args, ctx) => {
             const { path: file, name } = args;
-            const sym = await findSymbol(file, name);
+            const r = await parseFileSymbolsDiag(file, ctx?.cwd ?? root);
+            if (r.status !== 'ok') {
+                return typedOk({ found: false, note: degradedNote(r), ...degradedPayload(r) });
+            }
+            const sym = r.symbols.find((s) => s.name === name);
             if (!sym) {
-                return typedOk({ found: false, note: `no declaration named "${name}" found in ${file}` });
+                // File was read and parsed: a REAL not-found, safe to state.
+                return typedOk({
+                    found: false,
+                    status: 'ok',
+                    note: `no declaration named "${name}" found in ${r.symbols.length > 0 ? `${file} (declarations present: ${[...new Set(r.symbols.map((s) => s.name))].slice(0, 12).join(', ')})` : file}`,
+                });
             }
             const truncated = sym.text.length > MAX_TEXT_CHARS;
             return typedOk({
                 found: true,
+                status: 'ok',
                 kind: sym.kind,
                 exported: sym.exported,
                 line: sym.line,

package/dist/cli/ast/tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/cli/ast/tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/cli/ast/tools.ts"],"names":[],"mappings":"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"}

package/dist/cli/ast/tools.test.js

@@ -0,0 +1,124 @@
+/**
+ * S2.0/S2.2/S2.3 — tool-level tests: root propagation, ctx.cwd resolution,
+ * loud degraded notes with machine fields, and "found: false only when the
+ * file was actually read and parsed".
+ */
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { describe, it, expect } from 'vitest';
+import { createAstTools } from './tools.js';
+const SAMPLE = [
+    'export interface Shape { kind: string }',
+    'export class Circle implements Shape {',
+    '  kind = "circle";',
+    '  area(): number { return 1; }',
+    '}',
+    'export const area = (r: number): number => r * r;',
+    '',
+].join('\n');
+function fakeCtx(cwd) {
+    return {
+        signal: new AbortController().signal,
+        cwd,
+        audit: () => { },
+        sessionId: 'ast-tools-test',
+    };
+}
+async function run(tool, args, ctx) {
+    const r = await tool.execute(args, ctx);
+    if (!r.ok)
+        throw new Error(r.error);
+    return r.value;
+}
+function getTools(root) {
+    const tools = createAstTools(root);
+    const outline = tools.find((t) => t.name === 'ast_outline');
+    const findSym = tools.find((t) => t.name === 'find_symbol');
+    return { outline, findSym };
+}
+describe('ast_outline (loud degradation)', () => {
+    it('resolves a RELATIVE path against ctx.cwd', async () => {
+        const dir = await mkdtemp(path.join(tmpdir(), 'zelari-ast-'));
+        await writeFile(path.join(dir, 'sample.ts'), SAMPLE, 'utf8');
+        const { outline } = getTools('/nonexistent-root');
+        const v = await run(outline, { path: 'sample.ts' }, fakeCtx(dir));
+        expect(v.status).toBe('ok');
+        expect(v.count).toBeGreaterThan(0);
+        const symbols = v.symbols;
+        expect(symbols.some((s) => s.includes('export class Circle'))).toBe(true);
+    });
+    it('falls back to the factory root when ctx has no cwd (S2.0)', async () => {
+        const dir = await mkdtemp(path.join(tmpdir(), 'zelari-ast-'));
+        await writeFile(path.join(dir, 'sample.ts'), SAMPLE, 'utf8');
+        const { outline } = getTools(dir);
+        const ctxNoCwd = {
+            signal: new AbortController().signal,
+            audit: () => { },
+            sessionId: 'ast-tools-test',
+        };
+        const v = await run(outline, { path: 'sample.ts' }, ctxNoCwd);
+        expect(v.status).toBe('ok');
+        expect(v.count).toBeGreaterThan(0);
+    });
+    it('file-not-found names the absolute path it looked at', async () => {
+        const dir = await mkdtemp(path.join(tmpdir(), 'zelari-ast-'));
+        const { outline } = getTools('/nonexistent-root');
+        const v = await run(outline, { path: 'missing.ts' }, fakeCtx(dir));
+        expect(v.status).toBe('file-not-found');
+        expect(v.symbols).toEqual([]);
+        expect(v.note).toContain(path.join(dir, 'missing.ts'));
+        expect(v.recoverable).toBe(false);
+        expect(v.recommendedFallback).toBe('grep_content');
+    });
+    it('unsupported-extension reports the extension in the note', async () => {
+        const dir = await mkdtemp(path.join(tmpdir(), 'zelari-ast-'));
+        await writeFile(path.join(dir, 'script.py'), 'def f(): pass\n', 'utf8');
+        const { outline } = getTools('/nonexistent-root');
+        const v = await run(outline, { path: 'script.py' }, fakeCtx(dir));
+        expect(v.status).toBe('unsupported-extension');
+        expect(v.note).toContain('.py');
+    });
+    it('an empty-but-parsed file is a TRUE empty, not a degraded note', async () => {
+        const dir = await mkdtemp(path.join(tmpdir(), 'zelari-ast-'));
+        await writeFile(path.join(dir, 'empty.ts'), '\n', 'utf8');
+        const { outline } = getTools('/nonexistent-root');
+        const v = await run(outline, { path: 'empty.ts' }, fakeCtx(dir));
+        expect(v.status).toBe('ok');
+        expect(v.symbols).toEqual([]);
+        expect(v.note).toContain('no declarations');
+        // The old conflated three-causes note must be gone.
+        expect(String(v.note)).not.toContain('TypeScript unavailable');
+    });
+});
+describe('find_symbol (found:false only after a successful parse)', () => {
+    it('degraded file surfaces status, not a fake "no declaration named"', async () => {
+        const dir = await mkdtemp(path.join(tmpdir(), 'zelari-ast-'));
+        const { findSym } = getTools('/nonexistent-root');
+        const v = await run(findSym, { path: 'missing.ts', name: 'Circle' }, fakeCtx(dir));
+        expect(v.found).toBe(false);
+        expect(v.status).toBe('file-not-found');
+        expect(v.note).toContain(path.join(dir, 'missing.ts'));
+    });
+    it('symbol truly absent from a PARSED file → found:false, status ok, hint of present names', async () => {
+        const dir = await mkdtemp(path.join(tmpdir(), 'zelari-ast-'));
+        await writeFile(path.join(dir, 'sample.ts'), SAMPLE, 'utf8');
+        const { findSym } = getTools('/nonexistent-root');
+        const v = await run(findSym, { path: 'sample.ts', name: 'Sphere' }, fakeCtx(dir));
+        expect(v.found).toBe(false);
+        expect(v.status).toBe('ok');
+        expect(v.note).toContain('Sphere');
+        expect(v.note).toContain('Circle');
+    });
+    it('returns the exact declaration text for editing', async () => {
+        const dir = await mkdtemp(path.join(tmpdir(), 'zelari-ast-'));
+        await writeFile(path.join(dir, 'sample.ts'), SAMPLE, 'utf8');
+        const { findSym } = getTools('/nonexistent-root');
+        const v = await run(findSym, { path: 'sample.ts', name: 'Circle' }, fakeCtx(dir));
+        expect(v.found).toBe(true);
+        expect(v.kind).toBe('class');
+        expect(v.exported).toBe(true);
+        expect(String(v.text).startsWith('export class Circle')).toBe(true);
+    });
+});
+//# sourceMappingURL=tools.test.js.map

package/dist/cli/ast/tools.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.test.js","sourceRoot":"","sources":["../../../src/cli/ast/tools.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG5C,MAAM,MAAM,GAAG;IACb,yCAAyC;IACzC,wCAAwC;IACxC,oBAAoB;IACpB,gCAAgC;IAChC,GAAG;IACH,mDAAmD;IACnD,EAAE;CACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,SAAS,OAAO,CAAC,GAAW;IAC1B,OAAO;QACL,MAAM,EAAE,IAAI,eAAe,EAAE,CAAC,MAAM;QACpC,GAAG;QACH,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;QACf,SAAS,EAAE,gBAAgB;KAC5B,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,GAAG,CAAC,IAA6H,EAAE,IAAa,EAAE,GAAgB;IAC/K,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACxC,IAAI,CAAC,CAAC,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACpC,OAAO,CAAC,CAAC,KAAgC,CAAC;AAC5C,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,aAAa,CAAE,CAAC;IAC7D,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,aAAa,CAAE,CAAC;IAC7D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC9B,CAAC;AAED,QAAQ,CAAC,gCAAgC,EAAE,GAAG,EAAE;IAC9C,EAAE,CAAC,0CAA0C,EAAE,KAAK,IAAI,EAAE;QACxD,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC;QAC9D,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7D,MAAM,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC,mBAAmB,CAAC,CAAC;QAClD,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QAClE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;QACnC,MAAM,OAAO,GAAG,CAAC,CAAC,OAAmB,CAAC;QACtC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2DAA2D,EAAE,KAAK,IAAI,EAAE;QACzE,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC;QAC9D,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7D,MAAM,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QAClC,MAAM,QAAQ,GAAG;YACf,MAAM,EAAE,IAAI,eAAe,EAAE,CAAC,MAAM;YACpC,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;YACf,SAAS,EAAE,gBAAgB;SACF,CAAC;QAC5B,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,QAAQ,CAAC,CAAC;QAC9D,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qDAAqD,EAAE,KAAK,IAAI,EAAE;QACnE,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC;QAC9D,MAAM,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC,mBAAmB,CAAC,CAAC;QAClD,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QACnE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QACxC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC9B,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC;QACvD,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAClC,MAAM,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yDAAyD,EAAE,KAAK,IAAI,EAAE;QACvE,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC;QAC9D,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,EAAE,iBAAiB,EAAE,MAAM,CAAC,CAAC;QACxE,MAAM,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC,mBAAmB,CAAC,CAAC;QAClD,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QAClE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;QAC/C,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+DAA+D,EAAE,KAAK,IAAI,EAAE;QAC7E,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC;QAC9D,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAC1D,MAAM,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC,mBAAmB,CAAC,CAAC;QAClD,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QACjE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC9B,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;QAC5C,oDAAoD;QACpD,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,wBAAwB,CAAC,CAAC;IACjE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,yDAAyD,EAAE,GAAG,EAAE;IACvE,EAAE,CAAC,kEAAkE,EAAE,KAAK,IAAI,EAAE;QAChF,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC;QAC9D,MAAM,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC,mBAAmB,CAAC,CAAC;QAClD,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QACnF,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC5B,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QACxC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wFAAwF,EAAE,KAAK,IAAI,EAAE;QACtG,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC;QAC9D,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7D,MAAM,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC,mBAAmB,CAAC,CAAC;QAClD,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QAClF,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC5B,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACnC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,KAAK,IAAI,EAAE;QAC9D,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC;QAC9D,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7D,MAAM,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC,mBAAmB,CAAC,CAAC;QAClD,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QAClF,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3B,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7B,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,qBAAqB,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/cli/headless.js

@@ -27,6 +27,7 @@ object per line) or as plain text (just the assistant message text).
 
 Options:
   --task <text>              Task prompt (required)
+  --task-file <path>         Same as --task but read from a file (avoids Windows argv cap)
   --output json|plain        Output format (default: json)
   --mode kraken|council|zelari  Dispatch mode (default: kraken; agent=alias)
   --council                  Alias for --mode council
@@ -38,6 +39,7 @@ Options:
   --once                     Trigger mode: single cycle + lockfile (for cron/git hooks)
   --kraken-graph <goal>      Plan + execute a Kraken task graph instead of --task
                              (mutually exclusive with --task; ZELARI_KRAKEN_GRAPH=0 disables)
+  --kraken-graph-file <path> Same as --kraken-graph but read from a file
 
 Exit codes:
   0  completed
@@ -91,6 +93,25 @@ export function parseHeadlessFlags(argv) {
             task = argv[i + 1];
             i++;
         }
+        else if (arg === '--task-file') {
+            // File-backed variant of --task: the desktop spills long prompts to
+            // a temp file because Windows CreateProcess caps the command line at
+            // ~32KB (os error 206) and a long first message overflows it.
+            // Unreadable/empty file leaves `task` undefined so the validation
+            // below reports "requires --task" instead of a silent empty run.
+            const next = argv[i + 1];
+            if (next) {
+                try {
+                    const fromFile = readFileSync(next, 'utf-8');
+                    if (fromFile.trim())
+                        task = fromFile;
+                }
+                catch {
+                    // Missing/unreadable — validation below handles it.
+                }
+            }
+            i++;
+        }
         else if (arg === '--council') {
             councilFlag = true;
         }
@@ -222,6 +243,22 @@ export function parseHeadlessFlags(argv) {
             krakenGraph = argv[i + 1];
             i++;
         }
+        else if (arg === '--kraken-graph-file') {
+            // File-backed variant of --kraken-graph (same Windows argv cap as
+            // --task-file). Last flag wins, mirroring --task/--task-file.
+            const next = argv[i + 1];
+            if (next) {
+                try {
+                    const fromFile = readFileSync(next, 'utf-8');
+                    if (fromFile.trim())
+                        krakenGraph = fromFile;
+                }
+                catch {
+                    // Missing/unreadable — leave as-is.
+                }
+            }
+            i++;
+        }
         else if (arg === '--plan-only') {
             planOnly = true;
         }