xcoder-jarvis-agent 0.0.0-stage → 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neural Node Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,225 @@
-# Temporary Holding Version
+<!-- xcoder:version 3 | xcoder:task task-482677 | xcoder:updated 2026-11-05T03:54:36.038Z | xcoder:subtask code-st-729fd8 -->
+# @xcoder/jarvis-agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Jarvis is a ReAct agent that runs as a local CLI inside a developer's
+workspace. It reasons in a bounded loop, reads the workspace through a small
+allowlist of read-only tools, remembers short notes across sessions, and
+assembles its system prompt at runtime from versioned policy plus skill packs.
+
+It is built on `xcoder-dna` and follows the same workspace conventions: ESM,
+TypeScript, npm workspaces, vitest.
+
+## Install and run
+
+```bash
+npm run build -w @xcoder/jarvis-agent
+node packages/jarvis-agent/dist/program.js "summarise how the llm client picks a transport"
+```
+
+Once published, the binaries are `jarvis`.
+
+### Flags
+
+| Flag | Meaning | Default |
+|---|---|---|
+| `--skill NAME` | load only this skill pack (repeatable) | all discovered packs |
+| `--max-iterations N` | reasoning steps, clamped to 1..8 | 8 |
+| `--chat` | multi-turn mode: read turns from stdin until `exit`/`quit`/`bye` or EOF | off |
+| `--max-turns N` | chat turns, clamped to 1..200 | 50 |
+| `--no-memory` | skip loading and writing memory | memory on |
+| `--session ID` | session label | generated |
+| `--user ID` | memory scope label | OS user |
+| `--json` | emit one line of JSON | off |
+| `--help` | usage, exit 0 | |
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | answered |
+| 1 | error (bad flags, no task, model failure) |
+| 2 | iteration limit reached |
+| 3 | budget exceeded (in chat: also `--max-turns` reached) |
+| 4 | aborted by the kill switch |
+
+Code 2 is always a per-turn outcome in chat mode: a turn that hits its
+iteration limit is reported and the conversation continues.
+
+## Chat mode
+
+```bash
+node packages/jarvis-agent/dist/program.js --chat
+```
+
+Each line you type is one turn. The session ends when you type `exit`, `quit`
+or `bye` on a line by itself (case-insensitive, surrounding spaces ignored) or
+send EOF (Ctrl-D / Ctrl-Z). A line that merely *contains* one of those words —
+`exit now`, `how do I quit a program?` — is an ordinary turn.
+
+- **Continuity comes from memory, not from a growing transcript.** Every turn
+  re-reads the same memory session and re-assembles the prompt from it, so the
+  agent can recall earlier turns up to the memory window limit (~20 entries).
+  A very long chat therefore forgets its distant past; use `--session` to name
+  a conversation you want to return to.
+- **Each turn is one ordinary run.** It gets its own budget, its own `runId` and
+  exactly one provenance record, and the shared `session` label ties the turns
+  together. A turn that fails is reported and the loop continues.
+- **Blank lines are inert** — no model call, no memory write, no provenance.
+- **Lines over 8 KiB are rejected before the model sees them**, and only the
+  byte count is echoed, never the text.
+- **Ctrl-C and the kill switch still work.** `XCODER_JARVIS_KILL=1` or a
+  `.xcoder/jarvis/STOP` file is re-checked at every turn boundary and exits 4.
+- **`--json` emits one JSON object per executed turn** on stdout, so the stream
+  stays machine-readable; the session banner goes to stderr only.
+- **`--chat` plus a positional task is an error**, not a seed: a silently
+  discarded task looks like a model bug.
+
+A tool that needs confirmation prompts on stdin through the same reader the
+loop uses, so a prompt can never swallow a turn. Typing a terminator at a
+confirmation prompt denies that tool and ends the session at the next turn
+boundary — quitting is never blocked by a pending approval.
+
+## How it is built
+
+```
+argv -> runJarvisAgent
+          |-- discoverSkills -> skill packs (data, not instructions)
+          |-- assembleSystemPrompt -> trusted policy + delimited data blocks
+          |-- runReactLoop
+          |     |-- createLlmClient (xcoder-dna)
+          |     |-- parseDecision (zod)
+          |     `-- ToolRegistry (allowlist enforced in code)
+          |-- MemoryStore (scoped JSONL, redacted at write)
+          `-- writeProvenance (.xcoder/jarvis/runs/[runId].jsonl)
+```
+
+The ReAct loop is owned in-package rather than reusing
+`GenesisReActOrchestrator`, because that orchestrator's tool registry is
+internal and cannot be constrained to Jarvis's allowlist — reusing it would
+mean shipping an agent whose tool surface we do not control.
+
+### Tools
+
+Only six tools exist, and the list is enforced in code:
+
+| Tool | Risk | Notes |
+|---|---|---|
+| `read_file` | read | workspace-confined, symlink-resolved, secret-path denylist, 256 KiB cap |
+| `glob` | read | `*`, `**`, `?`, `{a,b}` only; 200 results |
+| `grep` | read | regex, 200 chars max; 100 matches; binary skipped |
+| `search_workspace` | read | path substring search |
+| `remember` | write | through `MemoryStore`, redacted before write |
+| `recall` | read | current scope's window |
+
+Deliberately absent: shell/exec, file write or delete, network fetch, git
+push, and any SQL. There is no irreversible tool in this build, so nothing
+needs human approval to run. The confirmation seam exists anyway and fails
+closed (deny) when stdin is not a TTY, so adding an irreversible tool later
+cannot silently skip approval.
+
+## Security model
+
+Jarvis is designed against the OWASP LLM Top 10. The controls that matter:
+
+**Prompt injection (LLM01).** The instruction region is a versioned constant,
+`POLICY`, in `src/jarvis/prompt/policy.ts`. Its sha256 is recorded in every
+run's provenance. Skill packs, memory entries and tool observations are
+treated as untrusted data: they are normalised (zero-width and bidi controls
+stripped), placed in `<untrusted-skill>` / `<untrusted-memory>` /
+`<untrusted-observation>` blocks, and any literal closing delimiter inside
+them is entity-escaped so it cannot end its own block.
+
+**Policy is enforced in code, not prose (PRM-09).** A prompt instruction is
+not a security boundary. The tool allowlist lives in `ToolRegistry.get()`,
+which returns `undefined` for any name that is not both registered and
+allowed. Iteration, token and wall-clock caps live in `RunBudget`. Model
+output is validated by a zod discriminated union before it can reach any
+tool.
+
+**Insecure output handling (LLM02).** Parsed decisions are the only thing
+that leaves `parseDecision`; raw model text is never passed to a shell, SQL,
+eval, HTML or a file path. There is no `eval` or `Function` constructor in the
+package.
+
+**Sensitive information (LLM06).** `read_file` refuses a denylist of
+secret-bearing paths (dotenv files, PEM/key files, ssh identities, npmrc,
+credential files). Anything read is run through `redactSecrets` before it
+enters the transcript, and memory values are redacted before they are
+written to disk.
+
+**Excessive agency (LLM08).** At most 8 iterations, one request in flight, a
+read-mostly tool surface, and a kill switch.
+
+**Cost and DoS (LLM10).** `RunBudget` caps input/output tokens, iterations and
+wall-clock time. A run over any cap returns exit 3 with no partial answer.
+
+### Kill switch
+
+Either signal aborts the run, checked before every LLM call and every tool
+dispatch, and failing closed:
+
+```bash
+export XCODER_JARVIS_KILL=1          # environment
+touch .xcoder/jarvis/STOP           # file in the workspace
+```
+
+An aborted run writes no memory entry and still records provenance with
+outcome `aborted`.
+
+### What is logged
+
+`.xcoder/jarvis/runs/[runId].jsonl` — one record per run, mode 0600 where the
+platform supports it. The schema holds identifiers, hashes and counts only:
+no prompt text, no model replies, no file contents, no tokens. The one
+free-text field is `error`, which is redacted and capped at 500 characters.
+Records older than 90 days are pruned off the hot path. Set `JARVIS_DEBUG=1`
+to print a stack trace to stderr on an unexpected error (never to the run
+log).
+
+## Memory
+
+Memory is append-only JSONL at
+`.xcoder/jarvis/memory/[workspaceId]/[userId].jsonl`, scoped by a hash of the
+resolved workspace path and a sanitised user label. Compaction is
+deterministic and never calls a model: it keeps the newest entry per key,
+then fills remaining capacity newest-first. A torn final line is dropped on
+read rather than throwing, so a killed process cannot corrupt the store.
+
+> **Accepted risk — scope is a label, not authentication.** `--user` selects
+> which memory file to use; it does not authenticate anyone. Anyone who can
+> run the CLI can read their own memory file, and anyone with filesystem
+> access can read the others. Real isolation requires separate OS accounts,
+> which is out of scope for a local CLI. Owner: platform team.
+
+> **File modes are best-effort on Windows.** The store requests mode 0700/0600
+> but Windows ignores POSIX permission bits; the protections there come from
+the user profile directory's ACLs.
+
+## Skill packs
+
+Packs are `SKILL.md` files with YAML frontmatter (`name`, `role`,
+`description`, `triggers`, `version`, `requires_tools`, `composes_with`).
+Discovery searches, first match wins: `$XCODER_SKILLS_DIR`, then
+`.xcoder/skills` in the workspace, then `~/.xcoder/skills` (seeded from the
+shipped packs on first run), then the bundled `xcoder-dna` packs.
+
+The frontmatter parser is a line-based YAML subset — no generic YAML
+dependency and no code execution. A pack that fails to parse is skipped and
+recorded in provenance; it never aborts a run. Unknown frontmatter keys are
+dropped rather than reaching the prompt.
+
+Because user-level packs are writable by the user, treat pack text as
+untrusted: review a pack before enabling it, exactly as you would review a
+script you were about to run.
+
+## Development
+
+```bash
+npm run typecheck -w @xcoder/jarvis-agent
+npm test                                  # full workspace suite
+npx vitest run packages/jarvis-agent      # just this package
+npm run check:boundaries                  # dependency rules
+```
+
+Tests live in `packages/*/src/**/*.test.ts` — the workspace vitest config only
+discovers that pattern.

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Public barrel for `@xcoder/jarvis-agent`.
+ *
+ * The CLI is the primary consumer, but everything the agent does is
+ * importable so a test (or a future orchestrator) can drive the loop, the
+ * memory store and the prompt assembler directly without spawning a process.
+ */
+export { JARVIS_AGENT_NAME, EXIT, runJarvisAgent, type JarvisDeps, type JarvisResult, } from "./jarvis/agent.js";
+export { MAX_ITERATIONS, runReactLoop, type LlmCompleter, type ReactLoopInput, type ReactLoopOutput, } from "./jarvis/react-loop.js";
+export { ActionDecision, FinalDecision, MAX_ARGS, MAX_ANSWER, MAX_THOUGHT, ReactDecision, ReactParseError, TOOL_NAME_RE, extractJsonObject, isValidToolName, parseDecision, type ReactDecision as ReactDecisionValue, } from "./jarvis/decision.js";
+export { BudgetExceeded, DEFAULT_CAPS, RunBudget, clampIterations, type BudgetCaps, type BudgetSnapshot } from "./jarvis/budget.js";
+export { ArgvError, MAX_TURNS_CEILING, MAX_TURNS_DEFAULT, USAGE, parseArgv, type JarvisRunRequest, } from "./jarvis/argv.js";
+export { MAX_LINE_BYTES, createArrayLineSource, createStdinLineSource, type LineResult, type LineSource, } from "./jarvis/chat/lines.js";
+export { TERMINATORS, isIgnorable, isTerminator, type TerminatorWord } from "./jarvis/chat/terminator.js";
+export { createChatConfirm, type ChatConfirm } from "./jarvis/chat/confirm.js";
+export { CHAT_DIRECTIVE } from "./jarvis/chat/prompt.js";
+export { runChatSession, runChatSessionDetailed, turnArgv, type ChatResult, type StopReason, } from "./jarvis/chat/session.js";
+export { DEFAULT_MAX_BYTES, DEFAULT_MAX_ENTRIES, DEFAULT_WINDOW_ENTRIES, MemoryStore, resolveUserId, workspaceScopeId, type MemoryEntry, type MemoryKind, type MemoryScope, type MemorySource, } from "./jarvis/memory/store.js";
+export { assembleSystemPrompt, wrapObservation, JARVIS_ROLE, UNTRUSTED_MEMORY_TAG, UNTRUSTED_OBSERVATION_TAG, UNTRUSTED_SKILL_TAG, type AssembledPrompt, type PromptProvenance, } from "./jarvis/prompt/assemble.js";
+export { POLICY_VERSION, POLICY, REFUSAL_RULES, renderPolicy } from "./jarvis/prompt/policy.js";
+export { DEFAULT_MAX_PACKS, DEFAULT_MAX_PACK_BYTES, DEFAULT_MAX_TOTAL_BYTES, discoverSkills, parseFrontmatter, type DiscoverSkillsOptions, type DiscoverSkillsResult, type SkillPack, type SkippedSkill, } from "./jarvis/prompt/skills.js";
+export { ALLOWED_TOOLS, DEFAULT_LIMITS, createToolRegistry, type AllowedToolName, type ToolContext, type ToolDescriptor, type ToolLimits, type ToolObservation, type ToolRegistry, } from "./jarvis/tools/registry.js";
+export { FS_TOOLS, globToRegExp, isSecretPath } from "./jarvis/tools/fs-tools.js";
+export { MEMORY_TOOLS } from "./jarvis/tools/memory-tools.js";
+export { RETENTION_DAYS, pruneProvenance, writeProvenance, type JarvisOutcome, type ProvenanceRecord, } from "./jarvis/telemetry/provenance.js";
+export { createConfirm, denyWhenNotTty, requireConfirmation, type ConfirmFn, type ConfirmRequest, type ToolRisk } from "./jarvis/util/confirm.js";
+export { createKillProbe, readKillState, stopFilePath, type KillState } from "./jarvis/util/kill.js";

package/dist/index.js

@@ -0,0 +1,28 @@
+// xcoder:version 2 | xcoder:task task-482677 | xcoder:updated 2026-11-05T03:49:01.166Z | xcoder:subtask code-st-729fd8
+/**
+ * Public barrel for `@xcoder/jarvis-agent`.
+ *
+ * The CLI is the primary consumer, but everything the agent does is
+ * importable so a test (or a future orchestrator) can drive the loop, the
+ * memory store and the prompt assembler directly without spawning a process.
+ */
+export { JARVIS_AGENT_NAME, EXIT, runJarvisAgent, } from "./jarvis/agent.js";
+export { MAX_ITERATIONS, runReactLoop, } from "./jarvis/react-loop.js";
+export { ActionDecision, FinalDecision, MAX_ARGS, MAX_ANSWER, MAX_THOUGHT, ReactDecision, ReactParseError, TOOL_NAME_RE, extractJsonObject, isValidToolName, parseDecision, } from "./jarvis/decision.js";
+export { BudgetExceeded, DEFAULT_CAPS, RunBudget, clampIterations } from "./jarvis/budget.js";
+export { ArgvError, MAX_TURNS_CEILING, MAX_TURNS_DEFAULT, USAGE, parseArgv, } from "./jarvis/argv.js";
+export { MAX_LINE_BYTES, createArrayLineSource, createStdinLineSource, } from "./jarvis/chat/lines.js";
+export { TERMINATORS, isIgnorable, isTerminator } from "./jarvis/chat/terminator.js";
+export { createChatConfirm } from "./jarvis/chat/confirm.js";
+export { CHAT_DIRECTIVE } from "./jarvis/chat/prompt.js";
+export { runChatSession, runChatSessionDetailed, turnArgv, } from "./jarvis/chat/session.js";
+export { DEFAULT_MAX_BYTES, DEFAULT_MAX_ENTRIES, DEFAULT_WINDOW_ENTRIES, MemoryStore, resolveUserId, workspaceScopeId, } from "./jarvis/memory/store.js";
+export { assembleSystemPrompt, wrapObservation, JARVIS_ROLE, UNTRUSTED_MEMORY_TAG, UNTRUSTED_OBSERVATION_TAG, UNTRUSTED_SKILL_TAG, } from "./jarvis/prompt/assemble.js";
+export { POLICY_VERSION, POLICY, REFUSAL_RULES, renderPolicy } from "./jarvis/prompt/policy.js";
+export { DEFAULT_MAX_PACKS, DEFAULT_MAX_PACK_BYTES, DEFAULT_MAX_TOTAL_BYTES, discoverSkills, parseFrontmatter, } from "./jarvis/prompt/skills.js";
+export { ALLOWED_TOOLS, DEFAULT_LIMITS, createToolRegistry, } from "./jarvis/tools/registry.js";
+export { FS_TOOLS, globToRegExp, isSecretPath } from "./jarvis/tools/fs-tools.js";
+export { MEMORY_TOOLS } from "./jarvis/tools/memory-tools.js";
+export { RETENTION_DAYS, pruneProvenance, writeProvenance, } from "./jarvis/telemetry/provenance.js";
+export { createConfirm, denyWhenNotTty, requireConfirmation } from "./jarvis/util/confirm.js";
+export { createKillProbe, readKillState, stopFilePath } from "./jarvis/util/kill.js";

package/dist/jarvis/agent.d.ts

@@ -0,0 +1,57 @@
+import type { LineSource } from "./chat/lines.js";
+import { type LlmCompleter } from "./react-loop.js";
+import { type JarvisOutcome } from "./telemetry/provenance.js";
+import { type ConfirmFn } from "./util/confirm.js";
+import { type ToolDescriptor } from "./tools/registry.js";
+export declare const JARVIS_AGENT_NAME: "jarvis-agent";
+/** Exit codes are the CLI contract (design §2.3, tradeoff T7). */
+export declare const EXIT: {
+    readonly answered: 0;
+    readonly error: 1;
+    readonly iteration_limit: 2;
+    readonly budget_exceeded: 3;
+    readonly aborted: 4;
+};
+export interface JarvisDeps {
+    createClient?: () => LlmCompleter;
+    now?: () => Date;
+    workspaceRoot?: string;
+    memoryRoot?: string;
+    runLogRoot?: string;
+    tools?: readonly ToolDescriptor<any>[];
+    confirm?: ConfirmFn;
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+    /** Injected for tests, so skill discovery never reads the real home dir. */
+    env?: NodeJS.ProcessEnv;
+    /** Chat seam: replaces process.stdin. Production builds a LineSource from it. */
+    stdin?: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    /** Chat seam: an explicit LineSource, so loop tests need no process or TTY. */
+    lines?: LineSource;
+    /** Chat seam: overrides TTY detection for the confirmation gate. */
+    isInteractive?: boolean;
+    /** Set by the chat loop: record this turn's user line before the run (T4). */
+    chatTurn?: boolean;
+}
+export interface JarvisResult {
+    outcome: JarvisOutcome;
+    answer?: string;
+    exitCode: number;
+    iterations: number;
+    runId: string;
+    session: string;
+    skills: string[];
+    provenancePath?: string;
+    error?: string;
+}
+/**
+ * Runs one Jarvis invocation and returns a process exit code.
+ *
+ * Never throws for expected conditions: a bad flag, a missing key, a model
+ * failure, a tripped kill switch and an exhausted budget all become a number
+ * plus a redacted message (T7). Provenance is written in a `finally` so an
+ * aborted run still leaves an audit record.
+ */
+export declare function runJarvisAgent(argv: readonly string[], deps?: JarvisDeps): Promise<number>;

package/dist/jarvis/agent.js

@@ -0,0 +1,306 @@
+// xcoder:version 13 | xcoder:task task-482677 | xcoder:updated 2026-11-05T03:48:53.483Z | xcoder:subtask code-st-729fd8
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { createLlmClient, requestScope, shortId, XCODER_VERSION } from "xcoder-dna";
+import { ArgvError, parseArgv, USAGE } from "./argv.js";
+import { BudgetExceeded, clampIterations, DEFAULT_CAPS, RunBudget } from "./budget.js";
+import { CHAT_DIRECTIVE } from "./chat/prompt.js";
+import { runChatSession } from "./chat/session.js";
+import { MemoryStore, resolveUserId, workspaceScopeId } from "./memory/store.js";
+import { assembleSystemPrompt } from "./prompt/assemble.js";
+import { POLICY_VERSION, renderPolicy } from "./prompt/policy.js";
+import { discoverSkills } from "./prompt/skills.js";
+import { MAX_ITERATIONS, runReactLoop } from "./react-loop.js";
+import { writeProvenance, pruneProvenance } from "./telemetry/provenance.js";
+import { createConfirm } from "./util/confirm.js";
+import { sha256 } from "./util/text.js";
+import { createKillProbe, readKillState } from "./util/kill.js";
+import { DEFAULT_LIMITS, createToolRegistry } from "./tools/registry.js";
+import { FS_TOOLS } from "./tools/fs-tools.js";
+import { MEMORY_TOOLS } from "./tools/memory-tools.js";
+export const JARVIS_AGENT_NAME = "jarvis-agent";
+/** Exit codes are the CLI contract (design §2.3, tradeoff T7). */
+export const EXIT = {
+    answered: 0,
+    error: 1,
+    iteration_limit: 2,
+    budget_exceeded: 3,
+    aborted: 4,
+};
+function emit(stream, text) {
+    try {
+        stream.write(text);
+    }
+    catch {
+        /* a closed stream must not fail the run */
+    }
+}
+/** Resolve a scope id from the real path, falling back to the raw path. */
+async function scopeIdFor(workspaceRoot) {
+    try {
+        return workspaceScopeId(await fsp.realpath(workspaceRoot));
+    }
+    catch {
+        return workspaceScopeId(path.resolve(workspaceRoot));
+    }
+}
+/**
+ * Runs one Jarvis invocation and returns a process exit code.
+ *
+ * Never throws for expected conditions: a bad flag, a missing key, a model
+ * failure, a tripped kill switch and an exhausted budget all become a number
+ * plus a redacted message (T7). Provenance is written in a `finally` so an
+ * aborted run still leaves an audit record.
+ */
+export async function runJarvisAgent(argv, deps = {}) {
+    const stdout = deps.stdout ?? process.stdout;
+    const stderr = deps.stderr ?? process.stderr;
+    const now = deps.now ?? (() => new Date());
+    let request;
+    try {
+        request = parseArgv(argv);
+    }
+    catch (err) {
+        const message = err instanceof ArgvError ? err.message : "invalid arguments";
+        emit(stderr, `jarvis: ${message}\n\n${USAGE}\n`);
+        return EXIT.error;
+    }
+    if (request.help) {
+        emit(stdout, `${USAGE}\n`);
+        return EXIT.answered;
+    }
+    // Chat runs many turns over one stdin/stdout pair; it owns its own loop.
+    if (request.chat) {
+        return await runChatSession(request, deps);
+    }
+    if (request.task.length === 0) {
+        emit(stderr, `jarvis: no task given\n\n${USAGE}\n`);
+        return EXIT.error;
+    }
+    const workspaceRoot = path.resolve(deps.workspaceRoot ?? process.cwd());
+    const memoryRoot = deps.memoryRoot ?? path.join(workspaceRoot, ".xcoder", "jarvis", "memory");
+    const runLogRoot = deps.runLogRoot ?? path.join(workspaceRoot, ".xcoder", "jarvis", "runs");
+    const env = deps.env ?? process.env;
+    const session = request.session ?? shortId("jarvis");
+    const runId = shortId("run");
+    const userId = resolveUserId(request.user);
+    const workspaceId = await scopeIdFor(workspaceRoot);
+    const kill = createKillProbe(workspaceRoot);
+    const confirm = deps.confirm ?? createConfirm({ stdin: process.stdin, stdout: stderr });
+    const memory = new MemoryStore({
+        rootDir: memoryRoot,
+        scope: { workspaceId, userId },
+        now,
+    });
+    const toolContext = {
+        workspaceRoot,
+        memory,
+        session,
+        confirm,
+        limits: DEFAULT_LIMITS,
+    };
+    const tools = deps.tools ?? [...FS_TOOLS, ...MEMORY_TOOLS];
+    const registry = createToolRegistry({ tools });
+    // Fail closed before doing any work at all.
+    const initialKill = readKillState(workspaceRoot);
+    if (initialKill.killed) {
+        const result = {
+            outcome: "aborted",
+            exitCode: EXIT.aborted,
+            iterations: 0,
+            runId,
+            session,
+            skills: [],
+            error: `kill switch tripped (${initialKill.reason})`,
+        };
+        emit(stderr, `jarvis: aborted — kill switch tripped (${initialKill.reason})\n`);
+        await safeWriteProvenance(runLogRoot, result, {
+            workspaceId,
+            userId,
+            policyVersion: POLICY_VERSION,
+            policySha256: sha256(renderPolicy(registry.describeForPrompt())),
+            skills: [],
+            skippedSkills: [],
+            toolAllowlist: registry.allowlist(),
+            toolsUsed: [],
+            memoryWrites: 0,
+            redactions: 0,
+            now,
+        });
+        return EXIT.aborted;
+    }
+    // ---- skills ----
+    const discovered = await discoverSkills({
+        workspaceRoot,
+        allow: request.skills.length > 0 ? request.skills : undefined,
+        env,
+    });
+    if (request.skills.length > 0 && discovered.packs.length === 0) {
+        emit(stderr, `jarvis: none of the requested skill packs were found (${request.skills.join(", ")})\n`);
+        return EXIT.error;
+    }
+    // In chat mode the user's line is recorded BEFORE the turn runs, so a failed
+    // turn still leaves a trace (tradeoff T4). It is stored as user-sourced data.
+    if (deps.chatTurn && request.memory) {
+        try {
+            await memory.append({
+                session,
+                kind: "task",
+                value: request.task,
+                source: "user",
+            });
+        }
+        catch {
+            /* a read-only memory dir must not fail the turn */
+        }
+    }
+    // ---- memory window (re-read every turn: this IS the continuity mechanism) ----
+    let window = [];
+    if (request.memory) {
+        try {
+            window = await memory.window();
+        }
+        catch {
+            window = [];
+        }
+    }
+    // ---- prompt ----
+    // The directive is the TRUSTED instruction section (PRM-02). A chat turn must
+    // never splice the user's text there, so it passes a constant; user text only
+    // ever arrives as transcript DATA (AC15).
+    const directive = deps.chatTurn ? CHAT_DIRECTIVE : request.task;
+    const assembled = assembleSystemPrompt({
+        agentName: JARVIS_AGENT_NAME,
+        directive,
+        skills: discovered.packs,
+        window,
+        toolAllowlist: registry.allowlist(),
+        toolManifest: registry.describeForPrompt(),
+        skippedSkills: discovered.skipped,
+        now: now(),
+    });
+    // ---- client ----
+    let client;
+    try {
+        client = deps.createClient ? deps.createClient() : createLlmClient("orchestrator");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message.slice(0, 300) : "model client could not start";
+        emit(stderr, `jarvis: ${message}\n`);
+        return EXIT.error;
+    }
+    const budget = new RunBudget({ ...DEFAULT_CAPS, maxIterations: clampIterations(request.maxIterations, MAX_ITERATIONS) }, now);
+    const toolsUsed = [];
+    let outcome = "error";
+    let answer;
+    let iterations = 0;
+    let errorMessage;
+    let memoryWrites = 0;
+    try {
+        // Install a recordUsage sink so dna-side usage events reach provenance.
+        const loopResult = await requestScope.run({ recordUsage: () => undefined }, () => runReactLoop({
+            task: request.task,
+            systemPrompt: assembled,
+            client,
+            registry,
+            toolContext,
+            maxIterations: clampIterations(request.maxIterations, MAX_ITERATIONS),
+            budget,
+            isKilled: kill,
+            onToolUsed: (name, observation) => {
+                toolsUsed.push({ name, ok: observation.ok, bytes: observation.bytes });
+                if (name === "remember" && observation.ok)
+                    memoryWrites += 1;
+            },
+        }));
+        outcome = loopResult.outcome;
+        answer = loopResult.answer;
+        iterations = loopResult.iterations;
+        errorMessage = loopResult.error;
+    }
+    catch (err) {
+        if (err instanceof BudgetExceeded) {
+            outcome = "budget_exceeded";
+            errorMessage = err.message;
+        }
+        else {
+            outcome = "error";
+            errorMessage = err instanceof Error ? err.message.slice(0, 300) : "run failed";
+            if (process.env["JARVIS_DEBUG"] === "1" && err instanceof Error && err.stack) {
+                emit(stderr, `${err.stack}\n`);
+            }
+        }
+    }
+    const exitCode = EXIT[outcome];
+    const result = {
+        outcome,
+        ...(answer !== undefined ? { answer } : {}),
+        exitCode,
+        iterations,
+        runId,
+        session,
+        skills: discovered.packs.map((p) => p.name),
+        ...(errorMessage !== undefined ? { error: errorMessage } : {}),
+    };
+    const usage = budget.snapshot();
+    const provenancePath = await safeWriteProvenance(runLogRoot, result, {
+        workspaceId,
+        userId,
+        policyVersion: assembled.provenance.policyVersion,
+        policySha256: assembled.provenance.policySha256,
+        skills: assembled.provenance.skills.map((s) => ({ name: s.name, sha256: s.sha256 })),
+        skippedSkills: assembled.provenance.skippedSkills,
+        toolAllowlist: registry.allowlist(),
+        toolsUsed,
+        memoryWrites,
+        redactions: memory.redactions(),
+        usage: { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens },
+        outcome,
+        iterations,
+        error: errorMessage,
+        now,
+    });
+    // Retention pruning is housekeeping: off the hot path, never fatal.
+    void pruneProvenance(runLogRoot, now()).catch(() => undefined);
+    // ---- report ----
+    if (request.json) {
+        emit(stdout, JSON.stringify({ ...result, provenancePath }) + "\n");
+    }
+    else if (outcome === "answered") {
+        emit(stdout, `${answer ?? ""}\n`);
+    }
+    else {
+        emit(stderr, `jarvis: ${outcome}${errorMessage ? ` — ${errorMessage}` : ""}\n`);
+    }
+    return exitCode;
+}
+async function safeWriteProvenance(dir, result, extra) {
+    try {
+        return await writeProvenance(dir, {
+            v: 1,
+            runId: result.runId,
+            ts: extra.now().toISOString(),
+            agent: JARVIS_AGENT_NAME,
+            version: XCODER_VERSION,
+            workspaceId: extra.workspaceId,
+            userId: extra.userId,
+            session: result.session,
+            policyVersion: extra.policyVersion,
+            policySha256: extra.policySha256,
+            skills: extra.skills,
+            skippedSkills: extra.skippedSkills,
+            toolAllowlist: extra.toolAllowlist,
+            toolsUsed: extra.toolsUsed,
+            iterations: extra.iterations ?? result.iterations,
+            outcome: extra.outcome ?? result.outcome,
+            usage: extra.usage ?? { inputTokens: 0, outputTokens: 0 },
+            memoryWrites: extra.memoryWrites,
+            redactions: extra.redactions,
+            ...(extra.error !== undefined ? { error: extra.error } : {}),
+        });
+    }
+    catch {
+        // A read-only workspace must not turn a good answer into a failure.
+        return undefined;
+    }
+}