swarph-cli 0.5.0__tar.gz → 0.7.0__tar.gz

{swarph_cli-0.5.0 → swarph_cli-0.7.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.5.0
-Summary: The `swarph` binary — multi-LLM CLI with mesh-gateway integration. v0.5.0 ships Phase 5.6 `swarph daemon` (foreground inbox drain — retires the orphaned-tail-F class) on top of Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL + Phase 5.5 onboard/ratify (PLAN.md §13 / §16).
+Version: 0.7.0
+Summary: The `swarph` binary — multi-LLM CLI with mesh-gateway integration. v0.7.0 ships Phase 7 substrate-doc R7 §11.1.7 operator-tooling layer in 5 increments: PR-A `--new-instance` flag (sibling-spawn case) + PR-B auto-suffix on collision (sibling-slot persistence) + PR-C SessionStart hook (closes bare-claude operator-paste gap) + watchdog (stranded-session recovery) + PR-D swarph-shared cell.yaml relocation (cell-yaml schema graduates to swarph-shared 0.3.0 kernel-tier; substrate-doc R7 §11.1.5 (O5) RESOLVED).
 Author: Pierre Samson, Claude Opus
 License: MIT
 Project-URL: Homepage, https://github.com/darw007d/swarph-cli
@@ -25,7 +25,8 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: swarph-mesh>=0.5.0
-Requires-Dist: swarph-shared>=0.2.0
+Requires-Dist: swarph-shared>=0.3.0
+Requires-Dist: PyYAML>=6.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Dynamic: license-file
@@ -49,16 +50,71 @@ This is one of three repos in the v0.3.x architecture:
 
 ## Status
 
-**v0.5.0 — Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL + Phase 5.5 onboard/ratify + Phase 5.6 daemon.** Six verbs ship:
+**v0.6.0 — Phase 7 spawn ships.** Seven verbs total:
 
 1. `swarph "prompt"` — Phase 2 one-shot mode (any of five providers)
 2. `swarph chat` — Phase 5 interactive REPL with multi-turn history + slash commands
-3. `swarph import <path>` — Phase 2.5 session import (Claude JSONL → swarph-native, with `--report-only` for honest pre-commit inspection)
-4. `swarph onboard <peer-name>` — Phase 5.5 mechanics-phase onboarding (PLAN.md §15.4)
-5. `swarph ratify <peer-name>` — Phase 5.5 witness ratification (PLAN.md §15.4a)
-6. `swarph daemon` — **NEW** Phase 5.6 foreground inbox drain loop (PLAN.md §16); structurally retires the orphaned-tail-F class
+3. `swarph spawn <role>` — **NEW** Phase 7 long-lived `claude` session as a named mesh cell (`--name`/`--session-id`/`--append-system-prompt` pinning per substrate-doc R7 §11.1.7 4-layer R2 stack)
+4. `swarph import <path>` — Phase 2.5 session import (Claude JSONL → swarph-native)
+5. `swarph onboard <peer-name>` — Phase 5.5 mechanics-phase onboarding (PLAN.md §15.4)
+6. `swarph ratify <peer-name>` — Phase 5.5 witness ratification (PLAN.md §15.4a)
+7. `swarph daemon` — Phase 5.6 foreground inbox drain (PLAN.md §16)
 
-Subsequent phases extend the CLI surface (`--ask <peer>`, REPL drain coroutine + `/inbox` + `/reply` slash commands in 5.6b).
+Subsequent phases extend the CLI surface (`--ask <peer>`, REPL drain coroutine + `/inbox` + `/reply` slash commands in 5.6b; non-Claude `spawn` providers + S-G `mesh-gateway://` URL form in v0.7).
+
+### `swarph spawn` (Phase 7 — v0.6.0)
+
+Operator-tooling layer of substrate-doc R7 §11.1.7 4-layer R2 mechanism stack. Wraps `claude` with the three R5/R7 disambiguation flags:
+
+* `--name <role>` — display name for `/resume` picker
+* `--session-id <uuid>` — pinned UUID, persisted to `$XDG_STATE_HOME/swarph/sessions/<role>.session-id` so re-spawns reuse the same session (the R5 fix at the operator-tooling layer)
+* `--append-system-prompt <text>` — starter prompt injected without manual paste (the R2 fix at the operator-tooling layer)
+
+```bash
+# 1. Author a cell.yaml (one-time per role)
+$ cat ~/.config/swarph/cells/lab.yaml
+schema_version: v1
+name: lab-ovh
+role: lab
+cwd: /home/ubuntu
+starter_prompt_path: ~/.claude/session_start_reminder.txt
+provider: claude
+
+# 2. Summon the cell (long-lived claude session, exec-replaced)
+$ swarph spawn lab
+      ╭───╮
+      │ ◉ │
+   ╭──┴───┴──╮
+   │  swarph │  v0.6.0
+   ╰──┬───┬──╯       spawn │ chat │ daemon
+      │ ◉ │
+      ╰───╯
+[claude session takes over the terminal — same flags as `claude --name lab --session-id <uuid> --append-system-prompt <starter>`]
+
+# 3. Resume the same cell after exit — same UUID, same session
+$ swarph spawn lab     # picker shows ONE entry: "lab" (R5 disambiguation)
+```
+
+Resolution order for `swarph spawn <role-or-path>`:
+
+1. `--onboarding <path-or-url>` (alias: `--cell`) — explicit override
+2. Positional ending in `.yaml`/`.yml` or containing a path separator — literal path
+3. Plain role name — `$XDG_CONFIG_HOME/swarph/cells/<role>.yaml` (default `~/.config/swarph/cells/`)
+4. No positional given — auto-discover `./cell.yaml` in current directory
+
+Useful flags:
+
+| Flag | Effect |
+|---|---|
+| `--dry-run` | Print resolved `claude` command + cell summary; do not exec |
+| `--no-starter` | Skip starter-prompt injection even if cell.yaml sets one |
+| `--print-id` | Print resolved session-id to stdout (capture for shell scripts) |
+| `--no-banner` | Suppress the swarph banner on stderr |
+| `-- <claude-args>` | Pass remaining args through to claude unchanged |
+
+cell.yaml schema is **frozen at `schema_version: "v1"`**. v0.7 migrates the parser to `swarph-shared` as a symbol-relocation only — v0.6 cell.yaml files keep working unchanged. Breaking changes require a `schema_version: "v2"` bump and parallel-supported-version window per `swarph-mesh` DEPRECATIONS discipline.
+
+**Known limitations (v0.6).** Single-instance-per-role only. Re-running `swarph spawn <role>` reuses the persisted UUID (R5 fix), so sibling-spawn (alpha + beta co-existing on the same peer-id) requires v0.7's `--new-instance` flag. Manual sibling spawning via `tmux` + explicit `--session-id` pinning still works unchanged; v0.6 does not regress that path, it just doesn't yet expose a CLI shape for it.
 
 ### `swarph daemon` (Phase 5.6)
 

swarph_cli-0.5.0/src/swarph_cli.egg-info/PKG-INFO → swarph_cli-0.7.0/README.md

@@ -1,35 +1,3 @@
-Metadata-Version: 2.4
-Name: swarph-cli
-Version: 0.5.0
-Summary: The `swarph` binary — multi-LLM CLI with mesh-gateway integration. v0.5.0 ships Phase 5.6 `swarph daemon` (foreground inbox drain — retires the orphaned-tail-F class) on top of Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL + Phase 5.5 onboard/ratify (PLAN.md §13 / §16).
-Author: Pierre Samson, Claude Opus
-License: MIT
-Project-URL: Homepage, https://github.com/darw007d/swarph-cli
-Project-URL: Source, https://github.com/darw007d/swarph-cli
-Project-URL: Substrate, https://github.com/darw007d/swarph-mesh
-Project-URL: Spec, https://github.com/darw007d/hedge-fund-mcp/blob/main/research/swarph_cli/PLAN.md
-Keywords: swarph,llm,cli,mesh,gemini,claude,deepseek
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: Utilities
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: swarph-mesh>=0.5.0
-Requires-Dist: swarph-shared>=0.2.0
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0; extra == "dev"
-Dynamic: license-file
-
 # swarph-cli
 
 The `swarph` binary — multi-LLM CLI with mesh-gateway integration. Thin client over the [`swarph-mesh`](https://github.com/darw007d/swarph-mesh) substrate.
@@ -49,16 +17,71 @@ This is one of three repos in the v0.3.x architecture:
 
 ## Status
 
-**v0.5.0 — Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL + Phase 5.5 onboard/ratify + Phase 5.6 daemon.** Six verbs ship:
+**v0.6.0 — Phase 7 spawn ships.** Seven verbs total:
 
 1. `swarph "prompt"` — Phase 2 one-shot mode (any of five providers)
 2. `swarph chat` — Phase 5 interactive REPL with multi-turn history + slash commands
-3. `swarph import <path>` — Phase 2.5 session import (Claude JSONL → swarph-native, with `--report-only` for honest pre-commit inspection)
-4. `swarph onboard <peer-name>` — Phase 5.5 mechanics-phase onboarding (PLAN.md §15.4)
-5. `swarph ratify <peer-name>` — Phase 5.5 witness ratification (PLAN.md §15.4a)
-6. `swarph daemon` — **NEW** Phase 5.6 foreground inbox drain loop (PLAN.md §16); structurally retires the orphaned-tail-F class
+3. `swarph spawn <role>` — **NEW** Phase 7 long-lived `claude` session as a named mesh cell (`--name`/`--session-id`/`--append-system-prompt` pinning per substrate-doc R7 §11.1.7 4-layer R2 stack)
+4. `swarph import <path>` — Phase 2.5 session import (Claude JSONL → swarph-native)
+5. `swarph onboard <peer-name>` — Phase 5.5 mechanics-phase onboarding (PLAN.md §15.4)
+6. `swarph ratify <peer-name>` — Phase 5.5 witness ratification (PLAN.md §15.4a)
+7. `swarph daemon` — Phase 5.6 foreground inbox drain (PLAN.md §16)
+
+Subsequent phases extend the CLI surface (`--ask <peer>`, REPL drain coroutine + `/inbox` + `/reply` slash commands in 5.6b; non-Claude `spawn` providers + S-G `mesh-gateway://` URL form in v0.7).
+
+### `swarph spawn` (Phase 7 — v0.6.0)
+
+Operator-tooling layer of substrate-doc R7 §11.1.7 4-layer R2 mechanism stack. Wraps `claude` with the three R5/R7 disambiguation flags:
+
+* `--name <role>` — display name for `/resume` picker
+* `--session-id <uuid>` — pinned UUID, persisted to `$XDG_STATE_HOME/swarph/sessions/<role>.session-id` so re-spawns reuse the same session (the R5 fix at the operator-tooling layer)
+* `--append-system-prompt <text>` — starter prompt injected without manual paste (the R2 fix at the operator-tooling layer)
+
+```bash
+# 1. Author a cell.yaml (one-time per role)
+$ cat ~/.config/swarph/cells/lab.yaml
+schema_version: v1
+name: lab-ovh
+role: lab
+cwd: /home/ubuntu
+starter_prompt_path: ~/.claude/session_start_reminder.txt
+provider: claude
+
+# 2. Summon the cell (long-lived claude session, exec-replaced)
+$ swarph spawn lab
+      ╭───╮
+      │ ◉ │
+   ╭──┴───┴──╮
+   │  swarph │  v0.6.0
+   ╰──┬───┬──╯       spawn │ chat │ daemon
+      │ ◉ │
+      ╰───╯
+[claude session takes over the terminal — same flags as `claude --name lab --session-id <uuid> --append-system-prompt <starter>`]
+
+# 3. Resume the same cell after exit — same UUID, same session
+$ swarph spawn lab     # picker shows ONE entry: "lab" (R5 disambiguation)
+```
+
+Resolution order for `swarph spawn <role-or-path>`:
+
+1. `--onboarding <path-or-url>` (alias: `--cell`) — explicit override
+2. Positional ending in `.yaml`/`.yml` or containing a path separator — literal path
+3. Plain role name — `$XDG_CONFIG_HOME/swarph/cells/<role>.yaml` (default `~/.config/swarph/cells/`)
+4. No positional given — auto-discover `./cell.yaml` in current directory
+
+Useful flags:
+
+| Flag | Effect |
+|---|---|
+| `--dry-run` | Print resolved `claude` command + cell summary; do not exec |
+| `--no-starter` | Skip starter-prompt injection even if cell.yaml sets one |
+| `--print-id` | Print resolved session-id to stdout (capture for shell scripts) |
+| `--no-banner` | Suppress the swarph banner on stderr |
+| `-- <claude-args>` | Pass remaining args through to claude unchanged |
+
+cell.yaml schema is **frozen at `schema_version: "v1"`**. v0.7 migrates the parser to `swarph-shared` as a symbol-relocation only — v0.6 cell.yaml files keep working unchanged. Breaking changes require a `schema_version: "v2"` bump and parallel-supported-version window per `swarph-mesh` DEPRECATIONS discipline.
 
-Subsequent phases extend the CLI surface (`--ask <peer>`, REPL drain coroutine + `/inbox` + `/reply` slash commands in 5.6b).
+**Known limitations (v0.6).** Single-instance-per-role only. Re-running `swarph spawn <role>` reuses the persisted UUID (R5 fix), so sibling-spawn (alpha + beta co-existing on the same peer-id) requires v0.7's `--new-instance` flag. Manual sibling spawning via `tmux` + explicit `--session-id` pinning still works unchanged; v0.6 does not regress that path, it just doesn't yet expose a CLI shape for it.
 
 ### `swarph daemon` (Phase 5.6)
 

{swarph_cli-0.5.0 → swarph_cli-0.7.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.5.0"
-description = "The `swarph` binary — multi-LLM CLI with mesh-gateway integration. v0.5.0 ships Phase 5.6 `swarph daemon` (foreground inbox drain — retires the orphaned-tail-F class) on top of Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL + Phase 5.5 onboard/ratify (PLAN.md §13 / §16)."
+version = "0.7.0"
+description = "The `swarph` binary — multi-LLM CLI with mesh-gateway integration. v0.7.0 ships Phase 7 substrate-doc R7 §11.1.7 operator-tooling layer in 5 increments: PR-A `--new-instance` flag (sibling-spawn case) + PR-B auto-suffix on collision (sibling-slot persistence) + PR-C SessionStart hook (closes bare-claude operator-paste gap) + watchdog (stranded-session recovery) + PR-D swarph-shared cell.yaml relocation (cell-yaml schema graduates to swarph-shared 0.3.0 kernel-tier; substrate-doc R7 §11.1.5 (O5) RESOLVED)."
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.10"
@@ -32,7 +32,16 @@ dependencies = [
     # Phase 5 REPL exercises all five adapters; bumped to 0.5.0 for
     # OpenAI + Grok availability in /provider switch.
     "swarph-mesh>=0.5.0",
-    "swarph-shared>=0.2.0",
+    # v0.7 PR-D step 2: swarph-shared 0.3.0 adds the cell module
+    # (universal cell.yaml schema; substrate-doc R7 §11.1.5 (O5)
+    # cell.yaml-format-home RESOLVED). swarph-cli's cell.py now
+    # re-exports data shapes from swarph_shared.cell + keeps file
+    # I/O + sidecar + slot allocation locally.
+    "swarph-shared>=0.3.0",
+    # Phase 7 spawn — cell.yaml parser. PyYAML 6.x is the standard.
+    # Stays a swarph-cli dep since file I/O is operator-tooling-layer
+    # concern; swarph-shared cell module is pure-stdlib.
+    "PyYAML>=6.0",
 ]
 
 [project.urls]

{swarph_cli-0.5.0 → swarph_cli-0.7.0}/src/swarph_cli/__init__.py

@@ -16,6 +16,6 @@ The architecture splits CLI from substrate so:
 
 from __future__ import annotations
 
-__version__ = "0.5.0"
+__version__ = "0.7.0"
 
 __all__ = ["__version__"]

swarph_cli-0.7.0/src/swarph_cli/cell.py

@@ -0,0 +1,360 @@
+"""``swarph_cli.cell`` — file I/O + sidecar + slot allocation (v0.7 PR-D step 2).
+
+After substrate-doc R7 §11.1.5 (O5) cell.yaml universal-genome relocation,
+the data shapes + schema validation live in ``swarph-shared`` (v0.3.0+).
+This module is the swarph-cli operator-tooling layer that consumes the
+shared schema + adds:
+
+* **File discovery**: ``cells_dir()``, ``discover_cell_in_cwd()``,
+  ``resolve_cell_path()``, ``is_mesh_gateway_url()``
+* **File I/O**: ``load_cell()`` (YAML read → ``parse_cell_dict()``),
+  ``_atomic_write_text()``
+* **Sidecar persistence**: ``session_state_path()``,
+  ``load_or_create_session_id()``
+* **Slot allocation** (substrate-doc R7 §11.1.7 operator-tooling layer
+  per beta #892 B1): ``next_free_slot_role()``,
+  ``base_role_from_slot_role()``
+
+Symbol-relocation only — the v0.6 + v0.7-pre-PR-D + v0.7-post-PR-D-step-2
+APIs are byte-for-byte identical at the swarph_cli.cell import level.
+v0.6 cell.yaml files keep working unchanged in v0.7+ per drop-mother
+review #890 (C2) schema-stability commitment.
+
+Re-export shim for backward-compat — historical imports still work:
+
+    from swarph_cli.cell import Cell, CellError, parse_cell_dict
+
+is equivalent to (and recommended going forward):
+
+    from swarph_shared.cell import Cell, CellError, parse_cell_dict
+
+Internal swarph-cli code uses the swarph-shared imports directly to
+avoid two-hop indirection. External consumers of swarph-cli's cell
+module continue to work unchanged.
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+from pathlib import Path
+from typing import Optional
+
+# Re-export data shapes + schema validation from swarph-shared 0.3.0+
+# (substrate-doc R7 §11.1.5 (O5) cell.yaml-format-home RESOLVED).
+from swarph_shared.cell import (
+    Cell,
+    CellError,
+    Lineage,
+    PEER_NAME_RE,
+    SCHEMA_VERSION_V1,
+    VALID_PROVIDERS,
+    VALID_SCHEMA_VERSIONS,
+    parse_cell_dict,
+    validate_uuid_str,
+)
+
+# Backward-compat aliases for v0.6 + v0.7-pre-PR-D-step-2 imports
+# (a few internal swarph-cli call sites used the leading-underscore shape).
+_PEER_NAME_RE = PEER_NAME_RE
+_VALID_SCHEMA_VERSIONS = VALID_SCHEMA_VERSIONS
+_VALID_PROVIDERS_V0_6 = VALID_PROVIDERS  # historical name for the v0.6 frozenset
+_validate_uuid = validate_uuid_str  # historical helper name
+
+
+def _config_root() -> Path:
+    """Return the active config root for cell lookups.
+
+    Honours ``$XDG_CONFIG_HOME`` per the XDG Base Directory spec; falls
+    back to ``~/.config/`` otherwise.
+    """
+    xdg = os.environ.get("XDG_CONFIG_HOME", "").strip()
+    if xdg:
+        return Path(xdg)
+    return Path.home() / ".config"
+
+
+def cells_dir() -> Path:
+    """Default lookup directory for ``<role>.yaml`` files."""
+    return _config_root() / "swarph" / "cells"
+
+
+def _state_root() -> Path:
+    xdg = os.environ.get("XDG_STATE_HOME", "").strip()
+    if xdg:
+        return Path(xdg)
+    return Path.home() / ".local" / "state"
+
+
+def session_state_path(role: str) -> Path:
+    """Return the per-role persisted-session-id file path.
+
+    v0.6 persists generated UUIDs OUTSIDE cell.yaml so the cell file
+    stays purely declarative and is safe to commit to git. Roles
+    re-spawned with the same role name resume the same session via
+    this state file.
+
+    v0.7 PR-B (beta #892 B1) extends this to per-slot sidecars for
+    sibling instances: ``<role>.session-id`` is slot 1; ``<role>-2``,
+    ``<role>-3`` etc. are siblings minted via ``--new-instance``.
+    See ``next_free_slot_role()`` for the slot allocation policy.
+    """
+    return _state_root() / "swarph" / "sessions" / f"{role}.session-id"
+
+
+def next_free_slot_role(base_role: str) -> str:
+    """Find the next free `<base_role>-N` slot for a sibling spawn.
+
+    v0.7 PR-B (beta #892 B1). Auto-suffix policy: siblings beyond
+    the first slot append ``-2``, ``-3``, ``-4`` etc. The naming
+    suffix matches the slot index, so:
+
+    * Slot 1 (the original): ``<base_role>``
+    * Slot 2 (first sibling): ``<base_role>-2``
+    * Slot 3 (second sibling): ``<base_role>-3``
+
+    Returns the synthesised role string for the next free slot.
+
+    Hard cap at slot 99 to avoid runaway loops.
+
+    Slot-reuse on unclean exit (beta iter-1 #987): a sibling instance
+    that dies without removing its sidecar leaves the slot
+    sidecar-occupied. Operator workaround at v0.7: ``rm`` the stale
+    sidecar. v0.8+ may ship ``swarph cleanup-sessions``.
+    """
+    for n in range(2, 100):
+        candidate = f"{base_role}-{n}"
+        if not session_state_path(candidate).exists():
+            return candidate
+    raise CellError(
+        f"next_free_slot_role: 99 sibling slots already occupied for "
+        f"base role {base_role!r}. Manual cleanup needed at "
+        f"{_state_root() / 'swarph' / 'sessions'}/."
+    )
+
+
+def base_role_from_slot_role(role: str) -> str:
+    """Strip a trailing ``-N`` slot suffix from a role string.
+
+    v0.7 PR-B. Lets ``swarph spawn <base-role>-2`` resolve back to
+    the cell.yaml at ``<base-role>.yaml`` for shared cell-context
+    (same cwd, starter-prompt, lineage, etc.) while the sidecar
+    + display name use the slot-suffixed role.
+
+    Returns ``role`` unchanged if no trailing ``-<N>`` suffix is
+    present (preserves v0.6 behavior for non-sibling spawns).
+    """
+    parts = role.rsplit("-", 1)
+    if len(parts) == 2 and parts[1].isdigit() and 2 <= int(parts[1]) <= 99:
+        return parts[0]
+    return role
+
+
+_MESH_GATEWAY_URL_PREFIX = "mesh-gateway://"
+
+
+def is_mesh_gateway_url(spec: str) -> bool:
+    """True for v0.7+ ``mesh-gateway://...`` URL inputs (alpha #891 D2)."""
+    return spec.startswith(_MESH_GATEWAY_URL_PREFIX)
+
+
+def resolve_cell_path(spec: str) -> Path:
+    """Resolve a ``swarph spawn`` positional/flag value to a cell file.
+
+    Precedence:
+      1. spec ends in ``.yaml`` or ``.yml`` → treated as a literal path
+      2. spec contains a path separator → treated as a literal path
+      3. ``./cell.yaml`` exists in current cwd AND spec equals current cwd's
+         basename OR equals a special token ``.`` → use ``./cell.yaml``
+      4. ``<cells_dir>/<spec>.yaml`` exists → use it
+      5. v0.7 PR-B sibling-resume — strip trailing ``-N`` suffix from spec
+         and try ``<cells_dir>/<base-role>.yaml`` (lets ``swarph spawn
+         drop-on-meta-edge-2`` resolve back to base cell.yaml so siblings
+         share cell-context). Honors operator-intent: explicit base file
+         takes precedence (step 4) over slot-stripped fallback (step 5).
+      6. otherwise → return ``<cells_dir>/<spec>.yaml`` (will fail on load
+         with a 'not found' error)
+    """
+    if spec == ".":
+        return Path.cwd() / "cell.yaml"
+    if spec.endswith((".yaml", ".yml")) or os.sep in spec:
+        return Path(spec).expanduser()
+
+    direct = cells_dir() / f"{spec}.yaml"
+    if direct.is_file():
+        return direct
+
+    # v0.7 PR-B sibling-resume fallback
+    base = base_role_from_slot_role(spec)
+    if base != spec:
+        base_path = cells_dir() / f"{base}.yaml"
+        if base_path.is_file():
+            return base_path
+
+    return direct  # not found; let load_cell raise with a clear error
+
+
+def discover_cell_in_cwd() -> Optional[Path]:
+    """Return ``./cell.yaml`` if it exists in the current cwd, else None."""
+    candidate = Path.cwd() / "cell.yaml"
+    return candidate if candidate.is_file() else None
+
+
+def read_starter_prompt(cell: Cell) -> Optional[str]:
+    """Return the starter-prompt text for ``cell``, or None.
+
+    Free function rather than ``Cell.starter_prompt_text()`` method —
+    swarph-shared Cell is intentionally pure-stdlib + no I/O, so the
+    file-read lives at the swarph-cli operator-tooling layer. Callers
+    that previously did ``cell.starter_prompt_text()`` now do
+    ``read_starter_prompt(cell)``.
+
+    Raises CellError if starter_prompt_path is set but unreadable, so
+    spawn fails loudly rather than silently dropping role-priming.
+    """
+    if cell.starter_prompt_path is None:
+        return None
+    try:
+        return cell.starter_prompt_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise CellError(
+            f"cell.yaml: starter_prompt_path "
+            f"'{cell.starter_prompt_path}' is not readable: {exc}"
+        ) from exc
+
+
+def load_cell(path: Path) -> Cell:
+    """Parse + validate a cell.yaml file. Raises CellError on any failure.
+
+    Reads YAML from disk, then delegates to ``swarph_shared.cell.parse_cell_dict``
+    for the actual schema validation. Sets ``cell.source_path`` to the
+    file path (a swarph-cli-specific provenance bit; swarph-shared
+    leaves it None since it doesn't know about the file).
+    """
+    import yaml  # local import — keeps `swarph --version` PyYAML-free
+
+    if not path.exists():
+        raise CellError(f"cell.yaml not found: {path}")
+
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise CellError(f"cell.yaml is not valid YAML ({path}): {exc}") from exc
+
+    cell = parse_cell_dict(raw, source=str(path), base_dir=path.parent)
+    # File-I/O wrapper concern: post-validate cwd reachability + tag source
+    # path. swarph-shared parse_cell_dict intentionally doesn't touch the
+    # filesystem (kernel-tier discipline); the live cwd.is_dir() check is
+    # the swarph-cli operator-tooling concern.
+    if not cell.cwd.is_dir():
+        raise CellError(f"cell.yaml: 'cwd' is not a directory: {cell.cwd}")
+    cell.source_path = path
+    return cell
+
+
+def load_or_create_session_id(
+    role: str,
+    cell: Cell,
+    new_instance: bool = False,
+) -> tuple[str, bool, str]:
+    """Resolve the session-id for a spawn invocation.
+
+    Returns ``(session_id, was_generated, effective_role)``.
+
+    Resolution order:
+      1. cell.session_id (cell.yaml-pinned) — never generated
+      2. ``new_instance=True`` AND base sidecar exists — auto-suffix slot
+      3. ``new_instance=True`` AND no base sidecar — fall through (degenerate)
+      4. session_state_path(role) reused — default re-resume path
+      5. mint new uuid4 + persist
+
+    Caller-side discipline (mother iter-1 #986): the ``effective_role``
+    value is the authoritative source for ``claude --name`` AND
+    sidecar persistence — NOT ``cell.role`` (which stays the BASE role
+    for shared cell-context: cwd, starter prompt, lineage, provider).
+    """
+    if cell.session_id:
+        return cell.session_id, False, role
+
+    if new_instance:
+        base_state = session_state_path(role)
+        if base_state.exists():
+            sibling_role = next_free_slot_role(role)
+            sibling_state = session_state_path(sibling_role)
+            new_id = str(uuid.uuid4())
+            sibling_state.parent.mkdir(parents=True, exist_ok=True)
+            _atomic_write_text(sibling_state, new_id + "\n")
+            return new_id, True, sibling_role
+
+    state_file = session_state_path(role)
+    if state_file.exists():
+        existing = state_file.read_text(encoding="utf-8").strip()
+        if existing:
+            try:
+                return validate_uuid_str(existing), False, role
+            except CellError:
+                # Corrupted state — fall through and regenerate.
+                pass
+
+    new_id = str(uuid.uuid4())
+    state_file.parent.mkdir(parents=True, exist_ok=True)
+    _atomic_write_text(state_file, new_id + "\n")
+    return new_id, True, role
+
+
+def _atomic_write_text(target: Path, content: str) -> None:
+    """Write text atomically: tempfile in the same dir, fsync, rename.
+
+    Per drop-mother review #890 (C1) — UUID writes are load-bearing for
+    R5 (session-resume identity disambiguation). A torn write that left
+    half a UUID in the state file would silently regenerate on next
+    spawn, defeating the disambiguation primitive entirely.
+    """
+    import tempfile
+
+    parent = target.parent
+    fd, tmp_path = tempfile.mkstemp(
+        prefix=f".{target.name}.", suffix=".tmp", dir=parent
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fp:
+            fp.write(content)
+            fp.flush()
+            os.fsync(fp.fileno())
+        os.replace(tmp_path, target)
+    except Exception:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise
+
+
+__all__ = [
+    # Re-exports from swarph_shared.cell (v0.3.0+)
+    "Cell",
+    "CellError",
+    "Lineage",
+    "PEER_NAME_RE",
+    "SCHEMA_VERSION_V1",
+    "VALID_PROVIDERS",
+    "VALID_SCHEMA_VERSIONS",
+    "parse_cell_dict",
+    "validate_uuid_str",
+    # swarph-cli-local file I/O + sidecar + slot allocation
+    "cells_dir",
+    "session_state_path",
+    "next_free_slot_role",
+    "base_role_from_slot_role",
+    "is_mesh_gateway_url",
+    "resolve_cell_path",
+    "discover_cell_in_cwd",
+    "read_starter_prompt",
+    "load_cell",
+    "load_or_create_session_id",
+    # Backward-compat aliases
+    "_PEER_NAME_RE",
+    "_VALID_SCHEMA_VERSIONS",
+    "_VALID_PROVIDERS_V0_6",
+    "_validate_uuid",
+]