feat(config): persist durable runtime settings (#178)

* feat(config): persist durable runtime settings

Move transcript capture settings and forge scoped identity onto the project config surface while preserving environment variables as per-invocation overrides. Propagate the resolved forge identity and transcript settings into launched agent and MCP processes so config-only projects carry their runtime context locally.\n\nRefs #177

* fix(config): forward default forge identity

Author: pentaxis93

ARCHITECTURE.md

@@ -26,13 +26,13 @@ These are library capabilities exposed by libagent and consumed by both the CLI
 
 6. **Protocol selection.** `selection::discover_ready_candidates` evaluates protocols in topological order under an explicit `EvaluationScope`. `EvaluationScope::Unscoped` evaluates only protocols with `scoped = false` and always uses `work_unit = None`. `EvaluationScope::Scoped(id)` evaluates only protocols with `scoped = true` for that exact delegated work unit. Readiness no longer discovers sibling work units from artifact instances. Current work is suppressed only when outputs are valid and trusted plus either: the current freshness-relevant input snapshot matches the last successful execution record for that `(protocol, work_unit)` pair, or no execution record exists and the timestamp fallback still shows outputs newer than all relevant inputs. Execution-record snapshots are mode-aware: `on_change`/`on_invalid` preserve any recorded matching instance, while `on_artifact` and `requires` compare only valid instances. The timestamp fallback still considers the latest recorded modification across relevant inputs.
 
-7. **Scoped work-unit identity validation.** After workspace scan and before scoped readiness evaluation, `runa state`, `runa step`, `runa run`, and `runa go` validate that the supplied `--work-unit` exactly matches a recorded `work-unit` instance id when any are recorded. Invalid and malformed recorded roots still establish canonical ids. Valid tracker-backed roots also enforce instance-id/handle number agreement, duplicate tracker-root rejection, and agreement with the active `GROUNDWORK_*` deployment identity. With no recorded `work-unit` roots, scoped evaluation remains inert.
+7. **Scoped work-unit identity validation.** After workspace scan and before scoped readiness evaluation, `runa state`, `runa step`, `runa run`, and `runa go` validate that the supplied `--work-unit` exactly matches a recorded `work-unit` instance id when any are recorded. Invalid and malformed recorded roots still establish canonical ids. Valid tracker-backed roots also enforce instance-id/handle number agreement, duplicate tracker-root rejection, and agreement with the active forge deployment identity resolved from `.runa/config.toml` with `GROUNDWORK_FORGE_*` env overrides. With no recorded `work-unit` roots, scoped evaluation remains inert.
 
 8. **Tracing bootstrap.** Both binaries bootstrap tracing with env/default settings before any config lookup, then reconfigure the shared subscriber from `config.toml` when logging settings are available. Tracing events always go to stderr; operator-facing command output stays on stdout.
 
 9. **Status and session evaluation.** `status::evaluate_protocols` is the shared readiness classification path used by CLI state reporting and MCP session readiness. `session::SessionState` layers current-step lifecycle state over that evaluator for scoped sessions: every public operation scans first, immediately revalidates the scoped work-unit identity for the session, readiness preserves an existing current step but may select the first ready step when none is active, exhausted work is reopened by the same relevant-input-change rule used by the live runner, and only `advance` retires the current step after postcondition enforcement, next-step validation, and execution-record persistence.
 
-10. **CLI execution commands.** `runa state`, `runa step`, `runa run`, and `runa go` share the same scope-resolved topology, readiness evaluation, and scope handling. Without `--work-unit`, commands evaluate only unscoped protocols; with `--work-unit <ID>`, they evaluate only scoped protocols for that delegated work unit after canonical identity validation. `step --dry-run` previews only the next concrete execution, while `run --dry-run` projects the full optimistic cascade to quiescence from declared `produces` outputs plus already-known required output choice branches within that same scope and scope-filtered execution order; optional `may_produce` outputs do not advance the projection unless they already exist, and required output choice branches are not synthesized unless exactly one member already exists. Live execution targets Linux. Live `step` executes exactly one ready candidate through fixed-protocol MCP, then re-scans and prints the refreshed state. Live `run` repeats the execute → scan → enforce → re-evaluate cycle until quiescence, resolves its agent command from `--agent-command -- <argv...>` or `[agent].command` in config, reopens exhausted work when a later reconciliation changes relevant inputs, and exits with outcome-specific status codes. Live `go` launches the configured agent with `runa-mcp --session --work-unit <ID>`, sends a generic one-tick prompt, and verifies that the selected session step recorded execution through the session surface. Before launching an agent, live execution builds a `runa-mcp` config, exports it through `RUNA_MCP_CONFIG`, and launches the configured argv unmodified; runtime-specific MCP adaptation belongs to the runtime or adapter. When `RUNA_TRANSCRIPT_DIR` is set, live execution also appends structured transcript events for the rendered prompt, agent stdout/stderr, and exit status.
+10. **CLI execution commands.** `runa state`, `runa step`, `runa run`, and `runa go` share the same scope-resolved topology, readiness evaluation, and scope handling. Without `--work-unit`, commands evaluate only unscoped protocols; with `--work-unit <ID>`, they evaluate only scoped protocols for that delegated work unit after canonical identity validation. `step --dry-run` previews only the next concrete execution, while `run --dry-run` projects the full optimistic cascade to quiescence from declared `produces` outputs plus already-known required output choice branches within that same scope and scope-filtered execution order; optional `may_produce` outputs do not advance the projection unless they already exist, and required output choice branches are not synthesized unless exactly one member already exists. Live execution targets Linux. Live `step` executes exactly one ready candidate through fixed-protocol MCP, then re-scans and prints the refreshed state. Live `run` repeats the execute → scan → enforce → re-evaluate cycle until quiescence, resolves its agent command from `--agent-command -- <argv...>` or `[agent].command` in config, reopens exhausted work when a later reconciliation changes relevant inputs, and exits with outcome-specific status codes. Live `go` launches the configured agent with `runa-mcp --session --work-unit <ID>`, sends a generic one-tick prompt, and verifies that the selected session step recorded execution through the session surface. Before launching an agent, live execution builds a `runa-mcp` config, exports it through `RUNA_MCP_CONFIG`, injects config-resolved transcript and forge identity environment into both the agent process and MCP config, and launches the configured argv unmodified; runtime-specific MCP adaptation belongs to the runtime or adapter. When transcript capture is enabled by config or `RUNA_TRANSCRIPT_DIR`, live execution also appends structured transcript events for the rendered prompt, agent stdout/stderr, and exit status.
 
 11. **MCP runtime loop.** In fixed-protocol mode, `runa-mcp` parses `--protocol` and optional `--work-unit`, loads the project, scans the workspace, resolves the named protocol from the manifest, validates declared scope and canonical work-unit identity against the provided arguments, validates that its outputs can be served as MCP tools, and serves output tools via stdio. In session mode, `runa-mcp --session --work-unit <ID>` opens a scoped `SessionState`, advertises driver tools plus current-step output tools, and emits `notifications/tools/list_changed` whenever a session verb changes the current step and therefore the advertised output tools. When transcript capture is enabled, tool calls and tool results are appended to the same JSONL stream as CLI execution events.
 
@@ -94,7 +94,7 @@ Returns `EnforcementError` on failure, containing the protocol name, enforcement
 
 ### `project.rs`
 
-Shared project loading logic used by both `runa-cli` and `runa-mcp`. Config resolution chain (explicit override → `.runa/config.toml` → XDG config → error), config parsing for logging plus optional agent execution command, manifest parsing, dependency graph construction, and artifact store initialization.
+Shared project loading logic used by both `runa-cli` and `runa-mcp`. Config resolution chain (explicit override → `.runa/config.toml` → XDG config → error), config parsing for logging, optional agent execution command, transcript defaults, and forge identity defaults, manifest parsing, dependency graph construction, and artifact store initialization.
 
 ### `selection.rs`
 
@@ -122,7 +122,7 @@ Canonical scoped work-unit identity validation shared by CLI commands and
 including invalid and malformed records. Valid tracker-backed roots receive the
 runtime checks that schema validation cannot express: id/handle number
 agreement, duplicate tracker identity detection, and active deployment
-agreement from `GROUNDWORK_*` atoms.
+agreement from config-resolved `GROUNDWORK_FORGE_*` atoms.
 
 ## runa-mcp Modules
 
@@ -142,7 +142,7 @@ output-tool surface.
 
 ```
 .runa/
-  config.toml                   # Created by `runa init`: methodology_path, optional logging, optional agent.command
+  config.toml                   # Created by `runa init`: methodology_path, optional logging, agent.command, transcript, forge defaults
   state.toml                    # Created by `runa init`: initialized_at, runa_version
   workspace/                    # Artifact workspace (non-configurable)
     {type_name}/
@@ -157,11 +157,11 @@ output-tool surface.
 
 Commands that operate on a loaded methodology share `project::load`, which resolves the config file, reads the methodology path from it, parses the manifest, builds the dependency graph, and opens the artifact store.
 
-Config resolution is whole-file (first found wins, no per-field merging): `--config` CLI flag → `RUNA_CONFIG` env var → `.runa/config.toml` → `$XDG_CONFIG_HOME/runa/config.toml` → error.
+Config resolution is whole-file (first found wins, no per-field merging): `--config` CLI flag → `RUNA_CONFIG` env var → `.runa/config.toml` → `$XDG_CONFIG_HOME/runa/config.toml` → error. Within the selected file, durable transcript and forge settings are field-level defaults that matching environment variables override for one invocation.
 
 ### `runa init --methodology <PATH> [--config <PATH>]`
 
-Parses the manifest at `<PATH>` via `libagent::manifest::parse`, canonicalizes the path, creates `.runa/config.toml` (or writes to the `--config` path) containing the canonical methodology path plus optional logging settings and optional agent execution settings. Creates `.runa/state.toml`, `.runa/store/`, and the fixed artifact workspace directory at `.runa/workspace/`. Reports the artifact type and protocol counts on success.
+Parses the manifest at `<PATH>` via `libagent::manifest::parse`, canonicalizes the path, creates `.runa/config.toml` (or writes to the `--config` path) containing the canonical methodology path plus optional logging, agent execution, transcript, and forge settings. Creates `.runa/state.toml`, `.runa/store/`, and the fixed artifact workspace directory at `.runa/workspace/`. Reports the artifact type and protocol counts on success.
 
 ### `runa list`
 

CHANGELOG.md

@@ -9,6 +9,10 @@ Semantic Versioning.
 
 ### Changed
 
+- Durable transcript capture settings and scoped forge identity can now live in
+  `.runa/config.toml`, with `RUNA_TRANSCRIPT_*` and `GROUNDWORK_FORGE_*`
+  environment variables retained as per-invocation overrides. Resolved forge
+  identity is forwarded into launched agent and MCP environments.
 - Live agent launch is now agent-agnostic. A command named `claude` is no
   longer launched with injected `--mcp-config` / `--strict-mcp-config` flags;
   it receives the MCP session config through `RUNA_MCP_CONFIG` like every other

README.md

@@ -167,6 +167,14 @@ Both projects are in early development.
 
 See [CLI Reference](docs/cli-reference.md) for flags, exit codes, configuration, and behavioral details.
 
+## Configuration
+
+`runa init` creates `.runa/config.toml` with the methodology path. Operators
+may also set durable project defaults there for live agent command,
+transcript capture, and scoped forge identity. Environment variables such as
+`RUNA_TRANSCRIPT_DIR` and `GROUNDWORK_FORGE_*` remain per-invocation overrides;
+config is the project-local default.
+
 ## Build
 
 Rust 2024 edition. Runa targets Linux.

docs/cli-reference.md

@@ -13,6 +13,38 @@ Commands that load a methodology share a common config resolution chain. The fir
 
 For `runa init`, `--config` controls where the config file is written. For all other commands, it controls where the config file is read from.
 
+### Durable Project Settings
+
+Durable project settings live in `.runa/config.toml`. Environment variables
+with matching runtime meaning remain per-invocation overrides.
+
+```toml
+[transcript]
+dir = "transcripts"
+redact_env = ["SECRET_TOKEN", "API_KEY"]
+
+[forge]
+type = "github"
+owner = "tesserine"
+name = "runa"
+tracker_id = "4"
+```
+
+`[transcript].dir` enables transcript capture and is resolved relative to the
+project directory when it is not absolute. `RUNA_TRANSCRIPT_DIR` overrides it
+for one invocation. `[transcript].redact_env` names environment variables whose
+current values should be redacted from transcript events.
+`RUNA_TRANSCRIPT_REDACT_ENV`, when set to a comma-separated list, overrides the
+configured list.
+
+`[forge]` supplies the active scoped work-unit deployment identity. Runa uses
+it when validating tracker-backed `work-unit` roots and injects the resolved
+`GROUNDWORK_FORGE_TYPE`, `GROUNDWORK_FORGE_OWNER`, `GROUNDWORK_FORGE_NAME`, and
+`GROUNDWORK_FORGE_TRACKER_ID` values into launched agent and MCP environments.
+Any non-empty matching `GROUNDWORK_FORGE_*` environment variable overrides the
+configured field for that invocation. The forge type still defaults to `github`
+when neither config nor env specifies one.
+
 ### Logging
 
 Runtime diagnostics use `tracing` on stderr. Command output stays on stdout.
@@ -51,14 +83,15 @@ payload containing the resolved `runa-mcp` command, arguments, and environment
 child process. Runtime-specific translation, such as wrapping that payload in a
 client-specific config file, belongs to the runtime or adapter, not to runa.
 
-When `RUNA_TRANSCRIPT_DIR` is set, live execution appends JSON Lines transcript
-events to `$RUNA_TRANSCRIPT_DIR/events.jsonl`. Events include protocol prompts,
+When transcript capture is enabled through `[transcript].dir` or
+`RUNA_TRANSCRIPT_DIR`, live execution appends JSON Lines transcript events to
+`events.jsonl` in the resolved directory. Events include protocol prompts,
 agent stdout/stderr chunks, agent exit status, and `runa-mcp` tool call/result
-events when the agent runtime launches the configured MCP server.
-`RUNA_TRANSCRIPT_REDACT_ENV` may name comma-separated environment variables;
-their current non-empty values are replaced with `[REDACTED:<name>]` before
-events are written. Hidden model reasoning and runtime-private provider events
-are outside runa's observable boundary.
+events when the agent runtime launches the configured MCP server. Configured or
+environment-supplied redaction names cause their current non-empty values to be
+replaced with `[REDACTED:<name>]` before events are written. Hidden model
+reasoning and runtime-private provider events are outside runa's observable
+boundary.
 
 ## Commands
 
@@ -291,10 +324,18 @@ resolves them from the local filesystem, so adapters do not depend on child
 process cwd to launch `runa-mcp`. Transcript environment variables are forwarded
 into the MCP config when transcript capture is enabled, which lets the MCP
 server append tool events to the same transcript stream as the CLI execution
-events.
+events. Configured forge identity is forwarded the same way through
+`GROUNDWORK_FORGE_*` entries so methodology tooling inside the agent session can
+use the project-local identity without user-global shell state.
 
 **Environment variables:**
 
 - `RUNA_WORKING_DIR` — Project directory. Defaults to the current directory.
 - `RUNA_CONFIG` — Config file override (same as `--config` in the CLI).
+- `RUNA_TRANSCRIPT_DIR` — Transcript directory override for one invocation.
+- `RUNA_TRANSCRIPT_REDACT_ENV` — Comma-separated transcript redaction-name
+  override for one invocation.
+- `GROUNDWORK_FORGE_TYPE`, `GROUNDWORK_FORGE_OWNER`, `GROUNDWORK_FORGE_NAME`,
+  `GROUNDWORK_FORGE_TRACKER_ID` — Forge identity field overrides for one
+  invocation.
 - `RUST_LOG` — Tracing filter override for stderr diagnostics.

libagent/src/lib.rs

@@ -49,13 +49,19 @@ pub use model::{
     ArtifactType, Manifest, ProtocolDeclaration, RequiredOutputChoice, TriggerCondition,
     UnscopedOutputRequiresWorkUnitError, validate_output_scope,
 };
-pub use project::{Config, LoadedProject, LogFormat, LoggingConfig, ProjectError, State};
+pub use project::{
+    Config, ForgeConfig, LoadedProject, LogFormat, LoggingConfig, ProjectError, State,
+    TranscriptConfig,
+};
 pub use projection::{ProjectionCandidate, ProjectionClass, project_cascade};
 pub use scan::{
     ArtifactRef, InvalidArtifact, MalformedArtifact, PartiallyScannedType, ScanError, ScanResult,
     UnreadableArtifact, scan,
 };
-pub use scoped_identity::{ScopedWorkUnitError, validate_scoped_work_unit};
+pub use scoped_identity::{
+    ScopedWorkUnitError, resolve_forge_environment, validate_scoped_work_unit,
+    validate_scoped_work_unit_with_env,
+};
 pub use selection::{
     Candidate, CandidateKey, CandidateStatus, ClassifiedCandidate, EvaluationScope,
     EvaluationTopology, ScanTrust, WaitingReason, classify_candidates,