devcouncil 0.1.1 → 0.3.0

package/src/devcouncil/cli/commands/runs.py

@@ -0,0 +1,223 @@
+"""`dev runs` — list and inspect per-run agent manifests.
+
+Coding-CLI executors write a manifest at
+``.devcouncil/runs/<run-id>/agent-run.json`` (prompt file, executor, profile,
+resolved command, exit status, run metadata). These commands let a developer or a
+supervisor list and inspect those runs without reading raw JSON, and flag a run
+whose status is still ``running`` but whose manifest has gone stale (the executor
+process likely crashed) as ``orphaned``.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from devcouncil.utils.redaction import redact_text
+
+app = typer.Typer(help="List and inspect coding-agent run manifests.")
+console = Console()
+
+# A run still marked ``running`` whose manifest has not been touched for longer
+# than this is treated as orphaned (the executor process likely died). Used as a
+# sane default; can be overridden per-call with --orphan-after.
+_DEFAULT_ORPHAN_AFTER_SECONDS = 600
+
+# Transcript/log files (in priority order) whose tail `dev runs show` surfaces.
+_TRANSCRIPT_CANDIDATES = ("transcript.txt", "transcript.log", "output.log", "run.log")
+_TRANSCRIPT_TAIL_LINES = 40
+
+
+def _runs_dir(project_root: Path) -> Path:
+    return project_root / ".devcouncil" / "runs"
+
+
+def _orphan_after_seconds(project_root: Path) -> int:
+    """Threshold (seconds) after which a stale ``running`` manifest is orphaned.
+
+    Config-driven when available (execution.lease_ttl_seconds is a reasonable
+    proxy for "how long a live run can plausibly stay quiet"); falls back to a
+    sane default so the command works before `dev init`."""
+    try:
+        from devcouncil.app.config import load_config
+
+        ttl = int(load_config(project_root).execution.lease_ttl_seconds)
+        if ttl > 0:
+            return ttl
+    except Exception:
+        pass
+    return _DEFAULT_ORPHAN_AFTER_SECONDS
+
+
+def _load_manifest(manifest_path: Path) -> dict | None:
+    try:
+        data = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _is_orphaned(manifest: dict, manifest_path: Path, *, orphan_after: int, now: float) -> bool:
+    """A run is orphaned when it is still ``running`` but its manifest file has
+    not been updated within the threshold — i.e. no heartbeat, executor gone."""
+    if manifest.get("status") != "running":
+        return False
+    try:
+        mtime = manifest_path.stat().st_mtime
+    except OSError:
+        return False
+    return (now - mtime) > max(0, orphan_after)
+
+
+def _run_summary(manifest: dict, manifest_path: Path, *, orphan_after: int, now: float) -> dict:
+    return {
+        "run_id": manifest.get("run_id") or manifest_path.parent.name,
+        "task_id": manifest.get("task_id"),
+        "agent": manifest.get("agent"),
+        "profile": manifest.get("profile"),
+        "status": manifest.get("status"),
+        "started_at": manifest.get("started_at") or manifest.get("timestamp"),
+        "finished_at": manifest.get("finished_at"),
+        "returncode": manifest.get("returncode"),
+        "orphaned": _is_orphaned(manifest, manifest_path, orphan_after=orphan_after, now=now),
+    }
+
+
+def _collect_runs(project_root: Path, *, orphan_after: int) -> list[dict]:
+    runs_dir = _runs_dir(project_root)
+    if not runs_dir.is_dir():
+        return []
+    now = time.time()
+    summaries: list[tuple[float, dict]] = []
+    for manifest_path in runs_dir.glob("*/agent-run.json"):
+        manifest = _load_manifest(manifest_path)
+        if manifest is None:
+            continue
+        try:
+            sort_key = manifest_path.stat().st_mtime
+        except OSError:
+            sort_key = 0.0
+        summaries.append((sort_key, _run_summary(manifest, manifest_path, orphan_after=orphan_after, now=now)))
+    # Newest first.
+    summaries.sort(key=lambda item: item[0], reverse=True)
+    return [summary for _, summary in summaries]
+
+
+def _find_transcript(run_dir: Path, manifest: dict) -> Path | None:
+    recorded = manifest.get("transcript")
+    if isinstance(recorded, str) and recorded:
+        candidate = Path(recorded)
+        if not candidate.is_absolute():
+            candidate = run_dir / recorded
+        if candidate.is_file():
+            return candidate
+    for name in _TRANSCRIPT_CANDIDATES:
+        candidate = run_dir / name
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _transcript_tail(path: Path, *, lines: int = _TRANSCRIPT_TAIL_LINES) -> str:
+    """Return the redacted tail of a transcript file (best-effort)."""
+    try:
+        content = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+    tail = content.splitlines()[-lines:]
+    return redact_text("\n".join(tail))
+
+
+@app.command("list")
+def list_runs(
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+    limit: int = typer.Option(20, "--limit", help="Maximum number of runs to show."),
+    status: str | None = typer.Option(None, "--status", help="Filter by run status (e.g. running, finished, failed, timeout)."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+) -> None:
+    """List recorded coding-agent runs, newest first."""
+    root = project_root.expanduser().resolve()
+    orphan_after = _orphan_after_seconds(root)
+    runs = _collect_runs(root, orphan_after=orphan_after)
+    if status:
+        runs = [run for run in runs if run.get("status") == status]
+    if limit > 0:
+        runs = runs[:limit]
+
+    if json_output:
+        console.print_json(data={"runs": runs, "count": len(runs)})
+        return
+
+    if not runs:
+        console.print("[dim]No agent runs found under .devcouncil/runs/.[/dim]")
+        return
+
+    table = Table(title="Agent runs")
+    table.add_column("Run ID", overflow="fold")
+    table.add_column("Task")
+    table.add_column("Agent")
+    table.add_column("Profile")
+    table.add_column("Status")
+    table.add_column("Started")
+    for run in runs:
+        status_text = str(run.get("status") or "?")
+        if run.get("orphaned"):
+            status_text = f"[red]{status_text} (orphaned)[/red]"
+        table.add_row(
+            str(run.get("run_id") or ""),
+            str(run.get("task_id") or ""),
+            str(run.get("agent") or ""),
+            str(run.get("profile") or ""),
+            status_text,
+            str(run.get("started_at") or ""),
+        )
+    console.print(table)
+
+
+@app.command("show")
+def show_run(
+    run_id: str = typer.Argument(..., help="The run id to inspect."),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+) -> None:
+    """Show the full manifest for a run plus a redacted transcript tail."""
+    root = project_root.expanduser().resolve()
+    run_dir = _runs_dir(root) / run_id
+    manifest_path = run_dir / "agent-run.json"
+    manifest = _load_manifest(manifest_path)
+    if manifest is None:
+        if json_output:
+            console.print_json(data={"ok": False, "error": f"Run {run_id} not found.", "run_id": run_id})
+        else:
+            console.print(f"[red]Run {run_id} not found under .devcouncil/runs/.[/red]")
+        raise typer.Exit(code=1)
+
+    orphan_after = _orphan_after_seconds(root)
+    orphaned = _is_orphaned(manifest, manifest_path, orphan_after=orphan_after, now=time.time())
+    transcript_path = _find_transcript(run_dir, manifest)
+    transcript_tail = _transcript_tail(transcript_path) if transcript_path else ""
+
+    if json_output:
+        console.print_json(data={
+            "ok": True,
+            "run_id": run_id,
+            "manifest": manifest,
+            "orphaned": orphaned,
+            "transcript_path": str(transcript_path) if transcript_path else None,
+            "transcript_tail": transcript_tail,
+        })
+        return
+
+    console.print_json(data=manifest)
+    if orphaned:
+        console.print("[red]This run is orphaned: still marked running but its manifest is stale.[/red]")
+    if transcript_path:
+        console.print(f"\n[bold]Transcript tail[/bold] [dim]({transcript_path})[/dim]:")
+        console.print(transcript_tail or "[dim](empty)[/dim]")
+    else:
+        console.print("\n[dim]No transcript file found for this run.[/dim]")

package/src/devcouncil/cli/commands/scaffold.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from devcouncil.repo.ci_scaffold import WORKFLOW_RELPATH, detect_stacks, scaffold_ci
+
+console = Console()
+
+
+def scaffold_ci_command(
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root to scaffold CI into."),
+    force: bool = typer.Option(False, "--force", help="Overwrite an existing devcouncil.yml workflow."),
+):
+    """Write a starter GitHub Actions workflow derived from the configured commands."""
+    root = project_root.expanduser().resolve()
+    if not (root / ".devcouncil").exists():
+        console.print("[red]DevCouncil is not initialized here. Run 'dev setup' first.[/red]")
+        raise typer.Exit(code=1)
+
+    target = scaffold_ci(root, force=force)
+    if target is None:
+        console.print(
+            f"[yellow]{WORKFLOW_RELPATH.as_posix()} already exists. "
+            f"Re-run with --force to overwrite.[/yellow]"
+        )
+        return
+
+    stacks = detect_stacks(root)
+    detected = ", ".join(sorted(stacks)) if stacks else "none auto-detected"
+    console.print(f"[green]Wrote {target.relative_to(root).as_posix()} (stacks: {detected}).[/green]")
+    console.print("[dim]Review the setup/install steps and commands before relying on it.[/dim]")

package/src/devcouncil/cli/commands/semantic.py

@@ -0,0 +1,47 @@
+import json
+import typer
+from pathlib import Path
+from rich.console import Console
+
+from devcouncil.cli.commands.init import initialize_project
+from devcouncil.indexing.semantic_index import SemanticIndex
+
+app = typer.Typer(help="Semantic snapshots and diffs.")
+console = Console()
+
+
+@app.command("snapshot")
+def snapshot(
+    task_id: str = typer.Argument(...),
+    stage: str = typer.Option("before", "--stage", help="before or after"),
+    project_root: Path = typer.Option(Path("."), "--project-root"),
+    json_format: bool = typer.Option(False, "--json"),
+):
+    root = project_root.expanduser().resolve()
+    initialize_project(root, quiet=True)
+    if stage not in {"before", "after"}:
+        console.print("[red]--stage must be before or after[/red]")
+        raise typer.Exit(code=2)
+    path = SemanticIndex(root).create_snapshot(task_id, stage)
+    payload = {"task_id": task_id, "stage": stage, "path": str(path)}
+    if json_format:
+        typer.echo(json.dumps(payload, indent=2))
+    else:
+        console.print(f"[green]Wrote semantic snapshot:[/green] {path}")
+
+
+@app.command("diff")
+def semantic_diff(
+    task_id: str = typer.Argument(...),
+    project_root: Path = typer.Option(Path("."), "--project-root"),
+    json_format: bool = typer.Option(False, "--json"),
+):
+    root = project_root.expanduser().resolve()
+    initialize_project(root, quiet=True)
+    result = SemanticIndex(root).diff(task_id)
+    if json_format:
+        typer.echo(json.dumps(result, indent=2))
+    else:
+        console.print(f"[cyan]Summary:[/cyan] {result['summary']}")
+        for item in result["classifications"]:
+            console.print(f" - {item['type']}: {item.get('path', '')}")

package/src/devcouncil/cli/commands/setup.py

@@ -8,18 +8,27 @@ import yaml
 from rich.console import Console
 from rich.panel import Panel
 
-from devcouncil.app.config import load_config, load_local_secrets, provider_api_key_env_var
+from devcouncil.app.config import (
+    _normalized_provider_name,
+    get_gcloud_access_token,
+    load_config,
+    load_local_secrets,
+    provider_api_key_env_var,
+)
 from devcouncil.cli.commands.doctor import render_doctor_check
-from devcouncil.cli.commands.init import initialize_project
+from devcouncil.cli.commands.init import initialize_project, parse_role_model_overrides
 from devcouncil.cli.commands.integrate import (
     _claude_command,
     _codex_command,
+    _configure_antigravity,
+    _configure_cursor,
     _configure_native_hooks,
+    _configure_opencode,
+    _configure_warp,
     _configure,
-    _cursor_command,
     _gemini_command,
 )
-from devcouncil.llm.provider import validate_model_provider
+from devcouncil.llm.provider import apply_provider_default_role_models, build_role_model_config, validate_model_provider
 
 app = typer.Typer()
 console = Console()
@@ -32,9 +41,36 @@ def _set_model_provider(project_root: Path, provider: str) -> None:
     raw_config.setdefault("models", {})
     previous = raw_config["models"].get("provider", "openrouter")
     raw_config["models"]["provider"] = normalized
+    updated_role_defaults = apply_provider_default_role_models(raw_config, previous, normalized)
     config_path.write_text(yaml.dump(raw_config, default_flow_style=False), encoding="utf-8")
     if previous != normalized:
         console.print(f"[green]Updated model provider from {previous} to {normalized}.[/green]")
+    if updated_role_defaults:
+        console.print(f"[green]Updated default role models for {normalized}.[/green]")
+
+
+def _set_model_roles(
+    project_root: Path,
+    model: str | None = None,
+    role_models: dict[str, str] | None = None,
+) -> None:
+    if not model and not role_models:
+        return
+
+    config_path = project_root / ".devcouncil" / "config.yaml"
+    raw_config = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    raw_config.setdefault("models", {})
+    provider = validate_model_provider(raw_config["models"].get("provider", "openrouter"))
+    raw_config["models"]["roles"] = build_role_model_config(
+        provider,
+        model=model,
+        role_models=role_models,
+    )
+    config_path.write_text(yaml.dump(raw_config, default_flow_style=False), encoding="utf-8")
+    if model:
+        console.print(f"[green]Updated all model roles to use {model}.[/green]")
+    for role, selected_model in (role_models or {}).items():
+        console.print(f"[green]Updated {role} to use {selected_model}.[/green]")
 
 
 def _write_local_secret(project_root: Path, env_var: str, value: str) -> Path:
@@ -54,9 +90,43 @@ def _write_local_secret(project_root: Path, env_var: str, value: str) -> Path:
     return path
 
 
+def _configure_vertexai_settings(
+    project_root: Path,
+    provider: str,
+    vertex_project: str | None,
+    vertex_location: str | None,
+) -> None:
+    if provider != "vertexai":
+        return
+
+    local_secrets = load_local_secrets(project_root)
+    if vertex_project:
+        _write_local_secret(project_root, "VERTEXAI_PROJECT", vertex_project)
+        console.print("[green]Saved VERTEXAI_PROJECT to .devcouncil/secrets.env.[/green]")
+    elif not (
+        os.environ.get("VERTEXAI_PROJECT")
+        or os.environ.get("GOOGLE_CLOUD_PROJECT")
+        or local_secrets.get("VERTEXAI_PROJECT")
+        or local_secrets.get("GOOGLE_CLOUD_PROJECT")
+    ):
+        console.print(
+            "[yellow]VERTEXAI_PROJECT is not set. "
+            "Set it in your shell or rerun setup with --vertex-project PROJECT_ID.[/yellow]"
+        )
+
+    if vertex_location:
+        _write_local_secret(project_root, "VERTEXAI_LOCATION", vertex_location)
+        console.print("[green]Saved VERTEXAI_LOCATION to .devcouncil/secrets.env.[/green]")
+
+
 def _configure_api_key(project_root: Path, api_key: str | None, skip_api_key: bool) -> None:
     config = load_config(project_root)
     provider = config.models.provider
+    if _normalized_provider_name(provider) == "ollama":
+        console.print(
+            "[green]Ollama uses a local server (default http://localhost:11434); no API key required.[/green]"
+        )
+        return
     env_var = provider_api_key_env_var(provider)
     local_secrets = load_local_secrets(project_root)
 
@@ -70,6 +140,9 @@ def _configure_api_key(project_root: Path, api_key: str | None, skip_api_key: bo
         _write_local_secret(project_root, env_var, api_key)
         console.print(f"[green]Saved {env_var} to .devcouncil/secrets.env.[/green]")
         return
+    if provider == "vertexai" and get_gcloud_access_token():
+        console.print("[green]Vertex AI access token is available from gcloud auth print-access-token.[/green]")
+        return
     if skip_api_key:
         console.print(f"[yellow]Skipped {env_var} setup. Model-backed commands will ask again if it is missing.[/yellow]")
         return
@@ -109,7 +182,6 @@ def _configure_coding_cli_integrations(project_root: Path, apply: bool, gemini_s
         ("Codex CLI", _codex_command(project_root)),
         ("Gemini CLI", _gemini_command(project_root, gemini_scope)),
         ("Claude Code", _claude_command(project_root, "local")),
-        ("Cursor", _cursor_command(project_root)),
     ]
     results = []
     for tool, command in commands:
@@ -117,6 +189,10 @@ def _configure_coding_cli_integrations(project_root: Path, apply: bool, gemini_s
             console.print(f"[yellow]{tool} CLI not found on PATH. Skipping optional integration.[/yellow]")
             continue
         results.append(_configure(tool, command, apply))
+    results.append(_configure_cursor(project_root, apply))
+    results.append(_configure_opencode(project_root, apply))
+    results.append(_configure_antigravity(project_root, apply))
+    results.append(_configure_warp(project_root, apply))
     _configure_native_hooks(project_root, "all", apply)
     if apply and any(not ok for ok in results):
         raise typer.Exit(code=1)
@@ -157,9 +233,20 @@ def setup(
     apply: bool = typer.Option(False, "--apply", help="Apply integration config instead of previewing commands."),
     gemini_scope: str = typer.Option("project", "--gemini-scope", help="Gemini MCP config scope: project or user."),
     provider: str | None = typer.Option(None, "--provider", help="Set models.provider before configuring the API key."),
+    model: str | None = typer.Option(None, "--model", "-m", help="Model id to use for every default role."),
+    role_model: list[str] | None = typer.Option(
+        None,
+        "--role-model",
+        help="Per-role model override in ROLE=MODEL form. Can be repeated.",
+    ),
     api_key: str | None = typer.Option(None, "--api-key", help="Store the configured provider API key in local .devcouncil/secrets.env."),
+    vertex_project: str | None = typer.Option(None, "--vertex-project", help="Store VERTEXAI_PROJECT for the vertexai provider."),
+    vertex_location: str | None = typer.Option(None, "--vertex-location", help="Store VERTEXAI_LOCATION for the vertexai provider. Defaults to global."),
     skip_api_key: bool = typer.Option(False, "--skip-api-key", help="Skip the first-run model API key prompt."),
     skip_integrations: bool = typer.Option(False, "--skip-integrations", help="Skip the first-run coding CLI integration prompt."),
+    skip_map: bool = typer.Option(False, "--skip-map", help="Skip generating repo_map.json and agent guides on init."),
+    skip_skills: bool = typer.Option(False, "--skip-skills", help="Skip scaffolding engineering skills into .claude/skills/ on init."),
+    scaffold_ci: bool = typer.Option(False, "--scaffold-ci", help="Write a starter .github/workflows/devcouncil.yml from the configured commands."),
 ):
     """
     Initialize DevCouncil from a normal terminal in the target repository root.
@@ -174,7 +261,44 @@ def setup(
         raise typer.Exit(code=2)
 
     root = project_root.expanduser().resolve()
-    created = initialize_project(root, project_name=name)
+    try:
+        role_models = parse_role_model_overrides(role_model)
+        initial_provider = validate_model_provider(provider) if provider else "openrouter"
+    except ValueError as e:
+        console.print(f"[red]{e}[/red]")
+        raise typer.Exit(code=2) from e
+
+    # Size the default local model to the host's memory ceiling (unified RAM on Apple
+    # Silicon, VRAM on a discrete GPU, system RAM otherwise) instead of the static 7b,
+    # so users on any OS get a capable council out of the box. Only when the user chose
+    # Ollama and did not pin a model.
+    if initial_provider == "ollama" and model is None:
+        from devcouncil import hardware
+
+        host = hardware.describe_host()
+        model = host.recommended_ollama_model
+        console.print(
+            f"[green]Detected {host.chip_label} ({host.memory_label}); "
+            f"defaulting Ollama model to {model}.[/green] "
+            "Override with --model, and pull it first: "
+            f"[bold]ollama pull {model}[/bold]."
+        )
+    elif initial_provider == "ollama" and model is not None:
+        # Model pinned explicitly — still remind the user it must be pulled locally.
+        console.print(
+            f"[green]Using Ollama model {model}.[/green] "
+            f"Pull it first if needed: [bold]ollama pull {model}[/bold]."
+        )
+
+    created = initialize_project(
+        root,
+        project_name=name,
+        model_provider=initial_provider,
+        model=model,
+        role_models=role_models,
+        with_map=not skip_map,
+        with_skills=not skip_skills,
+    )
     if not created:
         console.print(f"[yellow]DevCouncil is already initialized at {root / '.devcouncil'}.[/yellow]")
 
@@ -185,11 +309,24 @@ def setup(
             console.print(f"[red]{e}[/red]")
             raise typer.Exit(code=2) from e
 
+    _set_model_roles(root, model=model, role_models=role_models)
+
+    configured_provider = load_config(root).models.provider
+    _configure_vertexai_settings(root, configured_provider, vertex_project, vertex_location)
     _configure_api_key(root, api_key, skip_api_key)
 
     console.print()
     render_doctor_check(root)
 
+    if scaffold_ci:
+        from devcouncil.repo.ci_scaffold import WORKFLOW_RELPATH, scaffold_ci as scaffold_ci_workflow
+
+        written = scaffold_ci_workflow(root)
+        if written is None:
+            console.print(f"[yellow]{WORKFLOW_RELPATH.as_posix()} already exists; left unchanged.[/yellow]")
+        else:
+            console.print(f"[green]Wrote starter CI workflow {written.relative_to(root).as_posix()}.[/green]")
+
     if integrate:
         _configure_coding_cli_integrations(root, apply=apply, gemini_scope=gemini_scope)
     elif created and not skip_integrations:
@@ -213,6 +350,8 @@ def setup(
             "dev run TASK-001 --executor codex",
             "dev run TASK-001 --executor gemini",
             "dev run TASK-001 --executor claude",
+            "dev run TASK-001 --executor opencode",
+            "dev run TASK-001 --executor antigravity",
             "dev verify TASK-001",
             "",
             "Use [bold]dev setup --integrate[/bold] to preview coding CLI MCP and native hook setup.",

package/src/devcouncil/cli/commands/shell.py

@@ -0,0 +1,73 @@
+import typer
+from pathlib import Path
+from rich.console import Console
+
+from devcouncil.cli.commands.init import initialize_project
+from devcouncil.execution.shell_session import GuardedShellSession
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import TaskRepository
+
+console = Console()
+
+
+def shell(
+    task_id: str = typer.Argument(..., help="Task ID"),
+    command: str | None = typer.Option(None, "--command", help="Run one guarded command and exit."),
+    shell_name: str = typer.Option("auto", "--shell", help="Shell backend: auto, pwsh, bash, zsh."),
+    force: bool = typer.Option(False, "--force", help="Reclaim a stale lease from a previous (possibly crashed) session."),
+    project_root: Path = typer.Option(Path("."), "--project-root"),
+):
+    """
+    Run guarded shell commands for a task.
+    """
+    root = project_root.expanduser().resolve()
+    initialize_project(root, quiet=True)
+    db = get_db(root)
+    if not db:
+        console.print("[red]DevCouncil not initialized.[/red]")
+        raise typer.Exit(code=1)
+
+    with db.get_session() as session:
+        task = TaskRepository(session).get_by_id(task_id)
+        if not task:
+            console.print(f"[red]Task {task_id} not found.[/red]")
+            raise typer.Exit(code=1)
+
+    try:
+        session_runner = GuardedShellSession(root, task, shell=shell_name)
+    except ValueError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(code=2)
+    try:
+        session_runner.start(force=force)
+    except ValueError as exc:
+        # A live or stale lease from a prior session blocks a new one. Don't dump
+        # a traceback — tell the user how to recover.
+        console.print(f"[red]{exc}[/red]")
+        console.print(
+            "[yellow]Another shell session may be active for this task. If it is "
+            "stale (a previous session crashed), re-run with [bold]--force[/bold] to "
+            "reclaim it.[/yellow]"
+        )
+        raise typer.Exit(code=2)
+    try:
+        if command:
+            code = session_runner.run_one(command)
+            raise typer.Exit(code=code)
+
+        console.print(f"[cyan]Guarded shell for {task_id}. Type exit or quit to end.[/cyan]")
+        while True:
+            try:
+                line = input(f"devcouncil:{task_id}> ")
+            except (EOFError, KeyboardInterrupt):
+                break
+            normalized = line.strip()
+            if normalized.lower() in {"exit", "quit"}:
+                break
+            if not normalized:
+                continue
+            code = session_runner.run_one(normalized)
+            if code != 0:
+                console.print(f"[yellow]Command exited with {code}[/yellow]")
+    finally:
+        session_runner.finish()