feat: add terminal-shell engineer foundation

Specs/ProductArchitecture.md

@@ -53,7 +53,7 @@ For delivery purposes, v1 should be interpreted narrowly:
 
 - one primary engineer loop
 - one default local single-process deployment path, plus an explicit loopback multi-process operator path for supported base types
-- three builtin manifest-advertised base-type selections in the local scaffold: `local-harness`, `rusty-clawd`, and `copilot-sdk`, with `rusty-clawd` now behaving as a distinct session backend and `copilot-sdk` remaining an explicit alias of the local harness implementation
+- four builtin manifest-advertised base-type selections in the local scaffold: `local-harness`, `terminal-shell`, `rusty-clawd`, and `copilot-sdk`, with `terminal-shell` now providing a local PTY-backed shell path for the engineer identity, `rusty-clawd` behaving as a distinct session backend, and `copilot-sdk` remaining an explicit alias of the local harness implementation
 - one durable memory path
 - one small benchmark set
 
@@ -68,7 +68,7 @@ The following are hard constraints for the first implementation, not deferred as
 
 - **Dependency injection from the outset**: runtime composition must happen through explicit ports, traits, and typed configuration rather than hidden globals or direct construction buried inside the core loop.
 - **Distributed-readiness from the outset**: runtime, session, memory, and reflection contracts must not assume in-process execution even when the first deployment path is single-process.
-- **Multiple base types from the outset**: identity manifests and runtime selection logic must support multiple base types immediately. In the current v1 scaffold, `local-harness`, `rusty-clawd`, and `copilot-sdk` are all selectable builtin base types. `rusty-clawd` is now a distinct session backend, while `copilot-sdk` remains an explicit alias of the local single-process harness implementation.
+- **Multiple base types from the outset**: identity manifests and runtime selection logic must support multiple base types immediately. In the current v1 scaffold, `local-harness`, `terminal-shell`, `rusty-clawd`, and `copilot-sdk` are all selectable builtin base types for the engineer identity. `terminal-shell` is a local PTY-backed shell path, `rusty-clawd` is a distinct session backend, and `copilot-sdk` remains an explicit alias of the local single-process harness implementation.
 - **Visible failures from the outset**: unsupported capabilities, missing prompt assets, invalid lifecycle transitions, and unsupported topologies must fail explicitly through typed errors instead of silent fallbacks.
 
 ## Non-Goals
@@ -303,6 +303,7 @@ Candidate base types include:
 The current Simard scaffold already publishes builtin manifest-facing base-type identifiers for:
 
 - `local-harness`
+- `terminal-shell`
 - `rusty-clawd`
 - `copilot-sdk`
 

docs/howto/configure-bootstrap-and-inspect-reflection.md

@@ -28,7 +28,7 @@ Use this guide when you need to answer two questions:
 
 Provide the prompt root, objective, and state root yourself.
 
-For the builtin identities in this repo, the current scaffold accepts `local-harness`, `rusty-clawd`, or `copilot-sdk` as explicit base-type choices. `rusty-clawd` is a distinct session backend, while `copilot-sdk` remains an explicit alias of `local-harness`. The bootstrap path now injects either the in-process runtime services for `single-process` or the loopback mesh services for `multi-process`, so unsupported topology/base-type pairs fail explicitly instead of being rewritten.
+For the builtin identities in this repo, the current scaffold accepts `local-harness`, `rusty-clawd`, or `copilot-sdk` as explicit base-type choices everywhere, and `simard-engineer` additionally accepts `terminal-shell` for a real local PTY-backed shell session. `rusty-clawd` is a distinct session backend, `terminal-shell` is intentionally local-only, and `copilot-sdk` remains an explicit alias of `local-harness`. The bootstrap path now injects either the in-process runtime services for `single-process` or the loopback mesh services for `multi-process`, so unsupported topology/base-type pairs fail explicitly instead of being rewritten.
 
 ```bash
 SIMARD_PROMPT_ROOT="$PWD/prompt_assets" \
@@ -111,6 +111,8 @@ Builtin defaults are startup choices. They are not recovery behavior.
 - `agent_program_backend`
 - `handoff_backend`
 - `adapter_backend`
+- `adapter_capabilities`
+- `adapter_supported_topologies`
 - `topology_backend`
 - `transport_backend`
 - `supervisor_backend`
@@ -145,7 +147,7 @@ assert_eq!(snapshot.memory_backend.identity, "memory::json-file-store");
 assert_eq!(snapshot.evidence_backend.identity, "evidence::json-file-store");
 ```
 
-If you launched with `SIMARD_BASE_TYPE="copilot-sdk"`, `snapshot.selected_base_type` still shows the alias you chose while `snapshot.adapter_backend.identity` remains `local-harness`. If you launched with `SIMARD_BASE_TYPE="rusty-clawd"`, reflection truthfully reports `snapshot.adapter_backend.identity == "rusty-clawd::session-backend"`. Composite identities also surface `snapshot.identity_components` so operator tooling can see which roles were assembled.
+If you launched with `SIMARD_BASE_TYPE="copilot-sdk"`, `snapshot.selected_base_type` still shows the alias you chose while `snapshot.adapter_backend.identity` remains `local-harness`. If you launched with `SIMARD_BASE_TYPE="rusty-clawd"`, reflection truthfully reports `snapshot.adapter_backend.identity == "rusty-clawd::session-backend"`. If you launch the engineer identity with `SIMARD_BASE_TYPE="terminal-shell"`, reflection reports `snapshot.adapter_backend.identity == "terminal-shell::local-pty"`, `snapshot.adapter_capabilities` includes `terminal-session`, and `snapshot.adapter_supported_topologies == ["single-process"]`. Composite identities also surface `snapshot.identity_components` so operator tooling can see which roles were assembled.
 
 The same redaction rule applies to persisted session text: scratch memory, session summaries, and reflection summaries record `objective-metadata(...)` instead of the raw `SIMARD_OBJECTIVE` string.
 
@@ -176,6 +178,27 @@ Look for:
 
 This is the current honest v1 behavior: meeting mode captures structured planning output and writes concise decision memory, but it does not mutate code.
 
+## 6. Exercise the terminal-backed engineer path
+
+Use the operator probe when you want to validate the new terminal-backed engineer substrate directly:
+
+```bash
+cargo run --quiet --bin simard_operator_probe -- \
+  terminal-run single-process \
+  $'working-directory: .\ncommand: pwd\ncommand: printf "terminal-foundation-ok\\n"'
+```
+
+Look for:
+
+- `Probe mode: terminal-run`
+- `Selected base type: terminal-shell`
+- `Adapter implementation: terminal-shell::local-pty`
+- `Adapter capabilities: ... terminal-session`
+- `Terminal evidence: terminal-command-count=2`
+- a transcript preview containing `terminal-foundation-ok`
+
+This is the honest v1 terminal slice: Simard can drive a real local PTY-backed shell session through the runtime, but it does not claim remote hosts, Azlin orchestration, or distributed terminal control yet.
+
 ## 4. Validate stopped-state behavior
 
 Stopping the runtime is already observable.

docs/index.md

@@ -27,19 +27,19 @@ Today Simard provides:
 - explicit bootstrap configuration, with `builtin-defaults` available only through opt-in startup mode
 - a durable local state root selected through `SIMARD_STATE_ROOT` in `explicit-config` or defaulted through `builtin-defaults`
 - explicit base-type and topology selection at bootstrap, with opt-in defaults only in `builtin-defaults`
-- builtin manifest-advertised base types selectable at startup today: `local-harness`, `rusty-clawd`, and `copilot-sdk`, with `rusty-clawd` wired as a distinct session backend and `copilot-sdk` still aliased to the local harness implementation
+- builtin manifest-advertised base types selectable at startup today: `local-harness`, `terminal-shell`, `rusty-clawd`, and `copilot-sdk`, with `terminal-shell` wired as a real local PTY-backed shell session for `simard-engineer`, `rusty-clawd` wired as a distinct session backend, and `copilot-sdk` still aliased to the local harness implementation
 - builtin identities selectable at startup today: `simard-engineer`, `simard-meeting`, `simard-gym`, and the composite `simard-composite-engineer`
 - a facilitator-backed `simard-meeting` identity that captures structured decisions, risks, next steps, and open questions without mutating code
-- `single-process` for all builtin base types plus loopback `multi-process` execution for `rusty-clawd`, with unsupported pairs failing explicitly
+- `single-process` for all builtin base types plus loopback `multi-process` execution for `rusty-clawd`, with `terminal-shell` intentionally limited to local single-process runs and unsupported pairs failing explicitly
 - a starter benchmark gym suite that exercises all current builtin base-type selections plus a composite identity session through `cargo run --quiet --bin simard-gym -- run-suite starter`
 - benchmark artifacts written under `target/simard-gym/`, including per-scenario JSON and text summaries, a dedicated review artifact, and a suite summary
 - `ManifestContract { entrypoint, composition, precedence, provenance, freshness }`
-- `ReflectionSnapshot { manifest_contract, runtime_node, mailbox_address, agent_program_backend, adapter_backend, topology_backend, transport_backend, supervisor_backend, memory_backend, evidence_backend }`
+- `ReflectionSnapshot { manifest_contract, runtime_node, mailbox_address, agent_program_backend, adapter_backend, adapter_capabilities, adapter_supported_topologies, topology_backend, transport_backend, supervisor_backend, memory_backend, evidence_backend }`
 - truthful memory and evidence backend descriptors
 - file-backed memory, evidence, and handoff stores on the bootstrap path, with persisted local state under the configured state root
 - durable meeting decision records persisted under the configured state root so later sessions can inspect concise planning outcomes
 - offline review artifacts and concise decision records persisted under the configured state root when the operator runs the review probe
-- truthful runtime service metadata from the runtime-selected wiring, including the injected agent program, handoff store, and the canonical backend identities behind each selected base type
+- truthful runtime service metadata from the runtime-selected wiring, including the injected agent program, handoff store, the canonical backend identities behind each selected base type, and adapter capability/topology limits surfaced directly in reflection
 - persisted scratch, summary, and reflection text that records objective metadata instead of raw objective text
 - handoff snapshots that preserve runtime/session continuity while redacting the persisted session objective down to objective metadata
 - canonical session IDs shaped as `session-<uuid-v7>`, with validation at parsing boundaries

docs/reference/runtime-contracts.md

@@ -36,7 +36,7 @@ The stable contract in this repository is the bootstrap/runtime and benchmark-gy
 
 ## Meeting-mode operator flow
 
-The shipped operator probe also supports a meeting-specific path:
+The shipped operator probe also supports meeting-specific and terminal-session-specific paths:
 
 - `cargo run --quiet --bin simard_operator_probe -- meeting-run <base-type> <topology> <structured-objective>`
 - `cargo run --quiet --bin simard_operator_probe -- review-run <base-type> <topology> <objective>`
@@ -86,6 +86,7 @@ The shipped benchmark CLI currently supports:
 The starter suite is intentionally small and exercises:
 
 - `local-harness`
+- `terminal-shell`
 - `copilot-sdk`
 - `rusty-clawd`
 - the dedicated `simard-gym` identity
@@ -109,11 +110,12 @@ Artifacts are written under `target/simard-gym/` as JSON and text reports plus a
 
 ### Current builtin base-type registrations
 
-The builtin identities currently advertised by the loader are `simard-engineer`, `simard-meeting`, `simard-gym`, and the composite `simard-composite-engineer`. Their common builtin base-type registrations are:
+The builtin identities currently advertised by the loader are `simard-engineer`, `simard-meeting`, `simard-gym`, and the composite `simard-composite-engineer`. All of them accept `local-harness`, `rusty-clawd`, and `copilot-sdk`; `simard-engineer` additionally accepts `terminal-shell` for the local terminal-backed path:
 
 | Base type selection | Current session backend implementation | Supported topologies in this scaffold |
 | --- | --- | --- |
 | `local-harness` | `local-harness` single-process local process harness session backend | `single-process` |
+| `terminal-shell` | `terminal-shell::local-pty` real local PTY-backed shell session backend (`simard-engineer` only) | `single-process` |
 | `rusty-clawd` | `rusty-clawd::session-backend` real session backend | `single-process`, `multi-process` |
 | `copilot-sdk` | `local-harness` single-process local process harness session backend (alias) | `single-process` |
 
@@ -124,8 +126,8 @@ Notes:
 - for `multi-process` and `distributed`, bootstrap injects `topology::loopback-mesh`, `transport::loopback-mailbox`, and `supervisor::coordinated`
 - unsupported topology/base-type pairs still fail explicitly; for example, `local-harness + multi-process` returns `UnsupportedTopology`
 - if a future identity advertises a base type without a registered factory, runtime composition still fails explicitly with `AdapterNotRegistered`
-- the descriptors remain truthful: `selected_base_type` preserves the explicit choice, while `adapter_backend.identity` exposes the actual backend (`rusty-clawd::session-backend` for `rusty-clawd`, `local-harness` for the current `copilot-sdk` alias)
-- `runtime_node`, `mailbox_address`, `topology_backend`, `transport_backend`, `supervisor_backend`, and `handoff_backend` expose the actual runtime assembly rather than inferred labels
+- the descriptors remain truthful: `selected_base_type` preserves the explicit choice, while `adapter_backend.identity` exposes the actual backend (`terminal-shell::local-pty` for `terminal-shell`, `rusty-clawd::session-backend` for `rusty-clawd`, `local-harness` for the current `copilot-sdk` alias)
+- `runtime_node`, `mailbox_address`, `adapter_capabilities`, `adapter_supported_topologies`, `topology_backend`, `transport_backend`, `supervisor_backend`, and `handoff_backend` expose the actual runtime assembly rather than inferred labels
 - `MemoryPolicy.allow_project_writes=true` is rejected explicitly in v1 rather than being ignored
 
 ### Bootstrap modes
@@ -339,6 +341,8 @@ pub struct ReflectionSnapshot {
     pub agent_program_backend: BackendDescriptor,
     pub handoff_backend: BackendDescriptor,
     pub adapter_backend: BackendDescriptor,
+    pub adapter_capabilities: Vec<String>,
+    pub adapter_supported_topologies: Vec<String>,
     pub topology_backend: BackendDescriptor,
     pub transport_backend: BackendDescriptor,
     pub supervisor_backend: BackendDescriptor,

docs/tutorials/run-your-first-local-session.md

@@ -32,7 +32,7 @@ This tutorial follows the runtime path that exists in the repository today.
 
 From the repository root, start Simard with a real prompt asset directory, an explicit objective, and an explicit durable state root.
 
-For the builtin identities in this repo, you can currently choose `local-harness`, `rusty-clawd`, or `copilot-sdk` here. `rusty-clawd` is a distinct backend, while `copilot-sdk` remains an explicit alias of the local harness implementation. The default bootstrap path still opts into `single-process`, but the runtime can now inject a loopback `multi-process` topology when you request a supported pairing such as `rusty-clawd + multi-process`.
+For the builtin identities in this repo, you can currently choose `local-harness`, `rusty-clawd`, or `copilot-sdk` everywhere, and `simard-engineer` additionally accepts `terminal-shell` for a real local PTY-backed shell session. `rusty-clawd` is a distinct backend, `terminal-shell` is intentionally local-only, and `copilot-sdk` remains an explicit alias of the local harness implementation. The default bootstrap path still opts into `single-process`, but the runtime can now inject a loopback `multi-process` topology when you request a supported pairing such as `rusty-clawd + multi-process`.
 
 ```bash
 SIMARD_PROMPT_ROOT="$PWD/prompt_assets" \
@@ -83,6 +83,27 @@ Adapter implementation: local-harness
 
 **Checkpoint**: the runtime contract is explicit. `copilot-sdk` is selectable now, but its underlying implementation still stays `local-harness`. Simard preserves the selected base type without pretending the alias is already a distinct backend integration.
 
+### Variation: exercise the terminal-backed engineer path
+
+Use the shipped operator probe to drive a real local PTY-backed shell session through the runtime:
+
+```bash
+cargo run --quiet --bin simard_operator_probe -- \
+  terminal-run single-process \
+  $'working-directory: .\ncommand: pwd\ncommand: printf "terminal-foundation-ok\\n"'
+```
+
+Look for these lines:
+
+```text
+Probe mode: terminal-run
+Selected base type: terminal-shell
+Adapter implementation: terminal-shell::local-pty
+Terminal evidence: terminal-command-count=2
+```
+
+**Checkpoint**: this path is no longer synthetic. The runtime is actually allocating a local PTY-backed shell session and preserving a transcript preview in evidence, while still honestly limiting the feature to local single-process execution.
+
 ## Step 3: Exercise a composite identity and loopback multi-process runtime
 
 Use the shipped operator probe to validate the broader runtime seams like an operator would.