kanibako-cli 1.6.0.dev36__tar.gz → 1.7.0__tar.gz

{kanibako_cli-1.6.0.dev36/src/kanibako_cli.egg-info → kanibako_cli-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kanibako-cli
-Version: 1.6.0.dev36
+Version: 1.7.0
 Summary: Run AI coding agents in rootless containers with per-project isolation
 Requires-Python: >=3.11
 License-File: LICENSE.md

{kanibako_cli-1.6.0.dev36 → kanibako_cli-1.7.0}/README.md

@@ -13,6 +13,9 @@ agent sessions that survive reboots and SSH disconnects.
 
 CRAB: **C**ontained **R**untime **A**gent in a **B**ox.
 
+New here? Start with [GETTING_STARTED.md](GETTING_STARTED.md) for a five-minute
+walkthrough from install to your first agent session.
+
 No Docker or Podman experience required.  Just `cd` into a project and run
 `kanibako`.  Setup, rig pulls, credential syncing, and teardown are automatic.
 Claude Code, Codex, and Goose ship as first-class agent plugins (all installed
@@ -39,12 +42,12 @@ by the `kanibako` meta-package); other agents can be added as plugins.
 - **Vault snapshots** -- per-box read-only and read-write shared
   directories with smart snapshot strategy detection (reflink, hardlink,
   or tar.xz depending on filesystem)
-- **Shell customization** -- per-box environment variables (`box config
+- **Shell customization** -- per-box environment variables (`box set
   env.*`), drop-in init scripts (`shell.d/`), and layered seed-once home
   templates
 - **Agent configuration** -- per-agent YAML config with default args, state
   knobs, env vars, and shared caches; per-box setting overrides via
-  `box config`
+  `box set`
 - **Shared caches** -- global download caches (pip, cargo, npm, etc.)
   shared across boxes; agent-level caches via the agent config
 - **Plugin system** -- agent-agnostic core (`kanibako-cli`); Claude/Codex/Goose
@@ -60,21 +63,26 @@ by the `kanibako` meta-package); other agents can be added as plugins.
 ## Prerequisites
 
 - Python 3.11+
-- [Podman](https://podman.io/) (recommended) or Docker -- just needs to be
+- [Podman](https://podman.io/) 4.3+ (recommended) or Docker -- just needs to be
   installed; Kanibako manages all container operations automatically
 - An AI coding agent installed on the host (e.g.
   [Claude Code](https://docs.anthropic.com/en/docs/claude-code))
 
 ## Installation
 
+> **Pre-release:** the current line (`1.7.0`) is still in release candidates, so
+> add `--pre` (pip/pipx) or `--prerelease allow` (uv) to get the newest rc. Plain
+> `pip install kanibako` gets the last *stable* release (`1.6.0`). Once `1.7.0`
+> ships, drop the flag.
+
 ```bash
-# Standard install (cli + Claude, Codex, and Goose plugins)
-uv tool install kanibako
+# Standard install (cli + Claude, Codex, and Goose plugins) -- current rc
+uv tool install --prerelease allow kanibako
 # -- or --
-pip install kanibako
+pip install --pre kanibako
 
 # Base only (no agent plugins -- agent-agnostic shell mode)
-pip install kanibako-cli
+pip install --pre kanibako-cli
 
 # Development install
 git clone https://github.com/doctorjei/kanibako.git
@@ -92,8 +100,11 @@ it is used automatically. See [Agent Selection](#agent-selection).
 ## Quick Start
 
 ```bash
-# Start an agent session in the current directory
+# Create a box for the current directory (a deliberate, one-time step)
 cd ~/my-project
+kanibako create
+
+# Start an agent session (shortcut for `kanibako start`)
 kanibako
 
 # Start with a specific rig
@@ -109,10 +120,11 @@ kanibako shell -- echo hello
 kanibako -N
 ```
 
-That's it -- no `docker run`, no volume flags, no Containerfile.  On first run,
-Kanibako automatically pulls the container rig, sets up the project
-environment, and syncs your credentials.  Subsequent runs pick up where you
-left off.
+That's it -- no `docker run`, no volume flags, no Containerfile.  Creating a box
+is an explicit step (`kanibako create`); a launch (`kanibako` / `start` / `code` /
+`shell`) never invents a box, so a typo'd project or wrong directory can't
+silently make one.  On the first launch of a box, Kanibako pulls the container
+rig and syncs your credentials; subsequent runs pick up where you left off.
 
 ## Example: Python Project
 
@@ -121,21 +133,24 @@ gh, nano, jq, ripgrep, tmux, Podman, and common dev tools.  This is enough for
 most Python, JavaScript, and general scripting work.
 
 ```bash
-# 1. Install kanibako
-pip install kanibako
+# 1. Install kanibako (--pre while 1.7.0 is in rc; see Installation)
+pip install --pre kanibako
 
 # 2. Create or clone a project
 mkdir ~/my-flask-app && cd ~/my-flask-app
 git init
 # (or: git clone https://github.com/you/my-flask-app.git && cd my-flask-app)
 
-# 3. Launch -- that's it
+# 3. Create the box for this project (explicit, one-time)
+kanibako create
+
+# 4. Launch -- that's it
 kanibako
 ```
 
-On the first launch, Kanibako will:
+`kanibako create` sets up an isolated environment for this project.  On the
+first launch, Kanibako will:
 - Pull the base container rig (once, cached afterwards)
-- Create an isolated environment for this project
 - Copy your agent credentials into the sandbox
 - Drop you into an agent session inside the container
 
@@ -161,20 +176,23 @@ toolchains you need:
 kanibako rig prep systems
 # (or build one interactively with: kanibako rig extend my-systems --from kanibako-oci)
 
-# 2. Use it for your project
+# 2. Create the box for your project, pinned to that rig (explicit, one-time)
 cd ~/my-rust-project
-kanibako --image kanibako-template-systems
+kanibako create --image kanibako-template-systems
+
+# 3. Launch
+kanibako
 ```
 
-After the first run, Kanibako remembers the rig choice for this project,
-so you can just run `kanibako` next time.
+`kanibako create` pins the rig choice for this project, so you can just run
+`kanibako` next time.
 
 See [Container Rigs](#container-rigs) for the base rigs and custom rig
 creation.
 
 ## Commands
 
-Kanibako organizes commands into four management groups plus seven top-level
+Kanibako organizes commands into four management groups plus eight top-level
 shortcuts for common operations:
 
 ### Top-Level Shortcuts
@@ -188,6 +206,7 @@ shortcuts for common operations:
 | `kanibako ps [-a] [-q]` | `box ps` | List active (running) boxes |
 | `kanibako create [path]` | `box create` | Create a new project |
 | `kanibako rm <project>` | `box rm` | Remove a project |
+| `kanibako code [project]` | *(top-level only)* | Open VS Code attached to the box (see [VS Code Integration](#vs-code-integration)) |
 
 ### Management Commands
 
@@ -220,7 +239,7 @@ shortcuts for common operations:
 | `box list` / `box ls` | List projects (`--all`, `--orphan`, `-q`) |
 | `box info` / `box inspect` | Project details (mode, paths, lock, rig) |
 | `box rm` / `box delete` | Remove project (`--purge` deletes metadata, `--force` skips confirm) |
-| `box config` | View or modify project configuration |
+| `box set` / `box get` / `box show` / `box reset` | View or modify project configuration |
 | `box diagnose [project]` | Check project box health |
 
 **Relocation & conversion:**
@@ -265,7 +284,7 @@ shortcuts for common operations:
 | `workset list` / `workset ls` | List working sets (`-q`) |
 | `workset info` / `workset inspect` | Working set details |
 | `workset rm` / `workset delete` | Remove working set (`--purge`, `--force`) |
-| `workset config` | View or modify workset configuration (use `workset config default <key>=<value>` for default-workset defaults) |
+| `workset set` / `workset get` / `workset show` / `workset reset` | View or modify workset configuration (use `workset set default <key>=<value>` for default-workset defaults) |
 | `workset connect <workset> [source]` | Add project to working set (`--name`) |
 | `workset disconnect <workset> <project>` | Remove project from working set (`--force`) |
 
@@ -275,7 +294,7 @@ shortcuts for common operations:
 |------------|-------------|
 | `agent list` / `agent ls` | List configured agents (`-q`) |
 | `agent info` / `agent inspect` | Agent configuration details |
-| `agent config` | View or modify agent configuration |
+| `agent set` / `agent get` / `agent show` / `agent reset` | View or modify agent configuration |
 | `agent reauth [project]` | Refresh credentials |
 
 ### `box helper` / `box fork` Subcommands
@@ -300,10 +319,74 @@ The runtime helper and fork verbs (formerly under `crab`) now live under `box`:
 | Subcommand | Description |
 |------------|-------------|
 | `system info` / `system inspect` | System details (version, runtime, paths) |
-| `system config` | View or modify global configuration |
+| `system set` / `system get` / `system show` / `system reset` | View or modify global configuration |
 | `system upgrade` | Self-update (`--check` for dry run) |
 | `system diagnose` | Check system health (runtime, images, agents, storage) |
 
+## VS Code Integration
+
+> **⚠ Experimental.** VS Code integration is **experimental** in this release.
+> The commands below work, but multi-surface behavior is still hardening — in
+> particular, kanibako does **not yet enforce a single active agent per box**.
+> Running the agent **panel** and a **CLI agent** on the *same box at the same
+> time* silently **forks the session**: both write the same agent history and
+> one surface's turns can be lost with no warning. **Use one agent surface per
+> box at a time** until single-writer enforcement lands.
+
+`kanibako code [project]` opens your **host** VS Code attached to the box
+(Dev Containers "Attach to Running Container"), at the box's `~/workspace`.
+The box is auto-started detached if it isn't running, and it stays up when
+you close the window. The box agent's editor extension is installed into the
+attached window automatically.
+
+Requirements: the `code` CLI on your PATH, the Dev Containers extension
+(`ms-vscode-remote.remote-containers`), and
+`"dev.containers.dockerPath": "podman"` in your VS Code user settings.
+`kanibako system diagnose` checks all three.
+
+### Remote boxes
+
+```bash
+kanibako code --remote <host> <project>
+```
+
+attaches your **local** VS Code to a box on a **remote** kanibako host —
+no relay service, no VS Code on the remote host. `<host>` is an opaque SSH
+destination resolved by your own `~/.ssh/config`. kanibako runs the box
+lifecycle on the remote host over plain SSH, and the container-engine leg
+rides a kanibako-owned SSH tunnel: one OpenSSH `ControlPersist` master
+forwards the remote rootless podman socket to a local unix socket, and local
+podman dials that socket. podman's own golang `ssh:` transport is **not**
+used, so no `ssh-agent` is required, your `~/.ssh/config` is fully honored
+(aliases, ProxyJump, ports, `IdentityFile`), and per-call SSH handshake
+overhead is gone once the first call warms the tunnel.
+
+Requirements:
+
+- the same kanibako **version** on both hosts, plus a local `code` CLI and
+  local `podman` (the `--remote` client);
+- the rootless podman API socket on the remote host:
+
+  ```bash
+  systemctl --user enable --now podman.socket
+  loginctl enable-linger "$USER"
+  ```
+
+On first `--remote` use, kanibako asks to point
+`dev.containers.dockerPath` at its dispatch wrapper (local attaches are
+unaffected — the wrapper is a pass-through to `podman` except for remote
+attach windows).
+
+If a remote attach fails, check the dispatch log at
+`~/.local/state/kanibako/vscode-remote/dispatch.log` (or under
+`$XDG_STATE_HOME`) — one line per engine call showing the resolved route and
+context.
+
+> **First attach:** the first time VS Code attaches to a given container it
+> shows a workspace-trust dialog you must click through. In headless or
+> automated setups this can look like a silent hang — bring the VS Code
+> window forward and confirm the trust prompt to proceed.
+
 ## Common Flags
 
 ### Agent Flags (on `start`)
@@ -349,7 +432,7 @@ error, not a silent no-op).
 #### `--box`: operate on any box
 
 `--box` substitutes for being in the box's directory: `kanibako stop --box myproj`,
-`kanibako box config --box myproj model=opus`. The value is a **box name (resolved
+`kanibako box set --box myproj model=opus`. The value is a **box name (resolved
 first) or a path**. It is the *subject* the command acts on, and stays orthogonal to
 the `move`/`convert` *destination* group, so they coexist:
 
@@ -408,7 +491,7 @@ confirm. Non-TTY runs (CI / headless) skip the prompt gracefully.
 nudge to run `setup` if it has never been run, then proceed.
 
 Because `system.*` keys are **file-only** (see [Configuration](#configuration)),
-the default agent is *not* settable via `kanibako system config` -- use `setup` or
+the default agent is *not* settable via `kanibako system set` -- use `setup` or
 edit `global/settings.yaml` directly.
 
 ## Project Modes
@@ -431,11 +514,11 @@ and run `kanibako`, and the box joins the primary workset.
 
 The primary workset is addressable through the same `workset` commands as named
 worksets (workset name token `__PRIMARY__`), so primary-workset settings use the
-ordinary `workset config default` mechanism (see [Configuration](#configuration)):
+ordinary `workset set default` mechanism (see [Configuration](#configuration)):
 
 ```bash
-kanibako workset config default model=opus          # default for ALL primary-mode boxes
-kanibako workset config default group_auth=false    # distinct credentials by default
+kanibako workset set default model=opus          # default for ALL primary-mode boxes
+kanibako workset set default group_auth=false    # distinct credentials by default
 ```
 
 The names `__PRIMARY__` / `__STANDALONE__` (and legacy `default`) are reserved
@@ -629,9 +712,9 @@ container:
 
 ```bash
 # Persistent (stored in project config)
-kanibako box config env.EDITOR=vim           # project-level
-kanibako system config env.EDITOR=nano       # global (all projects)
-kanibako box config env.EDITOR               # show one value
+kanibako box set env.EDITOR=vim              # project-level
+kanibako system set env.EDITOR=nano          # global (all projects)
+kanibako box get env.EDITOR                  # show one value
 
 # Per-run (not persisted)
 kanibako start -e EDITOR=vim -e DEBUG=1
@@ -644,7 +727,7 @@ Project env vars override global ones.
 The shell prompt is controlled by the `KANIBAKO_PS1` environment variable:
 
 ```bash
-kanibako box config env.KANIBAKO_PS1="(myproject) \u:\w\$ "
+kanibako box set env.KANIBAKO_PS1="(myproject) \u:\w\$ "
 ```
 
 ### Init scripts
@@ -702,8 +785,8 @@ Manage agent settings via the CLI:
 
 ```bash
 kanibako agent list                    # list configured agents
-kanibako agent config model            # show effective model
-kanibako agent config model=sonnet     # set agent-level default
+kanibako agent get claude model        # show the agent's model
+kanibako agent set claude model=sonnet # set agent-level default
 ```
 
 ## Home Templates
@@ -822,7 +905,7 @@ guide.
 pip install kanibako-target-myagent
 
 # Use a specific target
-kanibako box config box.agent=myagent
+kanibako box set box.agent=myagent
 kanibako start
 
 # (`crab_name` is gone -- select the agent via box.agent)
@@ -846,29 +929,30 @@ CLI flag > settings_required > box > workset > agent.<agent> > system > settings
 **file-only** -- the CLI reads and shows them but refuses to set them (edit the
 file directly); `setup` and programmatic writers still write them.
 
-All settings levels share a unified interface:
+All settings levels share the same four verbs -- `set` / `get` / `show` /
+`reset`:
 
 ```bash
 # Box level
-kanibako box config                     # show box overrides
-kanibako box config --effective         # show resolved values (inherited + overrides)
-kanibako box config model               # get one key
-kanibako box config model=sonnet        # set one key
-kanibako box config --reset model       # remove override, back to default
+kanibako box show                       # show box overrides
+kanibako box show --effective           # show resolved values (inherited + overrides)
+kanibako box get model                  # get one key
+kanibako box set model=sonnet           # set one key
+kanibako box reset model                # remove override, back to default
 
 # Workset level (group defaults inherited by member boxes)
-kanibako workset config <workset> model=opus
-kanibako workset config default model=opus   # primary-workset default
+kanibako workset set <workset> model=opus
+kanibako workset set default model=opus      # primary-workset default
 
 # Agent level (defaults for all boxes using this agent)
-kanibako agent config model=opus
+kanibako agent set claude model=opus
 
 # System level (global settings defaults)
-kanibako system config model=opus
-kanibako system config --reset --all    # reset all global settings
+kanibako system set model=opus
+kanibako system reset --all             # reset all global settings
 ```
 
-`kanibako system config` sets **non-`system.`** settings only. `system.*`-prefixed
+`kanibako system set` sets **non-`system.`** settings only. `system.*`-prefixed
 keys (layout paths AND `system.default_agent`) are **file-only**: the CLI shows them
 but refuses to set/reset them, pointing you at the config file. Set the default agent
 with `kanibako setup`; edit structural paths in `~/.config/kanibako.yaml` directly.

{kanibako_cli-1.6.0.dev36 → kanibako_cli-1.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kanibako-cli"
-version = "1.6.0.dev36"
+version = "1.7.0"
 description = "Run AI coding agents in rootless containers with per-project isolation"
 requires-python = ">=3.11"
 dependencies = ["argcomplete>=3.0", "PyYAML>=6.0", "packaging>=20.0"]
@@ -30,11 +30,16 @@ where = ["src"]
     "templates/**/*", "templates/**/.*",
     "templates/.*/**/*", "templates/.*/*",
     "templates/**/.*/**/*", "templates/**/.*/*",
+    "global/*", "global/**/*",
 ]
 
 [tool.ruff]
 target-version = "py311"
 line-length = 99
+# ``salvage/`` holds frozen, non-shipping reference snapshots (retired code kept
+# for a possible future ``system recover``); it is not live code and is not
+# linted. It is also outside ``src/`` so the wheel build never includes it.
+extend-exclude = ["salvage"]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/conftest.py" = ["E402"]
@@ -48,6 +53,9 @@ line-length = 99
 # mypy at every src base and enable explicit package bases.
 namespace_packages = true
 explicit_package_bases = true
+# ``salvage/`` is a frozen non-shipping reference snapshot (see [tool.ruff]); it
+# is not type-checked and is not on any src base.
+exclude = ['^salvage/']
 mypy_path = "$MYPY_CONFIG_FILE_DIR/src:$MYPY_CONFIG_FILE_DIR/packages/agent-claude/src:$MYPY_CONFIG_FILE_DIR/packages/agent-goose/src:$MYPY_CONFIG_FILE_DIR/packages/agent-codex/src"
 
 [[tool.mypy.overrides]]

kanibako_cli-1.7.0/src/kanibako/__init__.py

@@ -0,0 +1,25 @@
+"""kanibako: Run AI coding agents in rootless containers with per-project isolation."""
+
+__version__ = "1.7.0"
+
+# Two-tier setup/config compatibility constants for the 5-band setup-completion
+# gate (design: ``plans/2026-06-23-setup-version-tiers-NEXT.md``).  Both are
+# compared against the recorded ``system.setup_completed`` marker by BASE version
+# (PEP 440 via ``packaging.version``), so a dev/rc build of the same base reads
+# as the released base, not "from the future".
+#
+# * ``SETUP_BCV`` — backward-compatible version: the OLDEST setup/config version
+#   this build can function with AT ALL.  Below it, the build can no longer
+#   auto-fill the gaps → the gate ERRORS (rc1) and the user must re-run setup.
+#   Bump only when a setup change can no longer be auto-filled.
+# * ``SETUP_FCV`` — forward-compatible version: the oldest version whose setup is
+#   COMPLETELY compatible (nothing new since).  At or above it (but below the
+#   running build) the gate SILENTLY bumps the marker forward.  Between BCV and
+#   FCV the gate NUDGES (non-blocking) to re-run setup.  Bump whenever setup adds
+#   a new feature/case.
+#
+# Invariant: ``SETUP_BCV <= SETUP_FCV <= __version__`` (base versions).  Most
+# releases change setup in no way → bump NEITHER → existing configs land
+# ``>= FCV`` → silent.
+SETUP_BCV = "1.6.0"
+SETUP_FCV = "1.7.0"

kanibako_cli-1.7.0/src/kanibako/agent_config.py

@@ -0,0 +1,146 @@
+"""Agent YAML configuration: load, write, and resolve per-agent settings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from kanibako.config_io import dump_doc, load_doc
+
+# Keys that live directly in the [agent] section as agent identity (not state).
+IDENTITY_KEYS = frozenset({"name", "run_args"})
+
+
+@dataclass
+class AgentConfig:
+    """Per-agent configuration loaded from an agent YAML file.
+
+    Sections:
+      agent        — identity (name, run_args) plus agent-state knobs
+                     (model, auto_approve, allow_helpers, endpoint, …). The
+                     per-node DISCRIMINATED sub-table ``agent.<node>.secret_path``
+                     also lives here (see *secret_path* below).
+      env          — raw env vars injected into container (VAR -> value)
+      secret_path  — the SECRET category (spec §2a, 2026-07-06; RENAMED from the
+                     rc0-rc2 ``env_file``): VAR -> host PATH pointer to secret
+                     material (e.g. a 0600 bearer-token file). Stored DISCRIMINATED
+                     under ``agent.<node>.secret_path.<VAR>`` (the SAME first-class
+                     category shape ``config set agent.<node>.secret_path.<VAR>``
+                     writes and ``_agent_partial`` reads into the launch cascade),
+                     so it resolves through ``system → workset → box → agent``
+                     precedence. The value is a PATH only — at launch it is ro-bind-
+                     mounted arm's-length + exported IN-BOX; kanibako NEVER reads the
+                     secret VALUE (never in the snapshot/keystore/logs/argv).
+    """
+
+    name: str = ""
+    run_args: list[str] = field(default_factory=list)
+    state: dict[str, str] = field(default_factory=dict)
+    env: dict[str, str] = field(default_factory=dict)
+    secret_path: dict[str, str] = field(default_factory=dict)
+    tweakcc: dict = field(default_factory=dict)
+
+
+def agents_dir(data_path: Path, paths_agents: str = "agents") -> Path:
+    """Return the agents directory under *data_path*."""
+    return data_path / (paths_agents or "agents")
+
+
+def agent_settings_path(agents_root: Path, agent_id: str) -> Path:
+    """Return ``@meta.agent.<agent>.settings`` for *agent_id*.
+
+    The per-agent SETTINGS cascade file lives INSIDE the per-agent store dir
+    (``@meta.agent.<agent>.path`` = ``agents/<agent>/``) as ``settings.yaml``
+    — NOT the old sibling ``agents/<agent>.yaml`` file (D-2026-06-22).  This
+    parallels the per-agent template dir ``agents/<agent>/template`` and the
+    Part-3 ``agents/<agent>/{plugins,cache}`` stores.
+    """
+    return agents_root / agent_id / "settings.yaml"
+
+
+def agent_config_path(
+    data_path: Path, agent_id: str, paths_agents: str = "agents",
+) -> Path:
+    """Return the path to an agent's config (settings) file.
+
+    Convenience wrapper for callers that hold a *data_path* rather than the
+    resolved agents root; delegates to :func:`agent_settings_path`.
+    """
+    return agent_settings_path(agents_dir(data_path, paths_agents), agent_id)
+
+
+def load_agent_config(path: Path) -> AgentConfig:
+    """Read an agent config file and return an AgentConfig.
+
+    Returns defaults if the file does not exist.
+    """
+    cfg = AgentConfig()
+    if not path.exists():
+        return cfg
+
+    data = load_doc(path)
+
+    # The node is the per-agent store dir name (agents/<node>/settings.yaml), which
+    # IS the cascade discriminator ``_agent_partial`` reads (agent_name == node). The
+    # DISCRIMINATED ``agent.<node>.secret_path`` sub-table (first-class category)
+    # lives under the same ``agent:`` table as the flat state — read it by node.
+    node = path.parent.name
+
+    agent_sec = data.get("agent", {})
+    if not isinstance(agent_sec, dict):
+        agent_sec = {}
+    cfg.name = str(agent_sec.get("name", ""))
+    raw_args = agent_sec.get("run_args", [])
+    cfg.run_args = [str(a) for a in raw_args] if isinstance(raw_args, list) else []
+
+    # Flat state = the SCALAR agent-state knobs. Exclude identity keys AND any
+    # dict-valued entry: the discriminated ``<node>:`` sub-table (secret_path, node
+    # binds) is a dict and is NOT flat state — it rides ``_agent_partial``, not the
+    # ``_agent_state_partial`` state channel.
+    cfg.state = {
+        k: str(v)
+        for k, v in agent_sec.items()
+        if k not in IDENTITY_KEYS and not isinstance(v, dict)
+    }
+    cfg.env = {k: str(v) for k, v in data.get("env", {}).items()}
+    # secret_path: VAR -> host PATH pointer, read from the DISCRIMINATED
+    # ``agent.<node>.secret_path`` sub-table (spec §2a SECRET category). Stored as a
+    # plain string path; the file's CONTENTS (the secret) are never persisted here
+    # nor read — they are ro-mounted + exported IN-BOX only at launch.
+    node_sub = agent_sec.get(node, {})
+    secret_sub = node_sub.get("secret_path", {}) if isinstance(node_sub, dict) else {}
+    cfg.secret_path = {
+        k: str(v) for k, v in secret_sub.items()
+    } if isinstance(secret_sub, dict) else {}
+    cfg.tweakcc = dict(data.get("tweakcc", {}))
+
+    return cfg
+
+
+def write_agent_config(path: Path, cfg: AgentConfig) -> None:
+    """Write an AgentConfig to a YAML file."""
+    node = path.parent.name
+    agent_sec: dict = {
+        "name": cfg.name,
+        "run_args": list(cfg.run_args),
+    }
+    for k, v in cfg.state.items():
+        agent_sec[k] = v
+    # secret_path (spec §2a SECRET category) is stored DISCRIMINATED under the
+    # ``agent.<node>.secret_path`` sub-table — the SAME first-class category location
+    # ``config set agent.<node>.secret_path.<VAR>`` writes and ``_agent_partial``
+    # reads into the launch cascade — so the persona-adopted token pointer resolves
+    # through the cascade like any other agent-tier category. Only materialized when
+    # non-empty (sparse). NO ``env_file`` section (RENAMED, clean break — rc0-rc2 only).
+    if cfg.secret_path:
+        agent_sec[node] = {"secret_path": dict(cfg.secret_path)}
+
+    data: dict = {
+        "agent": agent_sec,
+        "env": dict(cfg.env),
+        "tweakcc": dict(cfg.tweakcc),
+    }
+    # The settings file lives inside the per-agent store dir
+    # (agents/<agent>/settings.yaml); ensure that dir exists.
+    path.parent.mkdir(parents=True, exist_ok=True)
+    dump_doc(path, data)