pentesting 0.101.7 → 0.101.9

package/README.md

@@ -54,7 +54,7 @@ Provider variables are optional — the TUI launches without them and lets you l
 | Verified agent loop | Streams actions and observations; a model Stop ends only the turn, evidence-backed verification closes the mission, and the full trajectory is persisted |
 | Unified tool boundary | Built-in, delegated, and MCP calls share schema validation, provenance, permissions, policy, and resource limits |
 | Context economy | Automatic micro-pruning and model-triggered summaries preserve useful context for low-cost models |
-| Deterministic steering | Esc stops the current turn and auto loop, while submitted input resumes in FIFO order at safe turn boundaries |
+| Deterministic steering | Active-turn submissions are retained for the next safe transcript boundary; Esc stops the current turn and auto loop while the visible inputs resume in FIFO order |
 | Reverse-shell & PTY lifecycle | One control plane manages authorized callbacks and local PTY/pipe sessions, from tagging, probing, and verified upgrades to transcripts, evidence, FD accounting, and deterministic reclamation |
 | Bounded battlefield | A persistent Lead ledger produces a compact on-demand attention brief and read-only `/status` view; dispatch stays explicit and is capped at four branches |
 | Adversarial pathfinding | A localized AlphaGo-inspired minimax technique models an opponent's best defensive move and improves the ability to find viable bypass paths |
@@ -115,3 +115,9 @@ Provider variables are optional — the TUI launches without them and lets you l
 > Each voice sings its most beautiful song from its own place, yet when combined, they create one grand, beautiful melody. I believe this structure is no different from AI agents.
 >
 > — *agnusdei1207*
+
+---
+
+## 💡 Insight
+
+> Analyzing countless starred agent repos and papers gave me insights, but adopting them didn't actually solve the core problem. What did, I think: primitive CS theory — backtracking, Monte Carlo, Prim, Kruskal — and ideas from observing myself, the best design blueprint and best practice there is. The AI era keeps pushing sensational marketing, and I've lost trust in analyzing it. I think refining the fundamentals, internalizing them, and finding my own way matters more, especially now.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pentesting",
-  "version": "0.101.7",
-  "builderReleaseTag": "v0.101.7",
+  "version": "0.101.9",
+  "builderReleaseTag": "v0.101.9",
   "description": "Penetration testing AI agent powered by Rust, with audited reverse-shell capture, verified PTY upgrades, and evidence-first orchestration.",
   "license": "MIT",
   "author": "agnusdei1207",
@@ -14,7 +14,6 @@
     "lib",
     "scripts/postinstall.mjs",
     "README.md",
-    "ARCHITECTURE.md",
     "pentesting-logo.svg"
   ],
   "engines": {

package/ARCHITECTURE.md

@@ -1,622 +0,0 @@
-# Architecture
-
-This document reflects the current `main` branch architecture. It is the single,
-detailed reference for how the runtime is structured; the [README](README.md)
-stays intentionally short and usage-focused.
-
-> **Engine vs product.** The orchestration engine is **`builder`** — a
-> general-purpose, local-first Rust agent runtime. **`pentesting`** is the
-> published, security-focused distribution of that same engine: the npm package
-> and the command you run. They share one binary. The model owns task reasoning;
-> the Rust runtime owns protocol normalization, authorization, bounded execution,
-> observations, and verified outcome provenance.
-
-## 1. Architecture at a glance
-
-```text
-user input
-  → deterministic turn queue
-  → model/provider adapter
-  → one tool gateway
-  → authorized, bounded execution
-  → append observation to the turn
-  → repeat until TurnExit
-  → emit TurnCompleted
-  → emit TaskComplete only for a verified MissionState
-```
-
-The core is deliberately narrower than the complete product. Its append-only
-`TurnEvent` trajectory contains model terminals, actions, observations, and
-verification provenance. The complete trajectory is stored in the terminal
-`RunOutcome`; the request-time `TurnSnapshot` is its bounded O(1) projection.
-Memory, MCP,
-delegation, CTF exploration, and security sessions use the same tool boundary.
-Engagement context changes instructions, not tool reachability; resource caps
-bound expensive operations.
-
-## 2. Design pillars
-
-- **Model-Driven Work** — The model chooses plans, probes, commands, and ordinary
-  recovery. The runtime does not duplicate that reasoning with hot-path LLM judges.
-- **Hard Boundaries, Not Hard Opinions** — Schema, scope, permission, secrets,
-  cancellation, time, output, memory, and process limits are deterministic.
-- **Typed Turn Lifecycle** — Provider terminal state, `TurnExit`, and
-  `MissionState` are separate. Stop is never proof of success.
-- **One Tool Entry Boundary** — Built-in, delegated, and MCP tools share
-  allowlist, provenance, registered-contract, and schema validation. Hooks are
-  orchestrator-owned; permission checks apply only when a tool produces a
-  policy operation. Ordinary/MCP tools use configured timeouts, while
-  delegation uses its own runtime budget.
-- **Append-Oriented Observation** — Trajectory and evidence are local-first;
-  prior-run information is linked by reference rather than copied.
-- **Deterministic Queuing** — FIFO revisions support amend-next and explicit
-  replace without auxiliary LLM prioritization.
-- **One Security Surface** — Session, process, finding, flag verification, and
-  frontier operations are ordinary tools. Engagement context, permission,
-  resource budget, and proof remain separate responsibilities.
-- **Prompt Ownership** — Prompt mode owns Enter submission. Buffered replay may
-  preserve typed-ahead input, but live terminal control responses, redraws, and
-  resize noise are not allowed to turn a normal Enter into a pasted newline.
-  Modal return restores the transcript scroll region and its pre-modal saved
-  cursor before the fixed bottom UI is redrawn.
-- **Lab Session Multiplexing** — `shell-listener` runs multiple authorized TCP,
-  local PTY, and local pipe sessions. A single actor exclusively owns each
-  session's descriptors, command queue, transcript, raw log, and child
-  lifecycle; the registry keeps only a bounded sender and projection.
-- **Ebbinghaus-Inspired Memory** — Memories carry a *strength* that fades like
-  human memory and reinforces on recall. Faded notes are de-referenced, never
-  destroyed.
-- **Git-Backed Rewind** — Working-tree checkpoint/restore keeps autonomous edits
-  reversible.
-
-## 3. Runtime flow, one level deeper
-
-```mermaid
-flowchart TD
-    U[User request] --> CLI[builder_main CLI / TUI]
-    CLI --> API[builder_api facade]
-    API --> APP[builder_app coordination]
-    APP --> TURN[Turn kernel]
-    TURN --> MODEL[Provider adapter]
-    MODEL --> GW[Tool entry boundary]
-    GW --> POLICY[Schema + applicable policy/resource boundary]
-    POLICY --> EXEC[Tool / environment execution]
-    EXEC --> OBS[Observation + artifact refs]
-    OBS --> TURN
-    TURN --> EXIT[Typed TurnExit]
-    EXIT --> VERIFY[Outcome verifier]
-    VERIFY --> OUT[TurnCompleted / verified TaskComplete]
-```
-
-Plain view:
-
-```text
-user input
-  -> CLI / interactive prompt loop
-  -> terminal-session prompt ownership + buffered replay boundary
-  -> BuilderAPI facade
-  -> BuilderApp turn kernel and provider adapter
-  -> registered tool contract and common entry boundary
-  -> policy-gated, resource-bounded execution
-  -> observation and artifact references
-  -> typed turn exit and optional verified mission outcome
-```
-
-Builder is a domain-neutral runtime with a security-focused distribution.
-Development, pentesting, CTF, audit, and release behavior layers in through
-context, tools, and skills rather than new core strategy kinds.
-
-### Runtime persistence ports
-
-Hot-path consumers depend on ten cohesive persistence ports:
-
-```text
-run/objective/evidence/task/execution/outcome
-audit/observation/lineage/conversation-memory
-                         |
-          local persistence composition root
-```
-
-Each producer/consumer depends on the smallest relevant port. The methodless
-`ControlPlaneRepository` marker composes those ports only at construction and
-dynamic storage boundaries. Implementations and test fakes implement the
-physical ports directly; there are no blanket forwarding adapters, fallback
-methods, alternate schemas, or second runtime state.
-
-## 4. Engagement context and bounded CTF exploration
-
-There is no model-backed intent classifier or weak/standard model mode in the
-request hot path. Explicit event metadata is routed deterministically; absent
-metadata receives one general strategy. Named profiles may add context, but
-coarse labels do not authorize or reject tool calls.
-
-CTF engagement metadata may select `ctf-competition` prompt context, and
-`flag_check` remains a verification tool and evidence source rather than a
-default completion gate. `explore` is always available; `[exploration]` only
-sets node and fan-out caps. Installed users edit the relevant engagement, flag,
-and frontier fields through `/config`.
-
-The shipped exploration tool does not replace the core execution strategy.
-It provides a bounded `EvidenceKind::Lead` ledger and explicit dispatch. Stable
-generated identity is separate from semantic deduplication. Dead probes suppress
-an execution branch without rejecting its knowledge hypothesis, and fresh
-evidence reopens scheduling. An explicit `explore op=frontier` call reads one
-canonical snapshot and returns a bounded attention brief: one visible focus, at
-most two alternatives, at most two alerts, state counts, and an omitted count.
-Focus is visibility, not a recommendation, authorization, or execution lock;
-priority scores stay internal and the model must name leads in a separate
-`dispatch` call. The model-facing payload stays within 4 KiB after JSON and HTML
-escaping. On an explicit `/status`, the same pure projection is loaded once and
-rendered as Battlefield Lite: at most eight logical rows and 1.5 KiB, containing
-only typed counts/enums/numeric metadata and revalidated Lead IDs. It omits Lead
-title, detail, parent/sample IDs, evidence references, tool output, and score;
-that is a narrow Lead-prose disclosure boundary, not a general secret scanner
-for the rest of the diagnostic output. There is no passive mission-control
-injection, model-request hot-path repository read, `/frontier` command, detached
-task registry, advisor, or second scheduler.
-`orch_spec::exploration_e2e` pins the explicit frontier/pivot/dispatch/merge
-behavior. A deterministic 256-Lead Phase 4 fixture measured the legacy rendered
-frontier at 121,420 bytes and the bounded brief at 1,858 bytes (98.46% smaller),
-while the existing completion-provenance corpus remained 9/9. This supports the
-bounded visibility decision; it is not a claim of improved live-model solve rate.
-
-Reliability guards sit below the profile layer. Provider protocol capabilities
-default native tool support for OpenAI/Anthropic-compatible responses on
-registry misses, unparsed tool-shaped markup becomes retryable instead of a
-false completion, raw control markup is scrubbed from the stream, and the
-markdown renderer flushes long no-newline prose at soft boundaries while still
-bounding very large buffers.
-
-```mermaid
-flowchart LR
-    R[Request] --> GEN["Resolve<br/>task-shaped defaults"]
-    GEN --> REC["Optional<br/>named profile / pack"]
-    REC --> USE["Bound<br/>tool scope and budget"]
-```
-
-Request to closure:
-
-```mermaid
-flowchart TD
-    U[User request] --> A[Agent turn]
-    A --> M[Model output]
-    M --> T{Registered action?}
-    T -- no --> X[Typed turn exit]
-    T -- yes --> G[Common tool gateway]
-    G --> O[Observation]
-    O --> A
-    X --> V{Verified artifact?}
-    V -- no --> TC[TurnCompleted]
-    V -- yes --> MC[TaskComplete + provenance]
-```
-
-## Agent Team
-
-The core agent team is domain-neutral. Each agent ships as a markdown persona
-definition under `crates/builder_repo/src/agents/`.
-
-Subagents are explicit and bounded. A `task` call selects one agent; its tasks
-run concurrently up to four per call and delegation stops at depth two.
-Separate top-level tool calls are sequenced. Built-ins include `crypto`, `rev`,
-and `pwn`.
-
-`explore dispatch` is a separate path. It runs selected leads as `builder`
-clones with category overlays, defaults to breadth one, is hard-capped at four,
-and waits for the batch. It does not auto-route leads to specialist personas.
-Every child uses the same tool/policy gateway, budget, lineage, and evidence
-merge contracts.
-
-| Agent | Default role | Runtime profile |
-| --- | --- | --- |
-| `builder` | Hands-on implementation, refactoring, local file changes, tests | Implement + broad local write |
-| `planner` | Implementation plans and risk breakdowns | Plan + read-only |
-| `researcher` | Read-only codebase and reference research | Investigate + read-only |
-| `coordinator` | Splits broad work into owned packets and consolidates results | Coordinate + broad local write |
-| `investigator` | Evidence gathering across code, logs, commands, APIs, and behavior | Investigate + shell diagnostics |
-| `operator` | Builds, tests, packaging, service startup, and runtime workflows | Implement + broad local write |
-| `reviewer` | Findings-first technical review | Review + strict read-only |
-| `verifier` | Reproduction, build/test proof, and completion claim checks | Verify + strict read-only |
-| `report-writer` | Reports, handoffs, release notes, and reproducibility records | Implement + bounded write |
-
-> Distinct tool-scope is runtime-enforced for `builder`, `planner`, and
-> `researcher`; the remaining personas share a task-shaped generic profile
-> (read-only when the task shape is review/verify, broad local write otherwise)
-> and differ by their prompt instructions.
-
-## Named Autonomy Profiles
-
-Optionally pin the top-level profile (`autonomy_profile = "ctf-competition"`);
-leave unset for the deterministic general default. CTF engagement config may
-select CTF prompt context when no explicit profile is set, but it never changes
-tool reachability. Delegated subagent contracts stay intact. Defined in
-`crates/builder_domain/src/autonomy_profile.rs`.
-
-| Profile | Purpose |
-| --- | --- |
-| `general-agent` | Broad autonomous local orchestration for mixed tasks |
-| `local-builder` | Hands-on implementation with fresh evidence retrieval |
-| `ctf-competition` | Competition/lab workflow; the profile references `ctf-competition` and `pentesting-methodology`, while built-in `write-report` remains explicitly selectable |
-| `enterprise-review` | Strict, review-heavy profile with read-only dynamic scope |
-
-## Engagement Metadata
-
-Runs can attach typed engagement context — scope, phase, tags, flag format,
-flag-evidence requirement, and standard refs (PTES, MITRE ATT&CK, OWASP,
-CWE/CAPEC, NIST CSF, CIS Controls) — to workflow metadata. `/workflow report`
-exports it as a Markdown handoff.
-
-## Memory & Knowledge
-
-Local-first and split across two complementary layers, no vector DB, no cloud:
-
-- **Conversation memories** — facts/preferences/gotchas distilled from sessions,
-  persisted in local runtime state and recalled into each prompt by hybrid
-  retrieval. These carry a *strength* that fades like human memory, so the store
-  stays sharp instead of rotting.
-- **Knowledge vault** — an optional Obsidian-style set of markdown notes under
-  `.pentesting/knowledge` (wiki-links, backlinks, tags). The agent reads it on every
-  turn and grows it with the `write` tool; it is never auto-deleted.
-
-Both layers feed the same strength-weighted hybrid retrieval.
-
-**Storage** — Ebbinghaus lifecycle (decay · reinforce · floor, never deleted):
-
-```mermaid
-flowchart TD
-    N[New memory] --> S["strength = quality × recall × e^-λ·age"]
-    S --> U{recalled?}
-    U -- yes --> RE[reinforce ↑ · reset age]
-    U -- no --> D[decay over time]
-    RE --> S
-    D --> F{below floor?}
-    F -- no --> S
-    F -- yes --> AR[de-reference: archive / tombstone]
-    AR -. recoverable on disk .-> N
-```
-
-Kinds fade at different speeds (procedural outlives episodic); bi-temporal
-`event_time` vs `ingestion_time` lets newer facts supersede stale ones.
-
-**Retrieval** — hybrid fuse, strength-weighted, read-only:
-
-```mermaid
-flowchart LR
-    Q[Query] --> L[Lexical]
-    Q --> SE[Semantic]
-    Q --> G[Graph]
-    L --> RRF[RRF fuse]
-    SE --> RRF
-    G --> RRF
-    RRF --> RR[rerank: phase · recency · task]
-    RR --> W[weight by strength]
-    W --> P[Prompt context]
-```
-
-Faded, private, or unsafe memories are held back from the prompt. Lookups never
-write — reinforce/archive/supersede are explicit, never search side effects.
-
-## Storage Strategy
-
-Builder uses one operational storage strategy: local on-disk runtime state plus
-markdown-native knowledge artifacts.
-
-```mermaid
-flowchart LR
-    W[Workspace files] --> AD[Source adapters]
-    S[Skills] --> AD
-    M[Conversation memories] --> AD
-    N[Markdown notes] --> AD
-    AD --> IDX[Local lexical + semantic + graph index]
-    IDX --> RR[Contextual reranker]
-    RR --> PC[Prompt context]
-    PC --> RUN[Agent run]
-    RUN --> LS[.pentesting local state]
-    RUN --> ART[Local artifacts and reports]
-```
-
-Key invariants:
-
-- Runtime state is local-first and does not require an external data service.
-- The markdown knowledge graph is derived from local facts: notes, skills,
-  conversation memory, wiki-links, backlinks, and run artifacts.
-- Graph data is a derived retrieval view, not a second source of truth.
-- Evidence, workflow runs, state cards, and verified artifacts persist through
-  local repositories. Removed semantic-verdict, recovery-route, completion
-  bundle, replay-archive, and curation projections cannot redirect the active
-  model loop because they no longer exist in the runtime model.
-- Domain methods such as development, CTF practice, pentesting methodology,
-  audits, and release work live in skills and task instructions; they do not
-  change the core runtime identity.
-
-## Crate Map
-
-| Layer | Crates | Responsibility |
-| --- | --- | --- |
-| Interaction | `builder_main`, `builder_ratatui`, `builder_select`, `builder_markdown_stream` | CLI, TUI, prompt flow, rendering, selector fallback |
-| Facade | `builder_api` | Thin application boundary used by entry points |
-| Coordination | `builder_app` | turn loop, provider adaptation, common tool gateway, observations, verified outcome |
-| Contracts | `builder_domain` | typed IDs, tools, workflow records, engagement metadata, policies |
-| Capabilities | `builder_services` | tool services, auth, provider support, file/search/shell/fetch operations |
-| Persistence | `builder_repo`, `builder_provider_repo` | local repositories, provider catalog, chat repository |
-| Knowledge | `builder_knowledge`, `builder_workspace_index`, `builder_embed` | markdown note adapters, graph parsing, hybrid retrieval, local semantic scoring |
-| Infrastructure | `builder_config`, `builder_infra`, `builder_fs`, `builder_walker` | config, environment, filesystem, process/runtime helpers |
-| Support | `builder_display`, `builder_stream`, `builder_template`, `builder_json_repair`, `builder_snaps`, `builder_brand`, `builder_tracker`, `builder_test_kit`, `builder_tool_macros` | formatting, streaming, templates, JSON repair, snapshots, branding/theming, version tracking, tests, tool macros |
-
-## Tool Surface
-
-The runtime tool catalog is file, shell, network-fetch, planning, skill, todo,
-and delegation oriented. Core tools:
-
-- `read`, `write`, `patch`, `multi_patch`, `undo`, `remove`
-- `fs_search`, `sem_search`
-- `shell`, `fetch`
-- `plan`, `skill`, `todo_read`, `todo_write`
-- `task` and dynamically registered agent tools
-
-The full catalog (`builder_domain/src/tools/catalog.rs`) also includes web
-search, memory, verification primitives, session/process control, and
-compaction tools. Security-session primitives, `flag_check`, and `explore` are
-all present on the same surface. Engagement metadata supplies context;
-permission and resource budgets constrain execution. Direct raw storage-query
-tooling is not part of the active runtime surface.
-
-## Verification And Completion
-
-Turn closure and mission closure are separate:
-
-```text
-provider terminal
-  -> TurnExit
-  -> TurnCompleted
-
-candidate outcome + trusted artifact
-  -> bind objective + target + verifier + artifact + freshness
-  -> MissionState::Verified
-  -> TaskComplete
-```
-
-The key rule is that a model response may finish a turn but cannot prove the
-mission. The former completion-adjudicator, semantic self-review, consensus
-panel, recovery synthesis, and hot-path replay export have been removed. A
-trusted verifier with explicit provenance is the only mission-promotion path;
-`flag_check` is the direct CTF fast path.
-
-## Diagnostic UI boundary
-
-The default TUI renders the response stream and deterministic input queue. It
-does not maintain a second workflow engine. `/status` consumes one immutable
-`RunStatusProjection`; `/workflow report` is the explicit offline export. The
-former bare `/workflow` alias has been removed. For an active run the projection
-adds exactly one optional canonical Lead-ledger read and immediately reduces it
-to `Option<AttentionBrief>`; raw nodes never cross the API boundary, an optional
-read failure only renders `BATTLEFIELD [UNAVAILABLE]`, and no Lead produces no
-battlefield rows. Core status read failures retain their existing error path.
-With no recorded run, `/status` still shows goal, manual/auto mode, queue, and
-usage without an evidence read. Recorded `TurnExit` and typed `MissionState` are
-shown separately so model Stop or run completion cannot appear as verified
-mission completion. The live status row deliberately remains limited to
-actionable progress/wait state: there is no frontier parsing, background refresh,
-write, dispatch shortcut, or hidden chrome state.
-
-Completed type-ahead inputs carry an explicit active-turn behavior. Safe
-inspection commands (`/info`, `/usage`, `/context`, `/memory`, `/status`,
-`/help`, `/skill`, and `/tools`) are atomically extracted and
-rendered without cancelling the response stream. State-changing and modal
-commands, including `/log` and `/model`, remain in FIFO order until the next safe turn
-boundary. `/new`, `/retry`, `/exit`, and explicit `/replace` retain interrupt
-semantics and take priority over active-turn query extraction. The input buffer
-rebuilds replay events after extraction so queued messages and the current draft
-preserve their original order and cursor. Esc cancellation preserves submitted
-queued input and starts its FIFO replay after stream cleanup; Ctrl+C remains the
-explicit clear-buffer interrupt. A conversation reset consumes `/new` but retains
-its FIFO tail for the new conversation. Modal prompts isolate that pre-existing
-tail from widget input and expose it again only after modal ownership ends.
-Commands that eventually open a modal keep the outer interrupt listener during
-their asynchronous prefetch and persistence phases. Before the widget starts,
-the terminal session requests a reader pause and waits for its acknowledgement;
-the reader resumes after modal ownership ends. Type-ahead is therefore buffered
-FIFO instead of racing or leaking into a later model, agent, or configuration
-field. Service-layer approval, secret, selection, and follow-up prompts acquire
-the same lifetime-bound modal handoff through the prompt-entry hook, and
-concurrent service prompts are serialized so two widgets never read stdin at
-once.
-
-`/resume` is the canonical saved-session selector; `/conversation` and
-`/conversations` remain compatibility aliases. The selector includes every
-conversation with persisted context, even when it has no title. Resuming a
-different conversation clears the process-local goal and forces auto mode off,
-so state from the previous session cannot drive the resumed one accidentally.
-`/new` applies the same process-local goal/auto reset at the fresh-session
-boundary while preserving the queued FIFO tail. Persisted titles are reduced to
-one bounded control-free selector row before that row is bound to its typed
-conversation ID. Local upserts stamp the activity time used by `/resume`,
-`--continue`, and `conversation resume <id>` ordering. The command remains
-FIFO-queued while a turn is active because its selector is a modal terminal
-owner.
-
-Normal `/exit` and empty-prompt Ctrl+D termination are serialized through the
-output actor. It rejects new writes, completes its current render batch, resets
-styles and terminal modes, restores the full scroll region, clears the tracked
-multiline footer, shows the cursor, disables raw mode, and drops the terminal
-surface before printing one plain saved-session message. The shutdown
-acknowledgement and actor join occur after that message, so no detached redraw
-can overwrite terminal cleanup. The generic `restore_terminal` function is a
-best-effort fallback for failures outside this coordinated path. An empty
-session reports that no resumable messages were created instead of promising a
-session that the repository intentionally excludes from the resume list.
-
-Typing `/` opens the complete registered command catalog. Search includes
-canonical names and aliases; Up/Down changes the selection, and Enter inserts
-the selected template into the editor for partial matches and commands that
-require arguments. A later Enter submits that populated input; a fully typed
-exact command that needs no expansion submits normally. Palette descriptions
-expose `[now]`, `[queued]`, and `[interrupt]` so the queue behavior is visible
-before submission. The selected entry is rendered as the first hint row so it
-remains visible when the terminal can show only a constrained input viewport.
-
-## Distribution — single source, two surfaces
-
-Pentesting and Builder share the **same Rust runtime binary**. The `pentesting`
-npm package is a thin distribution facade:
-
-```text
-npm install -g pentesting
-         │
-         ▼
-  pentesting CLI (Node.js shim)
-         │  resolves or downloads the matching Builder release asset
-         ▼
-  Builder binary (Rust)  ← single runtime engine
-         │  PENTESTING_PRODUCT_NAME=pentesting
-         ▼
-  Interactive TUI with "pentesting" banner
-```
-
-- The npm package installs a launcher, **not** a second agent runtime.
-- It resolves or downloads the correct release asset from
-  `agnusdei1207/pentesting-public`.
-- It forwards arguments directly into the Rust binary — no command translation
-  or compatibility shims.
-- If a change would add orchestration, memory, or prompt logic into the npm
-  layer, that change belongs upstream in the Rust runtime.
-
-## Supported Runtime Targets
-
-The npm launcher currently resolves a managed native release asset for Linux
-x64. Docker is the recommended runtime on Windows and macOS. Published Docker
-images support `linux/amd64` only; Apple Silicon Macs use Docker Desktop's amd64
-emulation. Native ARM64 images and binaries are not supported. Advanced users
-may set `PENTESTING_BIN` to a locally supplied compatible binary.
-
-| OS | CPU | Release asset |
-| --- | --- | --- |
-| Linux | x64 | `pentesting-x86_64-unknown-linux-musl` |
-
-`/update` (and the npm postinstall) resolves the matching asset for the current
-supported OS/CPU target from `agnusdei1207/pentesting-public`.
-
-## Build containment boundary
-
-Compilation is outside the application runtime boundary and is always executed
-through resource-capped Docker wrappers. Host Cargo is not an emergency
-fallback. `dbuild.sh` owns individual Cargo commands, `dverify.sh` owns
-sequential gate profiles, and `dbuild-image.sh` owns BuildKit. Each path shares
-storage admission, effective-limit inspection, a machine-wide lock, watchdogs,
-and structured failure reports. Automated CI/CD is disabled; maintainers invoke
-these wrappers explicitly. The
-normative contract is [Docker-only build safety](https://github.com/agnusdei1207/pentesting/blob/main/docs/BUILD_SAFETY.md).
-
-Patch publication performs one Cross build. The version-checked, checksummed
-AMD64 musl artifact is uploaded to GitHub and packaged into Docker from a
-minimal context; its dependency cache stays in a versioned Docker volume.
-
-The measured next-stage simplification and deletion plan is indexed at
-[Minimal Core plan](https://github.com/agnusdei1207/pentesting/blob/main/docs/plans/2026/07/10/minimal-core/README.md).
-The concrete PTY actor, unified security-tool surface, turn-trajectory, and dead-path reduction is
-recorded in [the 2026-07-10 implementation report](docs/plans/2026/07/10/IMPLEMENTATION_LightweightCoreRefactor_2026-07-10.md).
-
-## Configuration
-
-Pentesting reads a user-global config from `~/.pentesting/.pentesting.toml`,
-overridden by project-local `.pentesting.toml` files discovered by walking up
-from the working directory. Local storage is the default; normal setup only
-needs the public model endpoint environment.
-
-The full file shape is represented in `builder.schema.json`; common runtime and
-CTF fields are editable through `/config`. Set `PENTESTING_CONFIG` to override
-the global config directory.
-
-| Variable | Description |
-| --- | --- |
-| `OPENAI_API_KEY` | API key or gateway token for OpenAI-compatible providers. |
-| `OPENAI_BASE_URL` | OpenAI-compatible base URL, for example `https://api.openai.com/v1` or a self-hosted gateway. |
-| `OPENAI_MODEL` | Default model id. |
-| `OPENAI_MAX_TOKENS` | Optional output-token override; accepts values like `4096`, `32k`, or `1M`. |
-| `PENTESTING_BIN` | Use an already-installed Builder binary instead of the managed download. |
-| `PENTESTING_PRODUCT_NAME` | Runtime banner label. The `pentesting` launcher sets this to `pentesting` automatically. |
-| `PENTESTING_REPO` | Override the public release repo used for binary downloads. Defaults to `agnusdei1207/pentesting-public`. |
-| `PENTESTING_SKIP_DOWNLOAD` | Skip the postinstall binary download. Useful in CI or when `PENTESTING_BIN` will be provided later. |
-| `PENTESTING_CONFIG` | Override the global config directory. |
-
-### Canonical configuration contract
-
-The next-generation runtime accepts one product namespace. Configuration uses
-`PENTESTING_*`, `~/.pentesting/.pentesting.toml`, and project-local
-`.pentesting.toml`. `BUILDER_*`, `.builder.toml`, `.builder/`, JSON config
-fallbacks, and runtime alias translation have been removed. Existing users must
-move data explicitly before upgrading; the runtime does not carry a permanent
-old/new branch.
-
-## Interactive Commands
-
-Inside an interactive session, these commands inspect and drive runtime state
-(`/help` lists the full set):
-
-```text
-/status        Show goal/mode/queue, turn vs mission, run gates, budgets, and a bounded read-only battlefield
-/workflow report
-               Export the active run, engagement metadata, evidence, and large outputs to Markdown
-/context       Show recent context-budget snapshots for the current conversation
-/memory        Show stored conversation memories for the current conversation
-/tools         List the currently available tools and schemas
-/agent         Switch the active agent
-/resume        Resume a saved session for the active workspace
-/goal <task>   Set the active goal without enabling autonomous mode
-/auto          Toggle autonomous mode for the current goal (default: off; Esc stops it)
-/update        Download and apply the latest public release asset for supported native targets
-/help          Show all commands
-/exit          Save the session, restore the terminal, and quit
-```
-
-## Security Domain Skills
-
-Six built-in skills ship with the runtime: `create-skill`, `execute-plan`,
-`github-pr-description`, `ctf-competition`, `pentesting-methodology`, and
-`write-report`. For authorized security work, `ctf-competition` covers callback
-delivery agility, reliable payload/tool delivery, and interpreter-aware
-execution; `pentesting-methodology` maps assessments to standard frameworks;
-and `write-report` turns preserved evidence into reproducible CTF and
-penetration-test writeups.
-
-- **PTES** (Penetration Testing Execution Standard)
-- **MITRE ATT&CK** tactics and techniques
-- **OWASP** Top 10 and Testing Guide
-- **CWE/CAPEC** weakness and attack pattern catalogs
-- **NIST CSF** and **CIS Controls**
-
-### Shell listener for authorized labs
-
-```bash
-pentesting shell-listener --bind 127.0.0.1 --port 4444 --extra-ports 8443,9001
-```
-
-Up to 32 unique primary/additional ports bind concurrently and share one monotonic
-session-id sequence; an unavailable port is skipped as long as at least one
-requested port binds. `shell-session --json health` reports the active bound
-endpoints so callback selection can be evidence-based. The remote-bind safety
-gate remains unchanged.
-
-Manages multiple accepted TCP sessions with per-session routing, buffered
-output, raw byte logging, full-duplex transcripts, command history, attach /
-detach events, replay, and evidence manifests. `probe` records the remote's
-current shell interpreter in `shell`, detected only from `/proc/$$/exe` and
-`$0`, so a BusyBox `sh` target is not confused with an installed Bash. This
-interpreter axis is separate from TTY/`pty_state`; it is stored in session state,
-the `shell-session --json` projection, session snapshots, and evidence manifests,
-and is restored after a listener restart. `pty-upgrade` sends one concrete
-helper only; `upgrade` runs a helper plus a probe and records `pty_state` as
-verified or failed. Explicit `technique=auto` adds a bounded listener-side state
-machine: framed capability recon, allowlisted `bash`/`sh` selection, ordered
-helper attempts (`python3`, `python`, `python2`, `script`, `expect`), generic
-prompt observation, and phase-local probe verification. Only unavailable,
-early-returned, or completed-but-unverified attempts advance to the next
-candidate; timeout, disconnect, or writer failure stops without blind input.
-The entire operation keeps one command id, deadline, session lease, ledger, and
-final response. There is still no silent default: omission is rejected, manual
-techniques keep their single-attempt behavior, and custom text remains the
-escape hatch for unusual targets. Raw logs and transcripts are capped per session and closed sessions
-are archived automatically so a noisy peer cannot grow memory or disk without
-bound. Secret redaction is applied before new raw/transcript/display records are
-written; it is not retroactive for output that arrived before the secret value
-was registered. Bound to loopback by default; `--allow-remote` is an explicit
-opt-in gate.