human-to-code 0.1.11 → 0.1.13

package/Readme.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/banner.svg" alt="human-to-code — reviewed intent to validated code patches" width="100%">
+  <img src="assets/banner.svg" alt="human-to-code — write intent in plain language, compile it to real code" width="100%">
 </p>
 
 <p align="center">
@@ -9,7 +9,12 @@
   <a href="CONTRIBUTING.md"><img alt="contributions welcome" src="https://img.shields.io/badge/contributions-welcome-brightgreen"></a>
 </p>
 
-`human-to-code` is a security-constrained compiler agent for turning a reviewed natural-language change request into a grounded, structured patch. It statically analyzes the host project, requires a versioned JSON change contract, limits what an LLM can see and request, validates the candidate in an isolated snapshot, and keeps application as a separate explicit action.
+`human-to-code` turns natural-language change requests — whole `.human` files or inline `@human` markers — into code. It has two entry points:
+
+- **Direct converter** (the default `npx human-to-code .`): discovers each request and turns it straight into code, with a receipt and confirmation. Fast, works with small local models, and writes to the working tree **without** a change contract or sandbox validation.
+- **Guided pipeline** (`human-to-code guided`): the security-constrained, production-architecture path. It statically analyzes the host project, binds the request to a versioned JSON change contract, limits what an LLM can see and request, validates the candidate in an isolated snapshot, and keeps application as a separate explicit action.
+
+The guided pipeline is shown below:
 
 ```text
 static project analysis
@@ -25,12 +30,12 @@ unchanged baseline vs candidate in a strong sandbox
 reviewed diff ── explicit apply only after VERIFIED ── exact rollback artifact
 ```
 
-This is not a universal deterministic source-to-source compiler. The LLM writes framework-specific patch operations, but it does not choose its own scope, validation commands, credentials, documentation sources, or acceptance criteria.
+This is not a universal deterministic source-to-source compiler. The LLM writes framework-specific patch operations, but it does not choose its own scope, validation commands, credentials, documentation sources, or acceptance criteria. The `.strict.human.json` change contract, `VERIFIED` status, and `apply`/`rollback` machinery all belong to the guided pipeline — the default direct converter does not use them.
 
 ## Release status
 
 > [!WARNING]
-> Version `0.1.0` is a production-architecture **preview**, not a certified production release.
+> This `0.1.x` release is a production-architecture **preview**, not a certified production release.
 
 The shipped React, NestJS, FastAPI, and Rust profiles are currently `preview` (CRA is `legacy`), and no provider/model certification benchmark entry is enabled by the CLI. Therefore generated runs in this release cannot honestly become `VERIFIED`; even a clean strong-sandbox validation remains `INCONCLUSIVE`, and `apply` (therefore `rollback`) stays unreachable through a normal preview CLI run. This fail-closed behavior is intentional.
 
@@ -46,26 +51,32 @@ The published-package entry point is:
 npx human-to-code .
 ```
 
-The command is a guided workflow, not an instruction to edit the current directory immediately:
+By default this runs the **direct converter**, not an instruction to rewrite the whole directory. It:
+
+1. Loads config and scans the project for `.human` files and inline `@human` markers, without importing application modules or executing project configuration.
+2. Prints a receipt (language, provider, model, and the exact worklist) and asks for confirmation. Nothing is written until you confirm — or pass `-y`/`--yes`. If no request is found it returns `NEEDS_INPUT`.
+3. On confirmation, converts each item with one model completion per unit and writes the result: a whole `.human` file becomes a sibling source file; an inline `@human` marker is replaced in place. Each item is independent — a failing one is skipped with a reason rather than aborting the rest.
 
-1. It statically analyzes the repository without importing application modules or executing project configuration.
-2. It finds one `.human` change request. If none or several are found, it returns `NEEDS_INPUT`.
-3. On the first run, it writes a review draft named `foo.strict.human.json` next to `foo.human` and exits with code `3`.
-4. You review the target workspaces and symbols, allowed paths and operations, acceptance criteria, risks, and unresolved questions. A material unresolved question blocks generation.
-5. Before any provider request, it scans first-party repository files—including ignored/untracked fixtures and logs—for credential-like content. A finding returns `SECURITY_BLOCKED`; an incomplete scan fails closed.
-6. On the next run, it builds an outbound context manifest, requests a structured patch from the selected provider, and validates an isolated baseline and candidate.
-7. It prints a diff and report. It never applies the patch as part of the guided command.
+The direct converter writes code straight to the working tree. It does **not** create a `.strict.human.json` change contract, run sandbox validation, produce a `VERIFIED` run, or perform the guided pipeline's repository-wide secret scan — only the indexed declarations it attaches to an inline prompt as context are secret-scanned (a finding is `SECURITY_BLOCKED`). For the reviewed contract → grounding → sandbox-validation lifecycle — where the `.strict.human.json` contract and the `VERIFIED`/`apply`/`rollback` machinery live — use `human-to-code guided` (see [The reviewed change contract](#the-reviewed-change-contract) and the [CLI](#cli) table).
 
-No configured provider is needed for the first analysis/draft pass. A no-file/default run selects loopback-local Ollama with `qwen2.5-coder:7b`, so a fresh `npx human-to-code .` never transmits code remotely by default. The model must already be installed; the tool never pulls it implicitly. To use another local model, OpenAI, or Ollama Cloud, create and edit a config (the command never overwrites one):
+No configured provider is needed to scan and preview. A default run selects loopback-local Ollama with `qwen2.5-coder:7b`, so a fresh `npx human-to-code .` never transmits code remotely by default. The model must already be installed; the tool never pulls it implicitly. To use another local model, OpenAI, or Ollama Cloud, create and edit a config (the command never overwrites one):
 
 ```bash
 npx human-to-code --init .
 # Edit human-to-code.config.json: select OpenAI, local Ollama, or Ollama Cloud.
 ```
 
-Or pass `--provider ollama --model <installed-model>` on every guided local-Ollama run. Remote OpenAI/Ollama Cloud generation needs a config because `privacy.remoteProviderConsent` defaults to `false` and has no consent-enabling CLI flag.
+Remote OpenAI/Ollama Cloud generation needs a config because `privacy.remoteProviderConsent` defaults to `false` and has no consent-enabling CLI flag.
 
-For example:
+Direct-converter example (inline marker converted in place):
+
+```bash
+printf '// @human add a function named health that returns { status: 200 }\n' > health.ts
+npx human-to-code . --yes --model qwen2.5-coder:7b
+# health.ts now contains the generated function in place of the marker.
+```
+
+Guided-pipeline example (reviewed contract, no code written until VERIFIED):
 
 ```bash
 cat > add-health-route.human <<'EOF'
@@ -73,9 +84,8 @@ Add a health endpoint using the existing routing, response, authentication,
 logging, and test conventions. It must not expose secrets or tenant data.
 EOF
 
-npx human-to-code . --provider ollama --model qwen2.5-coder:14b
-# Review add-health-route.strict.human.json, resolve REVIEW-1, then rerun:
-npx human-to-code . --file add-health-route.human --provider ollama --model qwen2.5-coder:14b
+npx human-to-code guided . --provider ollama --model qwen2.5-coder:14b
+# Review add-health-route.strict.human.json, resolve REVIEW-1, then rerun the same command.
 ```
 
 From a source checkout:
@@ -91,51 +101,69 @@ Node.js 24 or newer is required.
 
 ## Generation engines
 
-The default `npx human-to-code .` flow discovers work (whole `.human` files and
+The direct `npx human-to-code .` flow discovers work (whole `.human` files and
 inline `@human` markers), prints a receipt, and — after you confirm — converts
-it with a **LangChain/LangGraph deep agent** (the [`deepagents`](https://docs.langchain.com/oss/javascript/deepagents/overview)
-harness). The agent runs with the four deep-agent pillars:
-
-- **Planning** — the built-in `write_todos` tool decomposes the run into an
-  ordered, status-tracked plan.
-- **File System** — a project-rooted `FilesystemBackend` gives the agent
-  `ls`/`glob`/`grep`/`read_file`/`write_file`/`edit_file` over the working tree.
-  Writes to VCS, dependency, config, and secret paths are denied by filesystem
-  permissions; the agent cannot escape the project root.
-- **Sub Agents** — a `planner`, `implementer`, and `reviewer` subagent are
-  reachable through the built-in `task` tool for isolated subtasks.
-- **Prompts** — a task-specific system prompt for the main agent and one per
-  subagent role.
-
-The model, not the host, drives scope, file edits, and delegation here. This is
-an autonomous engine: it edits files directly and does **not** produce
-`VERIFIED` runs, hash-verified patches, or run-store records. For the reviewed,
-sandbox-validated pipeline use `human-to-code guided`.
-
-While it runs, the agent streams live progress to the terminal: an animated
-elapsed-time spinner plus a line for the plan and each tool call
-(`→ read_file …`, `→ edit_file …`, `✓ <done step>`), so a long run is never a
-blank screen.
-
-The provider is bound through the OpenAI-compatible chat client. Ollama is
-reached at its `/v1` endpoint (the deep agent's structured tool messages are not
-supported by the native `/api/chat` surface), so the model you pass must be
-tool-calling capable. Small models that cannot emit valid tool calls fail with a
-tool-call/XML parse error; the CLI detects this and suggests a larger model or
-`--simple`. In practice a ~7B-or-larger coder model is the floor; sub-2B models
-do not work.
-
-Unlike the rest of the tool, this engine adds runtime dependencies
-(`deepagents`, `langchain`, `@langchain/core`, `@langchain/openai`,
-`@langchain/ollama`). Pass `--simple` to convert with the built-in-only
-generator instead, which keeps the run's supply-chain surface at Node itself.
+it. Two engines are available.
+
+### Default: fast deterministic engine
+
+The host does the orchestration; the model only writes code. For each unit the
+host issues **one plain model completion** (no tool calls) and applies the
+result by exact marker range. This is fast and works with small models — a 1.5B
+coder model converts a four-marker file in ~4 seconds. Because it needs no
+tool-calling, models that can only do plain text generation work fine.
+
+- **Per-marker isolation** — each `@human` marker is generated and applied
+  independently. If one marker's output is bad (e.g. a small model redeclares an
+  existing symbol), that marker is retried, then skipped with a printed reason;
+  the other markers still convert. One failure never aborts the run.
+- **FileMemory** — declarations already in the file are shown to the model as
+  read-only context (with few-shot examples) so it reuses rather than
+  re-declares them.
+- **Clear, stable output** — a single truncated status line per marker
+  (`✓ app.ts (inline @human, line 12)` / `⊘ skipped … : <reason>`), plus an
+  in-place elapsed spinner while a completion is in flight.
+
+This engine cannot produce `VERIFIED` runs; for the reviewed, sandbox-validated
+pipeline use `human-to-code guided`.
+
+### `--agent`: LangGraph deep agent
+
+`--agent` runs a LangChain/LangGraph agent with an explicit coding-tool surface:
+`Task`, `Bash`, `Glob`, `Grep`,
+`LS`, `ExitPlanMode`, `Read`, `Edit`, `MultiEdit`, `Write`, `NotebookEdit`,
+`WebFetch`, `TodoWrite`, `WebSearch`, `BashOutput`, and `KillBash`. File tools
+are project-confined, reads are required before edits, protected paths are
+denied, multi-edits are atomic, shell output is bounded, and secret-bearing
+environment variables are removed from commands.
+
+In an interactive terminal, agent mode uses a two-column dashboard: the current
+todo list stays on the left while tool calls, command output, and git-style
+green `+` / red `-` file changes stream on the right. Non-TTY and `--json`
+usage remains line-oriented and machine-readable.
+
+The agent prompt includes concrete JSON tool-call examples intended to help
+very small models, including 0.8B-class models. Model size is not treated as a
+capability guarantee: the model must reliably support structured tool calling.
+If a model repeats the same call four times, claims completion without changing
+every worklist item, or reaches the bounded graph step limit, the run stops with
+a concise incomplete result instead of continuing to the framework recursion
+error. When the host observes that every discovered item is implemented, it
+stops the graph even if the model forgets to provide a final response.
+
+The engine is reached through the OpenAI-compatible chat client (Ollama via its
+`/v1` endpoint). Its `Bash` tool executes development commands on the host from
+the project root; it is bounded and guarded but is not a strong sandbox. Use
+the guided pipeline when hash-bound patches and container validation are
+required. Agent mode pulls the runtime dependencies `langchain`,
+`@langchain/core`, and `@langchain/openai`.
 
 ```bash
-# Deep agent (default), with a tool-calling local model:
-npx human-to-code . --yes --model qwen2.5-coder:7b
+# Fast deterministic engine (default) — works with small models:
+npx human-to-code . --yes --model qwen2.5-coder:1.5b
 
-# Deterministic, dependency-free generator:
-npx human-to-code . --yes --simple
+# Agent dashboard — needs reliable JSON tool calling:
+npx human-to-code . --yes --agent --model qwen2.5-coder:7b
 ```
 
 ## The reviewed change contract
@@ -156,8 +184,8 @@ The draft is deliberately conservative. Do not remove its review question until
 
 | Command | Behavior |
 | --- | --- |
-| `human-to-code [root]` | Default direct flow: discover `.human` files and `@human` markers, show a receipt, and on confirmation convert them with the **deep-agent engine** (see below). `npx human-to-code .` is the normal entry point. |
-| `human-to-code [root] --simple` | Same direct flow using the deterministic, dependency-free generator instead of the deep agent. |
+| `human-to-code [root]` | Default direct flow: discover `.human` files and `@human` markers, show a receipt, and on confirmation convert them with the **fast deterministic engine** (one plain model completion per marker; see below). `npx human-to-code .` is the normal entry point. |
+| `human-to-code [root] --agent` | Same direct flow using the tool-rich **LangGraph agent dashboard** (todos, filesystem, shell, diffs, and subagents). Needs reliable structured tool calling; model size alone is not a capability guarantee. |
 | `human-to-code guided [root]` | Reviewed contract → grounding → sandbox-validation lifecycle. The only path that can reach `VERIFIED`. |
 | `human-to-code analyze [root] [--json]` | Produce a deterministic multi-workspace project profile and diagnostics. `SUPPORTED` means statically recognized, not certified. |
 | `human-to-code plan <file.human> [--root <root>]` | Write a review-blocked `ChangeContractV1` draft. |
@@ -415,7 +443,7 @@ Captured stdout and stderr are scanned before report persistence. If either cont
 
 No strong sandbox means no project command runs and the result is `INCONCLUSIVE`. Baseline failures, fail-then-pass flakiness, pending manual checks, unavailable toolchains/services, or mixed ecosystems without an explicit multi-toolchain image also prevent verification.
 
-The guided `npx human-to-code .` flow may ask the same provider/model for at most two diagnostic repairs, further limited by `budgets.maxRepairs`. Repairs run only for deterministic candidate regressions after a healthy baseline in the strong sandbox. They cannot run for security findings, infrastructure/toolchain failures, timeouts, flaky/truncated output, or unavailable services, and they cannot change paths/operation kinds, provenance, requirement coverage, dependencies, lockfiles, test operations, validation configuration, or remove existing proposed test obligations. Every accepted repair is safety-checked and validated from fresh baseline/candidate copies.
+The `human-to-code guided` flow may ask the same provider/model for at most two diagnostic repairs, further limited by `budgets.maxRepairs`. Repairs run only for deterministic candidate regressions after a healthy baseline in the strong sandbox. They cannot run for security findings, infrastructure/toolchain failures, timeouts, flaky/truncated output, or unavailable services, and they cannot change paths/operation kinds, provenance, requirement coverage, dependencies, lockfiles, test operations, validation configuration, or remove existing proposed test obligations. Every accepted repair is safety-checked and validated from fresh baseline/candidate copies.
 
 Repair checkpoints preserve cumulative request/token/cost/repair usage, provider identity, request IDs, immutable input hashes, attempt patches/diffs, and reports. A crash cannot reset the allowance. The standalone `validate <run-id>` command deliberately has no provider credentials and therefore only revalidates the stored patch; an embedding caller can continue any remaining repair allowance only by supplying the exact original provider and persisted configuration.
 

package/assets/banner.svg

@@ -16,23 +16,18 @@
   <text x="640" y="118" text-anchor="middle" class="mono" font-size="62" font-weight="700" fill="#f8fafc">human-to-code</text>
   <text x="640" y="158" text-anchor="middle" class="sans" font-size="21" fill="#94a3b8">Write intent in plain language. Compile it to real code.</text>
 
-  <!-- pipeline: human -> strict -> code -->
+  <!-- pipeline: human -> code (the guided reviewed/validated path is optional) -->
   <g>
-    <rect x="300" y="212" width="170" height="62" rx="14" fill="#f59e0b"/>
-    <text x="385" y="251" text-anchor="middle" class="mono" font-size="24" font-weight="700" fill="#1c1206">human</text>
+    <rect x="445" y="212" width="170" height="62" rx="14" fill="#f59e0b"/>
+    <text x="530" y="251" text-anchor="middle" class="mono" font-size="24" font-weight="700" fill="#1c1206">human</text>
 
-    <text x="495" y="252" text-anchor="middle" class="sans" font-size="30" fill="#64748b">&#8594;</text>
+    <text x="640" y="252" text-anchor="middle" class="sans" font-size="30" fill="#64748b">&#8594;</text>
 
-    <rect x="520" y="212" width="240" height="62" rx="14" fill="#38bdf8"/>
-    <text x="640" y="251" text-anchor="middle" class="mono" font-size="24" font-weight="700" fill="#062033">strict</text>
-
-    <text x="785" y="252" text-anchor="middle" class="sans" font-size="30" fill="#64748b">&#8594;</text>
-
-    <rect x="810" y="212" width="170" height="62" rx="14" fill="#34d399"/>
-    <text x="895" y="251" text-anchor="middle" class="mono" font-size="24" font-weight="700" fill="#062018">code</text>
+    <rect x="665" y="212" width="170" height="62" rx="14" fill="#34d399"/>
+    <text x="750" y="251" text-anchor="middle" class="mono" font-size="24" font-weight="700" fill="#062018">code</text>
   </g>
 
-  <text x="385" y="304" text-anchor="middle" class="sans" font-size="15" fill="#64748b">natural language</text>
-  <text x="640" y="304" text-anchor="middle" class="sans" font-size="15" fill="#64748b">reviewable IR &#183; deterministic</text>
-  <text x="895" y="304" text-anchor="middle" class="sans" font-size="15" fill="#64748b">TS &#183; JS &#183; Python</text>
+  <text x="530" y="304" text-anchor="middle" class="sans" font-size="15" fill="#64748b">natural language</text>
+  <text x="750" y="304" text-anchor="middle" class="sans" font-size="15" fill="#64748b">TS &#183; JS &#183; Python</text>
+  <text x="640" y="336" text-anchor="middle" class="sans" font-size="14" fill="#475569">optional guided pipeline &#8594; reviewed contract &#8594; sandbox-validated patch</text>
 </svg>

package/assets/brand/social-card.svg

@@ -1,5 +1,5 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 640" width="1280" height="640" role="img" aria-labelledby="title desc">
-  <title id="title">human-to-code — reviewed intent to validated code</title>
+  <title id="title">human-to-code — plain language to real code</title>
   <desc id="desc">Social sharing card for human-to-code.</desc>
   <defs>
     <linearGradient id="bg" x1="80" y1="40" x2="1200" y2="620" gradientUnits="userSpaceOnUse">
@@ -24,19 +24,19 @@
     <rect x="58" y="45" width="12" height="38" rx="6" fill="#ff5f3c"/>
   </g>
   <text x="258" y="177" fill="#f7f4ef" font-family="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="64" font-weight="850" letter-spacing="-3">human-to-code</text>
-  <text x="91" y="315" fill="#f7f4ef" font-family="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="50" font-weight="760" letter-spacing="-1.6">Reviewed intent.</text>
-  <text x="91" y="376" fill="#ff8a5c" font-family="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="50" font-weight="760" letter-spacing="-1.6">Validated code.</text>
-  <text x="91" y="432" fill="#aaa6b0" font-family="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="23">Security-constrained compiler agent for grounded, reviewable patches.</text>
+  <text x="91" y="315" fill="#f7f4ef" font-family="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="50" font-weight="760" letter-spacing="-1.6">Plain language.</text>
+  <text x="91" y="376" fill="#ff8a5c" font-family="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="50" font-weight="760" letter-spacing="-1.6">Real code.</text>
+  <text x="91" y="432" fill="#aaa6b0" font-family="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="23">Turns .human files and @human markers straight into real code.</text>
   <g transform="translate(91 500)" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18" font-weight="700">
     <rect width="142" height="48" rx="24" fill="#f7f4ef" fill-opacity=".08" stroke="#fff" stroke-opacity=".12"/>
     <text x="71" y="31" text-anchor="middle" fill="#f7f4ef">.human</text>
     <path d="M155 24h42" stroke="#ff5f3c" stroke-width="3" stroke-linecap="round"/>
     <path d="m190 17 8 7-8 7" fill="none" stroke="#ff5f3c" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
     <rect x="211" width="168" height="48" rx="24" fill="#f7f4ef" fill-opacity=".08" stroke="#fff" stroke-opacity=".12"/>
-    <text x="295" y="31" text-anchor="middle" fill="#f7f4ef">review</text>
+    <text x="295" y="31" text-anchor="middle" fill="#f7f4ef">generate</text>
     <path d="M392 24h42" stroke="#ff5f3c" stroke-width="3" stroke-linecap="round"/>
     <path d="m427 17 8 7-8 7" fill="none" stroke="#ff5f3c" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
     <rect x="448" width="182" height="48" rx="24" fill="#ff5f3c"/>
-    <text x="539" y="31" text-anchor="middle" fill="#13090b">verified patch</text>
+    <text x="539" y="31" text-anchor="middle" fill="#13090b">code</text>
   </g>
 </svg>

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,sGAAsG;AA+vBtG,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAiFzD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,sGAAsG;AA0wBtG,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAiFzD"}

package/dist/cli.js

@@ -15,12 +15,13 @@ import { ProviderError } from "./providers/provider.js";
 import { createOllamaProvider, createOpenAIProvider } from "./providers/providers.js";
 import { RunStore } from "./pipeline/run-store.js";
 import { applyUnit, discoverUnits, generateConversionUnits, generateCode, renderReceipt, } from "./pipeline/simple.js";
+import { createAgentTerminal } from "./pipeline/agent-tui.js";
 import { applyVerifiedRun, buildContextPreview, generateRun, resolveWorkspaceConfig, rollbackAppliedRun, validateStoredRun, } from "./pipeline/workflow.js";
 const HELP = `human-to-code — reviewed, grounded, isolated human-to-code compiler agent
 
 Usage:
-  human-to-code [root] [-y]                    Convert .human files and @human markers to code (default; LangGraph deep agent)
-  human-to-code [root] [-y] --simple           Use the deterministic, dependency-free generator instead of the deep agent
+  human-to-code [root] [-y]                    Convert .human files and @human markers to code (default; fast deterministic engine)
+  human-to-code [root] [-y] --agent            Use the agent dashboard (todos/tools/commands/diffs; needs reliable JSON tool calling)
   human-to-code build [root] [-y]              Alias of the default convert flow
   human-to-code guided [root]                  Reviewed/grounded/validated compiler pipeline
   human-to-code analyze [root] [--json]
@@ -51,7 +52,8 @@ Other options:
   --explain                      Show outbound context provenance and exact selected content
   --json                         Machine-readable output
   -y, --yes                      Skip the confirmation prompt and write files
-  --simple                       Use the deterministic generator instead of the deep agent (default flow only)
+  --agent                        Use the interactive agent dashboard instead of the deterministic engine
+  --simple                       Deprecated no-op; the deterministic engine is now the default
   --dry-run                      Analyze and preview only; perform no generation
   --manual-passed                Explicitly attest all reviewed manual acceptance checks
   --sandbox-image <image>        Trusted image reference that must already exist locally
@@ -83,6 +85,7 @@ function parse(argv) {
             "trust-custom-endpoint": { type: "boolean", default: false },
             yes: { type: "boolean", short: "y", default: false },
             simple: { type: "boolean", default: false },
+            agent: { type: "boolean", default: false },
             init: { type: "boolean", default: false },
             help: { type: "boolean", short: "h", default: false },
             root: { type: "string" },
@@ -108,6 +111,7 @@ function parse(argv) {
         trustCustomEndpoint: values["trust-custom-endpoint"] === true,
         yes: values.yes === true,
         simple: values.simple === true,
+        agent: values.agent === true,
         init: values.init === true,
         help: values.help === true,
         ...(typeof values.root === "string" ? { root: values.root } : {}),
@@ -432,11 +436,19 @@ function createSpinner(active) {
     const started = Date.now();
     let index = 0;
     let text = "working";
+    const columns = () => (typeof process.stderr.columns === "number" && process.stderr.columns > 12 ? process.stderr.columns : 80);
     const clear = () => { process.stderr.write("\r"); };
     const tick = () => {
         index = (index + 1) % frames.length;
         const seconds = Math.round((Date.now() - started) / 1000);
-        process.stderr.write(`\r${frames[index] ?? ""} ${text} · ${seconds}s`);
+        let line = `${frames[index] ?? ""} ${text} · ${seconds}s`;
+        // Truncate to one terminal row: a wider line wraps, and the carriage-return
+        // clear then cannot erase the wrapped remainder — that is what made the
+        // spinner spew a new line per frame.
+        const max = columns() - 1;
+        if (line.length > max)
+            line = `${line.slice(0, max - 1)}…`;
+        process.stderr.write(`\r\x1b[K${line}`);
     };
     const timer = setInterval(tick, 120);
     if (typeof timer.unref === "function")
@@ -447,18 +459,11 @@ function createSpinner(active) {
         stop: () => { clearInterval(timer); clear(); },
     };
 }
-function todoIcon(status) {
-    if (status === "completed")
-        return "[✓]";
-    if (status === "in_progress")
-        return "[~]";
-    return "[ ]";
-}
 /** Rewrite an incapable-model tool-call failure into an actionable hint. */
 function deepAgentErrorHint(message) {
     const looksLikeToolFormatFailure = /xml syntax error|<\/?(?:function|parameter|tool_call)>|failed to parse|does not support tools|no tool/iu.test(message);
     return looksLikeToolFormatFailure
-        ? " — the model likely cannot emit valid tool calls. Use a larger tool-calling model (for example qwen2.5-coder:7b or bigger), or run with --simple."
+        ? " — the model could not emit valid JSON tool calls. Try the deterministic default mode or a stronger tool-calling model."
         : "";
 }
 /**
@@ -489,7 +494,7 @@ async function buildCommand(cli, rootInput) {
         }
     }
     else {
-        output(renderReceipt(units, providerName, model, language, cli.simple ? "simple" : "agent"), false);
+        output(renderReceipt(units, providerName, model, language, cli.agent ? "agent" : "simple"), false);
     }
     if (units.length === 0)
         return 3;
@@ -507,53 +512,20 @@ async function buildCommand(cli, rootInput) {
     const apiKey = providerName === "openai"
         ? process.env[effective.provider.apiKeyEnv ?? "OPENAI_API_KEY"]
         : undefined;
-    const localMemoryProvider = providerName === "ollama"
+    const localProvider = providerName === "ollama"
         && (baseUrl === undefined || isLoopbackProviderHost(new URL(baseUrl).hostname));
-    if (units.some((unit) => unit.kind === "inline")
-        && !localMemoryProvider
-        && !effective.privacy.remoteProviderConsent) {
-        throw new ContextSecurityError("INVALID_CANDIDATE", "Inline FileMemory would send statically indexed source declarations to a remote provider. Review the provider and set privacy.remoteProviderConsent to true first.");
-    }
-    // Default engine: a LangGraph deep agent (planning, filesystem, subagents,
-    // prompts). `--simple` selects the deterministic, dependency-free generator.
-    if (!cli.simple) {
+    if (!localProvider && !effective.privacy.remoteProviderConsent) {
+        throw new ContextSecurityError("INVALID_CANDIDATE", "Direct conversion would send change instructions and possibly source context to a remote provider. Review the provider and set privacy.remoteProviderConsent to true first.");
+    }
+    // `--agent` opts into the tool-rich LangGraph agent dashboard. The default
+    // remains the deterministic per-marker generator below.
+    if (cli.agent) {
         const { runDeepAgentConversion } = await import("./pipeline/deep-agent.js");
-        const interactive = !cli.json;
-        const spinner = createSpinner(interactive);
         const started = Date.now();
-        const todoStatus = new Map();
-        let planPrinted = false;
-        const onProgress = interactive
-            ? (event) => {
-                if (event.kind === "plan") {
-                    if (!planPrinted) {
-                        spinner.note("\nPlan:");
-                        for (const todo of event.todos) {
-                            spinner.note(`  ${todoIcon(todo.status)} ${todo.content}`);
-                            todoStatus.set(todo.content, todo.status);
-                        }
-                        planPrinted = true;
-                        return;
-                    }
-                    for (const todo of event.todos) {
-                        if (todoStatus.get(todo.content) !== todo.status) {
-                            if (todo.status === "completed")
-                                spinner.note(`  ✓ ${todo.content}`);
-                            else if (todo.status === "in_progress")
-                                spinner.label(todo.content);
-                            todoStatus.set(todo.content, todo.status);
-                        }
-                    }
-                }
-                else if (event.kind === "tool") {
-                    const detail = event.detail ? ` ${event.detail}` : "";
-                    spinner.note(`  → ${event.name}${detail}`);
-                    spinner.label(`${event.name}${detail}`);
-                }
-            }
+        const terminal = cli.json ? undefined : createAgentTerminal(`human-to-code agent  •  ${model}  •  ${basename(root)}`);
+        const onProgress = terminal
+            ? (event) => terminal.progress(event)
             : undefined;
-        if (interactive)
-            output("\nStarting deep agent… (planning, filesystem, subagents)", false);
         try {
             const outcome = await runDeepAgentConversion({
                 root,
@@ -565,30 +537,50 @@ async function buildCommand(cli, rootInput) {
                 ...(apiKey ? { apiKey } : {}),
                 ...(onProgress ? { onProgress } : {}),
             });
-            spinner.stop();
+            terminal?.stop();
             const seconds = Math.round((Date.now() - started) / 1000);
             if (cli.json) {
-                output({ status: "DONE", engine: "deep-agent", todos: outcome.todos, messages: outcome.messageCount, summary: outcome.summary }, true);
+                output({ status: "DONE", engine: "deep-agent", stopReason: outcome.stopReason, todos: outcome.todos, messages: outcome.messageCount, tools: outcome.toolCount, summary: outcome.summary }, true);
             }
             else {
-                output(`\nDeep agent finished in ${seconds}s (${outcome.messageCount} steps).${outcome.summary ? `\n${outcome.summary}` : ""}`, false);
+                output(`Agent finished in ${seconds}s • ${outcome.toolCount} tools • ${outcome.stopReason.replaceAll("_", " ")}.${outcome.summary ? `\n${outcome.summary}` : ""}`, false);
             }
             return 0;
         }
         catch (error) {
-            spinner.stop();
+            terminal?.stop();
             const message = error instanceof Error ? error.message : String(error);
             output(cli.json
                 ? { status: "FAILED", engine: "deep-agent", error: message }
-                : `\nDeep agent error: ${message}${deepAgentErrorHint(message)}`, cli.json);
+                : `Agent stopped: ${message}${deepAgentErrorHint(message)}`, cli.json);
             return 5;
         }
     }
+    // Default engine: deterministic per-marker generation. Each marker is one
+    // plain model completion (no tool calls), applied by exact range. One marker
+    // failing never aborts the others.
+    const describeUnit = (unit) => unit.kind === "file"
+        ? `${unit.sourcePath} → ${unit.outputPath}`
+        : `${unit.sourcePath} (inline @human, line ${unit.line ?? "?"})`;
+    const interactive = !cli.json;
+    const spinner = createSpinner(interactive);
+    const started = Date.now();
+    const onProgress = interactive
+        ? (event) => {
+            if (event.kind === "start") {
+                const retry = event.attempt > 1 ? ` (retry ${event.attempt - 1})` : "";
+                spinner.label(`generating ${describeUnit(event.unit)}${retry}`);
+            }
+            else if (event.kind === "skip") {
+                spinner.note(`  ⊘ skipped ${describeUnit(event.unit)}: ${event.reason}`);
+            }
+        }
+        : undefined;
+    if (interactive)
+        output(`\nConverting ${units.length} item(s) with ${model}…`, false);
     let generated;
-    let generatingSource;
     try {
         generated = await generateConversionUnits(units, (unit, context) => {
-            generatingSource = unit.sourcePath;
             if (context.fileMemory
                 && context.fileMemory.length > effective.privacy.maxContextTokens * 4) {
                 throw new ContextSecurityError("BUDGET_EXCEEDED", `FileMemory for ${unit.sourcePath} exceeds the configured context budget.`, unit.sourcePath);
@@ -601,18 +593,19 @@ async function buildCommand(cli, rootInput) {
                 ...(apiKey ? { apiKey } : {}),
                 ...context,
             });
-        });
+        }, { retries: 1, ...(onProgress ? { onProgress } : {}) });
     }
     catch (error) {
+        spinner.stop();
         if (error instanceof ContextSecurityError)
             throw error;
-        output(cli.json
-            ? { status: "FAILED", ...(generatingSource ? { source: generatingSource } : {}), error: String(error) }
-            : `\nProvider error${generatingSource ? ` for ${generatingSource}` : ""}: ${error instanceof Error ? error.message : String(error)}`, cli.json);
+        const message = error instanceof Error ? error.message : String(error);
+        output(cli.json ? { status: "FAILED", error: message } : `\nError: ${message}`, cli.json);
         return 5;
     }
-    // Generation is top-to-bottom so FileMemory is meaningful. Application stays
-    // bottom-to-top so replacing later markers cannot invalidate earlier ranges.
+    spinner.stop();
+    // Apply bottom-to-top so replacing a later marker cannot invalidate an
+    // earlier marker's range.
     const ordered = [...generated].sort((left, right) => {
         if (left.unit.kind !== right.unit.kind)
             return left.unit.kind === "file" ? -1 : 1;
@@ -622,19 +615,31 @@ async function buildCommand(cli, rootInput) {
         return (right.unit.range?.start ?? 0) - (left.unit.range?.start ?? 0);
     });
     const written = [];
-    for (const { unit, code } of ordered) {
+    const skipped = [];
+    for (const { unit, code, error } of ordered) {
+        if (error !== undefined) {
+            skipped.push({ source: unit.sourcePath, reason: error });
+            continue; // already reported live via onProgress
+        }
         if (code.trim().length === 0) {
+            skipped.push({ source: unit.sourcePath, reason: "empty model output" });
             if (!cli.json)
-                output(`  ! empty model output for ${unit.sourcePath}; skipped`, false);
+                output(`  ⊘ skipped ${describeUnit(unit)}: empty model output`, false);
             continue;
         }
         const path = await applyUnit(root, unit, code);
         written.push(path);
         if (!cli.json)
-            output(`  ✓ wrote ${path}`, false);
+            output(`  ✓ ${describeUnit(unit)}`, false);
     }
-    output(cli.json ? { status: "DONE", written } : `\nDone. ${written.length} file(s) written.`, cli.json);
-    return 0;
+    const seconds = Math.round((Date.now() - started) / 1000);
+    if (cli.json) {
+        output({ status: written.length === 0 && skipped.length > 0 ? "FAILED" : "DONE", engine: "simple", written, skipped }, true);
+    }
+    else {
+        output(`\nDone in ${seconds}s. ${written.length} written${skipped.length > 0 ? `, ${skipped.length} skipped` : ""}.`, false);
+    }
+    return written.length === 0 && skipped.length > 0 ? 5 : 0;
 }
 async function guided(cli, rootInput) {
     const root = resolve(cli.root ?? rootInput ?? ".");