kanibako-cli 1.8.0.dev98__tar.gz → 1.8.0rc2__tar.gz

{kanibako_cli-1.8.0.dev98/src/kanibako_cli.egg-info → kanibako_cli-1.8.0rc2}/PKG-INFO

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

{kanibako_cli-1.8.0.dev98 → kanibako_cli-1.8.0rc2}/README.md

@@ -225,7 +225,7 @@ shortcuts for common operations:
 
 | Subcommand | Description |
 |------------|-------------|
-| `workset create [path]` | Create working set (`--name`, `--standalone`, `--image`, `--no-vault`, `--distinct-auth`) |
+| `workset create [path]` | Create working set (`--name`, `--image`, `--no-vault`, `--distinct-auth`) |
 | `workset list` / `workset ls` | List working sets (`-q`) |
 | `workset info` / `workset inspect` | Working set details |
 | `workset rm` / `workset delete` | Remove working set (`--purge`, `--force`) |
@@ -505,8 +505,8 @@ and cannot be used as a named-workset name.
 
 ```
 $XDG_DATA_HOME/kanibako/primary_workset/
-├── settings.yaml
-├── boxes/{name}/{home/ → ~/ , settings.yaml}
+├── workset.yaml
+├── boxes/{name}/{home/ → ~/ , box.yaml}
 ├── vault/{ro,rw}/{name}/                        → ~/vault/{ro,rw}
 └── logs/{name}.jsonl
 # the box WORKSPACE stays external: your real project dir → ~/workspace
@@ -515,7 +515,7 @@ $XDG_DATA_HOME/kanibako/primary_workset/
 ### Named workset
 
 A workset is a *named* project group rooted at a directory you pick.  It groups
-related projects under one human-readable root, with a single `<root>/settings.yaml`
+related projects under one human-readable root, with a single `<root>/workset.yaml`
 (identity + member list + a group-level settings/auth tier that member boxes
 inherit; see [Configuration](#configuration)).  A workset name is a shared
 address and must be unique -- a collision at create/import time is refused.
@@ -529,8 +529,8 @@ kanibako
 
 ```
 {workset}/
-├── settings.yaml
-├── boxes/{name}/{home/ → ~/ , settings.yaml}
+├── workset.yaml
+├── boxes/{name}/{home/ → ~/ , box.yaml}
 ├── workspaces/{name}/                  → ~/workspace
 ├── vault/{ro,rw}/{name}/               → ~/vault/{ro,rw}
 └── logs/{name}.jsonl
@@ -559,9 +559,9 @@ kanibako box register ~/myproj         # or opt in afterwards
 
 ```
 {project}/                       ← project root
-├── settings.yaml                ← box metadata (at the root)
+├── workset.yaml                 ← workset tier (degenerate workset at the root)
 ├── workspace/                   → ~/workspace  (a subdir, not the root)
-├── box_data/{home/ → ~/ , {name}.jsonl}
+├── box_data/{home/ → ~/ , box.yaml, {name}.jsonl}
 └── vault/{ro,rw}/               → ~/vault/{ro,rw}
 ```
 
@@ -744,31 +744,33 @@ support `shell.d/` on the next launch.
 ## Agent Configuration
 
 Each agent gets a YAML configuration file inside its per-agent store directory
-at `$XDG_DATA_HOME/kanibako/agents/{agent}/settings.yaml`.  The file is
+at `$XDG_DATA_HOME/kanibako/agents/{agent}/agent.yaml`.  The file is
 generated automatically on first use (via the target plugin's
 `generate_agent_config()` method) and can be edited afterwards.
 
 ```yaml
-agent:
+self:
   name: "Claude Code"
-  run_args: []              # extra CLI args prepended on every launch
+  run_args: ["--verbose"]   # extra CLI args prepended on every launch (omit if none)
   model: "opus"             # agent-specific state knobs (e.g. --model for Claude)
   access: "permissive"
-env:
-  # KEY: "value"            # raw env vars injected into the box
-tweakcc:
-  # enabled: false          # enable tweakcc binary patching
-  # config: "~/.tweakcc/config.json"  # external tweakcc config file
+  env:
+    # KEY: "value"          # raw env vars injected into the box
+  transform_settings:
+    # enabled: false        # enable tweakcc binary patching
+    # config: "~/.tweakcc/config.json"  # external tweakcc config file
 ```
 
 **Sections:**
-- `agent:` -- identity and defaults (`name`, `run_args`) plus runtime state
-  knobs translated by the target plugin into CLI args and env vars (e.g. Claude
-  maps `model` -> `--model`). Effective state resolves across the settings
-  cascade `system < agent.<agent> < workset < box` with the target's declared
-  defaults as the floor.
-- `env:` -- environment variables injected into the box
-- `tweakcc:` -- optional tweakcc integration for binary patching
+- `self:` -- the file's root table, which stands for the agent whose file it is
+  (`agent.<agent>`); it is a spelling of this file only and has no CLI form. It
+  holds identity and defaults (`name`, `run_args`) plus runtime state knobs
+  translated by the target plugin into CLI args and env vars (e.g. Claude maps
+  `model` -> `--model`). Effective state resolves across the settings cascade
+  `system < agent.<agent> < workset < box` with the target's declared defaults
+  as the floor.
+- `self.env:` -- environment variables injected into the box
+- `self.transform_settings:` -- optional tweakcc integration for binary patching
   (see [docs/tweakcc.md](docs/tweakcc.md))
 
 Per-agent common dirs/caches are declared by the plugin (`agent.<agent>.common` /
@@ -911,12 +913,18 @@ Later sources override earlier ones when two plugins register the same name.
 |------|----------|----------|
 | 1. Entry points | `kanibako.agents` entry point group + `kanibako.plugins.*` namespace scan | Pip-installed packages and bind-mounted plugins in nested containers |
 | 2. User directory | `~/.local/share/kanibako/plugins/*.py` | Personal plugins shared across all projects |
-| 3. Project directory | `{project}/.kanibako/plugins/*.py` | Project-specific plugins |
+| 3. Project directory | `{project}/box_data/plugins/*.py` | Project-specific plugins |
 
 Drop a `.py` file containing a `Target` subclass into the user or project
 plugins directory and Kanibako picks it up automatically -- no packaging or
 `pip install` needed.  Files starting with `_` are skipped.
 
+**A plugin that fails to load is skipped, not fatal.**  If a plugin raises while
+being imported -- most often because it was built against a different
+`kanibako-cli` -- Kanibako names it on standard error, says the rest still works,
+and carries on without it.  Only that agent becomes unavailable; every other
+agent, and `kanibako setup`, are unaffected.
+
 **Security note:** file-drop plugins run with the same permissions as
 Kanibako itself.  Only place files you trust in plugin directories.
 
@@ -928,10 +936,11 @@ guide.
 pip install kanibako-target-myagent
 
 # Use a specific target
-kanibako box set box.agent=myagent
+kanibako box set pref.system.agent=myagent
 kanibako start
 
-# (`crab_name` is gone -- select the agent via box.agent)
+# (`crab_name` and `box.agent_name` are gone -- select the agent via
+#  pref.system.agent, which is the spelling kanibako's own messages print)
 ```
 
 ## Configuration
@@ -940,15 +949,17 @@ Kanibako splits **config** (layout -- *where things live*, the `system.*`
 namespace) from **settings** (behavior -- `agent.*` / `box.*` / `workset.*` plus
 the category keys).  They live in separate file sets.
 
-**Settings** follow a 6-tier cascade (box wins among the normal tiers;
-`*_required` is an absolute admin cap above box), below CLI flags:
+**Settings** follow a 5-tier cascade (box wins), below CLI flags:
 
 ```
-CLI flag > settings_required > box > workset > agent.<agent> > system > settings_base
+CLI flag > box > workset > agent.<agent> > system > settings_base
 ```
 
+Within the agent tier, `agent.default` supplies the all-agents fallback for any key
+the active agent's own layer does not set.
+
 **Config** (`system.*`) is read from the config file set
-(`config_base < ~/.config/kanibako.yaml < config_required`).  Config keys are
+(`config_base < ~/.config/kanibako.yaml`).  Config keys are
 **file-only** -- the CLI reads and shows them but refuses to set them (edit the
 file directly); `setup` and programmatic writers still write them.
 
@@ -987,9 +998,13 @@ All kanibako config/settings files are YAML.
 
 - **Config (global)**: `$XDG_CONFIG_HOME/kanibako.yaml` (`system.*` layout only)
 - **System settings**: `$XDG_DATA_HOME/kanibako/global/settings.yaml`
-- **Workset settings**: `<workset_root>/settings.yaml`
-- **Per-agent settings**: `$XDG_DATA_HOME/kanibako/agents/{agent}/settings.yaml`
-- **Per-box settings**: `boxes/{name}/settings.yaml` (standalone: `<root>/settings.yaml`)
+- **Workset settings**: `<workset_root>/workset.yaml` (optional -- a workset root has
+  one only once you set something there)
+- **Workset membership**: `<workset_root>/registry.yaml` (its boxes, as flat `name: path`
+  rows -- and nothing else; a workset is NAMED by the global registry's `worksets:` section,
+  never by a file under its own root)
+- **Per-agent settings**: `$XDG_DATA_HOME/kanibako/agents/{agent}/agent.yaml`
+- **Per-box settings**: `boxes/{name}/box.yaml` (standalone: `<root>/box_data/box.yaml`)
 - **Template root**: `$XDG_DATA_HOME/kanibako/global/template/` (the `box`,
   `workset` and `agent` moulds new stores are stamped from)
 - **System handbook**: `$XDG_DATA_HOME/kanibako/global/canon/handbook/` -- your
@@ -1104,7 +1119,7 @@ A broadcast channel (`all/`) is available to all helpers.
     workspace/          # helper's working directory
     vault/ro/           # read-only vault share
     vault/rw/           # read-write vault share
-    playbook/scripts/   # helper-init.sh (entrypoint wrapper)
+    scripts/            # helper-init.sh (entrypoint wrapper)
     peers/              # symlinks to peer channels
     all -> ../all/      # broadcast channel
     spawn.yaml          # RO spawn budget

{kanibako_cli-1.8.0.dev98 → kanibako_cli-1.8.0rc2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kanibako-cli"
-version = "1.8.0.dev98"
+version = "1.8.0rc2"
 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"]
@@ -102,5 +102,9 @@ markers = [
     # OF ``unshare_chown``/``unshare_chmod`` themselves: patching the subject with
     # the stub turns real assertions into false reds.
     "no_unshare_sim: never apply the protected-canon unshare simulation",
+    # The KeyStore census (tests/_keystore_census.py) fails a run on an undeclared
+    # key. A test that EXERCISES a refusal has to write one; it names the exact
+    # paths here, and a named path that is never written fails the run in its turn.
+    "writes_undeclared: this test writes the named UNDECLARED key paths on purpose",
 ]
 addopts = "-m 'not integration and not e2e'"

{kanibako_cli-1.8.0.dev98 → kanibako_cli-1.8.0rc2}/src/kanibako/__init__.py

@@ -1,6 +1,6 @@
 """kanibako: Run AI coding agents in rootless containers with per-project isolation."""
 
-__version__ = "1.8.0.dev98"
+__version__ = "1.8.0rc2"
 
 # 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

{kanibako_cli-1.8.0.dev98 → kanibako_cli-1.8.0rc2}/src/kanibako/agent_ref.py

@@ -10,7 +10,11 @@ from __future__ import annotations
 import re
 from kanibako.errors import ConfigError
 
-# Persona/harness separators: one for typing [+], another internally to avoid collisions [℘]
+# Persona/harness separators.  ``+`` is the spelling wherever a human looks, the on-disk store
+# dirname included (:func:`kanibako.settings.agent_config.store_dirname`).  ``℘`` exists for ONE
+# reason: a key path is split on ``.`` into ``SEGMENT_CHAR_CLASS`` segments (below), which admit
+# no ``+`` — so ``agent.nav+claude.model`` would match only ``agent.nav`` and silently resolve a
+# different key.  A node wears ``℘`` INSIDE a key and nowhere else.
 SEPARATORS = (PLUS_SEP := "+", CANONICAL_SEP := "℘")
 
 # "Safe" characters in agent names

kanibako_cli-1.8.0rc2/src/kanibako/box_lifecycle.py

@@ -0,0 +1,232 @@
+"""Box CLIENT-ATTACHMENT detection — the shared PID-1 lifecycle primitive.
+
+⚑ Half of the PID-1 pair with :mod:`kanibako.box_supervisor`: PINNED FLAT,
+STDLIB-ONLY, invoked in-box by a dotted literal.  Do not package or move it, and
+do not add a non-stdlib import.
+
+⚑ Every probe here is TOLERANT — an absent tmux, empty/garbled output or a
+malformed ``/proc`` entry resolves to a safe falsy / ``None``, never an
+exception.  This module runs as PID-1; a raise takes the box down.
+
+Reasoning, the increment map and the design refs: ``llm-docs/kanibako/box_lifecycle.py.md``.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from enum import Enum
+from glob import glob
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# VS Code remote-server directory markers (canonical — shared with code_cmd).
+# ---------------------------------------------------------------------------
+
+# ⚑ ILLUSTRATIVE — the known channels, for readers.  NOT the matching rule:
+# :func:`is_vscode_server_path_part` is authoritative and deliberately broader,
+# so editing this tuple does NOT change matching.
+VSCODE_SERVER_DIR_MARKERS: tuple[str, ...] = (
+    ".vscode-server",
+    ".vscode-server-insiders",
+    ".vscode-server-oss",
+    ".cursor-server",
+)
+
+
+def is_vscode_server_path_part(part: str) -> bool:
+    """True when a single path SEGMENT names a VS Code remote-server dir.
+
+    Takes ONE path component (e.g. from :attr:`pathlib.Path.parts`), so a
+    caller tests each segment of a resolved/cmdline path independently.
+    """
+    return part.startswith(".vscode-server") or part == ".cursor-server"
+
+
+# ---------------------------------------------------------------------------
+# Pure surface detectors.
+# ---------------------------------------------------------------------------
+
+def vscode_server_present(proc_cmdlines: Iterable[str]) -> bool:
+    """True iff any process command line indicates a running in-box VS Code server.
+
+    PURE, over ALREADY-collected cmdlines: a cmdline counts when any
+    ``/``-delimited SEGMENT of it names a remote-server dir — so
+    ``/home/agent/.vscode-server/bin/<hash>/node`` matches while
+    ``/usr/bin/node`` does not.  An empty iterable → ``False``.
+    """
+    for cmdline in proc_cmdlines:
+        if any(is_vscode_server_path_part(part) for part in cmdline.split("/")):
+            return True
+    return False
+
+
+def tmux_terminal_attached(list_clients_output: str) -> bool:
+    """True iff ``tmux list-clients`` output shows ≥1 attached terminal client.
+
+    PURE: tmux prints one LINE per attached client and nothing otherwise.
+    ⚑ The CALLER must normalise any tmux error to ``""`` to keep this a pure
+    string test — :func:`_tmux_clients_output` is what does that.
+    """
+    return bool(list_clients_output.strip())
+
+
+# ---------------------------------------------------------------------------
+# Attach-state model + transition classifier.
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class AttachState:
+    """Immutable snapshot of which client surfaces are attached to the box.
+
+    Two surfaces today, kept as named bools so a new one is a single added
+    field.  Frozen so a prev/cur pair is safe to hold across a watcher tick.
+    """
+
+    vscode_server: bool = False
+    tmux_terminal: bool = False
+
+    @property
+    def any_attached(self) -> bool:
+        """True when ANY client surface is currently attached."""
+        return self.vscode_server or self.tmux_terminal
+
+    @property
+    def _surfaces(self) -> tuple[bool, ...]:
+        """The per-surface flags, positionally stable across states.
+
+        A new surface added to this tuple needs no classifier change.
+        """
+        return (self.vscode_server, self.tmux_terminal)
+
+
+class LifecycleEvent(Enum):
+    """The transition a watcher tick produces (consumed by E2 self-heal / D)."""
+
+    ATTACH = "attach"
+    DETACH = "detach"
+    NONE = "none"
+
+
+def classify_transition(prev: AttachState, cur: AttachState) -> LifecycleEvent:
+    """Classify the attach-state transition ``prev`` → ``cur`` (PURE).
+
+    * DETACH — ANY surface present in ``prev`` is gone in ``cur``, even when a
+      DIFFERENT surface appeared in the same tick.
+    * ATTACH — no surface was lost AND at least one new surface appeared.
+    * NONE — no surface changed (includes the idempotent same-state tick).
+
+    ⚑ That DETACH bias is deliberate and safety-critical: MISSING a detach
+    drops a just-refreshed token, while an EXTRA detach costs only a redundant,
+    idempotent writeback.  Do not "fix" the mixed tick — see the llm-doc.
+    """
+    lost = any(p and not c for p, c in zip(prev._surfaces, cur._surfaces))
+    if lost:
+        return LifecycleEvent.DETACH
+    gained = any(c and not p for p, c in zip(prev._surfaces, cur._surfaces))
+    if gained:
+        return LifecycleEvent.ATTACH
+    return LifecycleEvent.NONE
+
+
+# ---------------------------------------------------------------------------
+# Thin INJECTABLE system-probe layer (the ONLY side-effecting code).
+# ---------------------------------------------------------------------------
+
+# The subprocess-runner signature the probes call; tests inject a fake.
+_Runner = Callable[..., "subprocess.CompletedProcess[str]"]
+
+
+def _collect_proc_cmdlines() -> list[str]:
+    """Collect running-process command lines from ``/proc/*/cmdline``.
+
+    The impure companion to :func:`vscode_server_present`.  Tolerant: a
+    vanished PID, a permission error or a kernel thread's empty cmdline is
+    SKIPPED, never raised.
+    """
+    cmdlines: list[str] = []
+    for entry in glob("/proc/[0-9]*/cmdline"):
+        try:
+            raw = Path(entry).read_bytes()
+        except OSError:
+            # PID vanished between glob and read, or unreadable — skip it.
+            continue
+        # cmdline is NUL-delimited argv (trailing NUL); decode leniently.
+        text = raw.replace(b"\x00", b" ").decode("utf-8", "replace").strip()
+        if text:
+            cmdlines.append(text)
+    return cmdlines
+
+
+def _tmux_clients_output(session: str, run: _Runner) -> str:
+    """Return ``tmux list-clients -t <session>`` stdout, or ``""`` on any failure.
+
+    Normalises EVERY not-attached / no-tmux condition to the empty string
+    :func:`tmux_terminal_attached` reads as "no terminal".
+    ⚑ ``-F ""`` is NOT used: the default one-line-per-client output IS the
+    presence signal being tested.
+    """
+    try:
+        proc = run(
+            ["tmux", "list-clients", "-t", session],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except (FileNotFoundError, OSError):
+        return ""
+    if proc.returncode != 0:
+        return ""
+    return proc.stdout or ""
+
+
+def snapshot_attach_state(
+    session: str,
+    *,
+    run: _Runner = subprocess.run,
+    proc_cmdlines: Iterable[str] | None = None,
+) -> AttachState:
+    """Probe the CURRENT client-attachment state of the box (the impure snapshot).
+
+    Composes the two pure detectors over freshly probed system state; an
+    explicit *proc_cmdlines* skips the ``/proc`` read entirely.  ⚑ All probing
+    in this module is confined here and to the two ``_*`` helpers.  Never
+    raises.
+    """
+    cmdlines = (
+        _collect_proc_cmdlines() if proc_cmdlines is None else list(proc_cmdlines)
+    )
+    return AttachState(
+        vscode_server=vscode_server_present(cmdlines),
+        tmux_terminal=tmux_terminal_attached(_tmux_clients_output(session, run)),
+    )
+
+
+def canonical_tmux_session_pid(
+    session: str,
+    *,
+    run: _Runner = subprocess.run,
+) -> int | None:
+    """Best-effort PID of the tmux server hosting *session* (the "live marker").
+
+    ⚑ ``#{pid}`` is the tmux SERVER pid, not a pane or client pid.  ``None``
+    when the session is absent, tmux is missing, or the output is unparseable.
+    E2 uses this to identify the canonical always-on instance.
+    """
+    try:
+        proc = run(
+            ["tmux", "display-message", "-p", "-t", session, "#{pid}"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except (FileNotFoundError, OSError):
+        return None
+    if proc.returncode != 0:
+        return None
+    text = (proc.stdout or "").strip()
+    try:
+        return int(text)
+    except ValueError:
+        return None