@smilintux/skcapstone 0.9.0 → 0.12.5

package/src/skcapstone/cli/daemon.py

@@ -140,7 +140,8 @@ def register_daemon_commands(main: click.Group) -> None:
         effective_port = _resolve_agent_port(agent, port)
 
         if agent:
-            # Propagate identity to child imports that read SKCAPSTONE_AGENT.
+            # Propagate identity to child imports that read SKAGENT.
+            os.environ["SKAGENT"] = agent
             os.environ["SKCAPSTONE_AGENT"] = agent
 
         if not home_path.exists():
@@ -270,60 +271,120 @@ def register_daemon_commands(main: click.Group) -> None:
             console.print(f"  [yellow]API unreachable on port {effective_port}[/]\n")
 
     @daemon.command("install")
-    def daemon_install():
-        """Install the daemon as a systemd user service.
+    @click.option("--agent", "agent_name", default=None,
+                  help="Agent name for SKCAPSTONE_AGENT (default: from env or 'sovereign').")
+    @click.option("--start", is_flag=True, help="Start services immediately after installing.")
+    def daemon_install(agent_name: str | None, start: bool):
+        """Install the daemon as a system service.
 
-        Copies unit files to ~/.config/systemd/user/, enables at login,
-        and starts immediately. No root required.
+        On Linux: installs systemd user service units.
+        On macOS: installs launchd plist files to ~/Library/LaunchAgents/.
+
+        The --agent flag sets the SKCAPSTONE_AGENT environment variable
+        in the service definition. If not provided, uses the
+        SKCAPSTONE_AGENT env var or defaults to 'sovereign'.
 
         Examples:
 
             skcapstone daemon install
+
+            skcapstone daemon install --agent myagent --start
         """
-        from ..systemd import install_service, systemd_available
+        import platform
 
-        if not systemd_available():
-            console.print("[red]systemd user session not available.[/]")
-            console.print("[dim]This command requires a Linux system with systemd.[/]")
-            raise SystemExit(1)
+        effective_agent = agent_name or os.environ.get("SKCAPSTONE_AGENT", "sovereign")
 
-        console.print("\n[cyan]Installing skcapstone systemd service...[/]")
-        result = install_service()
+        if platform.system() == "Darwin":
+            from ..launchd import install_service as launchd_install
 
-        if result["installed"]:
-            console.print("[green]  Unit files installed.[/]")
-        if result["enabled"]:
-            console.print("[green]  Service enabled at login.[/]")
-        if result["started"]:
-            console.print("[green]  Service started.[/]")
-        console.print()
+            console.print(f"\n[cyan]Installing launchd services for agent '{effective_agent}'...[/]")
+            result = launchd_install(agent_name=effective_agent, start=start)
+
+            if result["installed"]:
+                for svc in result.get("services", []):
+                    status = "[green]loaded[/]" if svc.get("loaded") else "[green]installed[/]"
+                    console.print(f"  [green]✓[/] {svc['label']} — {status}")
+                console.print()
+                console.print("[dim]  Manage: launchctl list | grep skcapstone[/]")
+                if not start:
+                    console.print("[dim]  Start:  launchctl start com.skcapstone.daemon[/]")
+                    console.print("[dim]  Or re-run with --start to load immediately.[/]")
+            else:
+                console.print("[red]Installation failed. Check logs.[/]")
+                raise SystemExit(1)
+            console.print()
+
+        elif platform.system() == "Linux":
+            from ..systemd import install_service, systemd_available, SERVICE_NAME
+
+            if not systemd_available():
+                console.print("[red]systemd user session not available.[/]")
+                console.print("[dim]This command requires a Linux system with systemd.[/]")
+                raise SystemExit(1)
+
+            console.print(f"\n[cyan]Installing skcapstone systemd service for agent '{effective_agent}'...[/]")
+            result = install_service(agent_name=effective_agent, start=start)
+            svc_name = result.get("service_name", SERVICE_NAME)
+
+            if result["installed"]:
+                console.print(f"[green]  Unit files installed ({svc_name}).[/]")
+            if result["enabled"]:
+                console.print(f"[green]  Service enabled at login.[/]")
+            if result.get("started"):
+                console.print(f"[green]  Service started.[/]")
+            else:
+                console.print(f"[dim]  Start: systemctl --user start {svc_name}[/]")
+            console.print()
 
-        if not result["installed"]:
-            console.print("[red]Installation failed. Check logs.[/]")
+            if not result["installed"]:
+                console.print("[red]Installation failed. Check logs.[/]")
+                raise SystemExit(1)
+        else:
+            console.print(f"[red]Auto-start not supported on {platform.system()}.[/]")
             raise SystemExit(1)
 
     @daemon.command("uninstall")
     def daemon_uninstall():
-        """Uninstall the systemd user service.
+        """Uninstall the system service.
 
-        Stops, disables, and removes the unit files.
+        On Linux: stops, disables, and removes systemd unit files.
+        On macOS: unloads and removes launchd plist files.
 
         Examples:
 
             skcapstone daemon uninstall
         """
-        from ..systemd import uninstall_service
+        import platform
 
-        console.print("\n[cyan]Uninstalling skcapstone systemd service...[/]")
-        result = uninstall_service()
+        if platform.system() == "Darwin":
+            from ..launchd import uninstall_service as launchd_uninstall
 
-        if result["stopped"]:
-            console.print("[green]  Service stopped.[/]")
-        if result["disabled"]:
-            console.print("[green]  Service disabled.[/]")
-        if result["removed"]:
-            console.print("[green]  Unit files removed.[/]")
-        console.print()
+            console.print("\n[cyan]Uninstalling skcapstone launchd services...[/]")
+            result = launchd_uninstall()
+
+            if result["stopped"]:
+                console.print("[green]  Services unloaded.[/]")
+            if result["removed"]:
+                for label in result.get("services", []):
+                    console.print(f"  [green]✓[/] Removed {label}")
+            console.print()
+
+        elif platform.system() == "Linux":
+            from ..systemd import uninstall_service
+
+            console.print("\n[cyan]Uninstalling skcapstone systemd service...[/]")
+            result = uninstall_service()
+
+            if result["stopped"]:
+                console.print("[green]  Service stopped.[/]")
+            if result["disabled"]:
+                console.print("[green]  Service disabled.[/]")
+            if result["removed"]:
+                console.print("[green]  Unit files removed.[/]")
+            console.print()
+
+        else:
+            console.print(f"[red]Not supported on {platform.system()}.[/]")
 
     @daemon.command("components")
     @click.option("--agent", default=None, help="Named agent to query.")
@@ -413,7 +474,10 @@ def register_daemon_commands(main: click.Group) -> None:
     @click.option("--lines", "-n", default=50, help="Number of lines (default: 50).")
     @click.option("--follow", "-f", is_flag=True, help="Show the command to follow logs live.")
     def daemon_logs(lines: int, follow: bool):
-        """Show daemon logs from journald.
+        """Show daemon logs.
+
+        On Linux: reads from journald.
+        On macOS: reads from ~/.skcapstone/logs/ files.
 
         Examples:
 
@@ -423,14 +487,29 @@ def register_daemon_commands(main: click.Group) -> None:
 
             skcapstone daemon logs -f
         """
-        from ..systemd import service_logs
+        import platform
 
-        if follow:
-            cmd = service_logs(follow=True)
-            console.print(f"\n  Run: [bold cyan]{cmd}[/]\n")
+        if platform.system() == "Darwin":
+            if follow:
+                log_path = Path.home() / ".skcapstone" / "logs" / "daemon.stdout.log"
+                console.print(f"\n  Run: [bold cyan]tail -f {log_path}[/]\n")
+            else:
+                from ..launchd import service_logs
+                output = service_logs(lines=lines)
+                if output.strip():
+                    click.echo(output)
+                else:
+                    console.print("[dim]No logs found in ~/.skcapstone/logs/[/]")
+                    console.print("[dim]Is the service installed? Run: skcapstone daemon install[/]")
         else:
-            output = service_logs(lines=lines)
-            if output.strip():
-                click.echo(output)
+            from ..systemd import service_logs
+
+            if follow:
+                cmd = service_logs(follow=True)
+                console.print(f"\n  Run: [bold cyan]{cmd}[/]\n")
             else:
-                console.print("[dim]No logs found. Is the service installed?[/]")
+                output = service_logs(lines=lines)
+                if output.strip():
+                    click.echo(output)
+                else:
+                    console.print("[dim]No logs found. Is the service installed?[/]")

package/src/skcapstone/cli/gtd.py

@@ -108,10 +108,35 @@ def register_gtd_commands(main: click.Group) -> None:
         console.print()
 
     @gtd.command("status")
-    def gtd_status():
+    @click.option("--brief", is_flag=True,
+                  help="One-line summary (for hooks / session start).")
+    def gtd_status(brief: bool):
         """Summary of all GTD lists."""
         from ..mcp_tools.gtd_tools import _load_list, _GTD_LISTS
 
+        if brief:
+            from datetime import datetime, timezone
+
+            counts = {name: len(_load_list(name)) for name in _GTD_LISTS}
+            now = datetime.now(timezone.utc)
+            stale = 0
+            for p in _load_list("projects"):
+                ts = p.get("moved_at") or p.get("created_at")
+                try:
+                    if ts and (now - datetime.fromisoformat(ts)).days >= 7:
+                        stale += 1
+                except (ValueError, TypeError):
+                    pass
+            stale_str = f" ({stale} stale)" if stale else ""
+            click.echo(
+                f"GTD: {counts.get('inbox', 0)} inbox · "
+                f"{counts.get('next-actions', 0)} next · "
+                f"{counts.get('projects', 0)} projects{stale_str} · "
+                f"{counts.get('waiting-for', 0)} waiting · "
+                f"{counts.get('someday-maybe', 0)} someday"
+            )
+            return
+
         console.print()
         total = 0
         rows = []

package/src/skcapstone/cli/housekeeping.py

@@ -14,9 +14,9 @@ def register_housekeeping_commands(main: click.Group) -> None:
 
     @main.command("housekeeping")
     @click.option("--home", default=AGENT_HOME, type=click.Path(), help="Agent home directory.")
-    @click.option("--skcomm-home", default="~/.skcomm", type=click.Path(), help="SKComm home directory.")
+    @click.option("--skcomms-home", default="~/.skcomms", type=click.Path(), help="SKComms home directory.")
     @click.option("--dry-run", is_flag=True, help="Report what would be deleted without deleting.")
-    def housekeeping(home: str, skcomm_home: str, dry_run: bool):
+    def housekeeping(home: str, skcomms_home: str, dry_run: bool):
         """Prune stale ACKs, delivered envelopes, and old seeds.
 
         Reclaims disk space from files that accumulate in the agent
@@ -33,7 +33,7 @@ def register_housekeeping_commands(main: click.Group) -> None:
 
         results = run_housekeeping(
             skcapstone_home=Path(home).expanduser(),
-            skcomm_home=Path(skcomm_home).expanduser(),
+            skcomms_home=Path(skcomms_home).expanduser(),
             dry_run=dry_run,
         )
 

package/src/skcapstone/cli/identity_cmd.py

@@ -0,0 +1,378 @@
+"""Identity commands: migrate.
+
+The ``skcapstone identity migrate`` command backfills every provisioned
+agent's ``identity/identity.json`` with the explicit sovereign-identity
+fields the unified layer expects (skcomms T2 / epic ``2b264064``):
+
+  * ``realm`` + ``operator`` — mirrored from ``cluster.json``.
+  * ``fqid`` — the three-tier ``<agent>@<operator>.<realm>`` label, sourced
+    from :func:`capauth.resolve_agent_identity` (the canonical resolver).
+  * ``pgp_fingerprint`` — the agent's 40-char PGP fingerprint, also from the
+    resolver / the agent's CapAuth profile.
+
+This command does **not** reimplement identity logic — it delegates to
+``capauth.resolve_agent_identity`` for the per-agent identity and only mirrors
+``realm``/``operator`` from cluster.json directly (those are cluster facts, not
+agent facts). It is a *walker*: it finds every provisioned agent (one with a
+CapAuth home, never a ``*-template``) and merges the missing fields into its
+identity.json without clobbering unrelated keys.
+
+Safety: these are LIVE identity files, so the command defaults to a dry-run
+(it prints a plan and writes nothing). Pass ``--apply`` (alias ``--write``) to
+actually modify files. The operation is idempotent — a second run on an
+already-complete home reports every agent as unchanged.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+import click
+
+from ._common import SHARED_ROOT, console
+
+# Fields the walker backfills, in stable display order.
+_MANAGED_FIELDS = ("realm", "operator", "fqid", "pgp_fingerprint")
+
+# cluster.json search path (mirrors capauth.agent_identity._CLUSTER_LOOKUP so
+# realm/operator come from the same source the resolver uses for the fqid).
+_CLUSTER_LOOKUP = [
+    Path("/etc/skcapstone/cluster.json"),
+]
+
+
+@dataclass
+class AgentPlan:
+    """Planned identity.json changes for a single agent.
+
+    Attributes:
+        agent: Short agent name.
+        path: Path to the agent's identity/identity.json.
+        additions: Field → value mapping that would be written. Empty when
+            the agent is already complete (nothing to add).
+        applied: Whether the additions were actually written to disk.
+        error: Non-empty when the agent could not be processed (e.g. an
+            unreadable identity.json); such agents are skipped, not crashed.
+    """
+
+    agent: str
+    path: Path
+    additions: dict[str, str] = field(default_factory=dict)
+    applied: bool = False
+    error: str = ""
+
+    @property
+    def changed(self) -> bool:
+        """True when this agent has at least one field to add."""
+        return bool(self.additions)
+
+
+@dataclass
+class MigrationPlan:
+    """Aggregate plan across every walked agent.
+
+    Attributes:
+        home: Shared root that was walked (``~/.skcapstone``).
+        dry_run: True when nothing was written to disk.
+        cluster_found: Whether a cluster.json was located (realm/operator are
+            unavailable when False).
+        agents: Per-agent plans (one per provisioned, non-template agent).
+    """
+
+    home: Path
+    dry_run: bool
+    cluster_found: bool
+    agents: list[AgentPlan] = field(default_factory=list)
+
+    @property
+    def changed_count(self) -> int:
+        """Number of agents with at least one field to add."""
+        return sum(1 for a in self.agents if a.changed)
+
+    @property
+    def unchanged_count(self) -> int:
+        """Number of already-complete agents (no additions, no error)."""
+        return sum(1 for a in self.agents if not a.changed and not a.error)
+
+    def to_dict(self) -> dict:
+        """Serialise to a JSON-friendly dict."""
+        return {
+            "home": str(self.home),
+            "dry_run": self.dry_run,
+            "cluster_found": self.cluster_found,
+            "changed": self.changed_count,
+            "unchanged": self.unchanged_count,
+            "agents": [
+                {
+                    "agent": a.agent,
+                    "path": str(a.path),
+                    "additions": a.additions,
+                    "applied": a.applied,
+                    "error": a.error,
+                }
+                for a in self.agents
+            ],
+        }
+
+
+def _load_cluster(home: Path) -> Optional[dict]:
+    """Load cluster.json from ``/etc/skcapstone`` then the agent home.
+
+    Mirrors :data:`capauth.agent_identity._CLUSTER_LOOKUP` but resolves the
+    home-local copy relative to *home* so a test (or alternate root) reads the
+    fixture cluster.json rather than the real ``~/.skcapstone`` one.
+
+    Args:
+        home: Shared root directory being walked.
+
+    Returns:
+        The parsed cluster dict, or ``None`` when no cluster.json exists or it
+        cannot be parsed.
+    """
+    for path in [*_CLUSTER_LOOKUP, home / "cluster.json"]:
+        if path.exists():
+            try:
+                return json.loads(path.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError):
+                continue
+    return None
+
+
+def _provisioned_agents(home: Path) -> list[str]:
+    """List agents with a CapAuth home (and thus a real identity).
+
+    Reuses the "provisioned agent" notion from
+    :func:`skcapstone.doctor._provisioned_agents`: an agent counts only when
+    ``agents/<name>/capauth/`` exists, and ``*-template`` scaffolds are
+    excluded.
+
+    Args:
+        home: Shared root directory (``~/.skcapstone``).
+
+    Returns:
+        Sorted provisioned agent names.
+    """
+    from ..doctor import _provisioned_agents as _doctor_provisioned
+
+    return _doctor_provisioned(home)
+
+
+def _plan_agent(home: Path, agent: str, cluster: Optional[dict]) -> AgentPlan:
+    """Compute the identity.json additions for one agent.
+
+    Reads the agent's current ``identity/identity.json`` and determines which
+    of ``realm``/``operator``/``fqid``/``pgp_fingerprint`` are missing, using
+    cluster.json (realm/operator) and ``capauth.resolve_agent_identity`` (fqid
+    + fingerprint) as the source of truth. Existing values are never
+    overwritten.
+
+    Args:
+        home: Shared root directory.
+        agent: Short agent name.
+        cluster: Parsed cluster.json dict, or ``None``.
+
+    Returns:
+        An :class:`AgentPlan` describing the additions (empty when complete or
+        when no source value is available), or carrying an ``error`` when the
+        identity.json is unreadable.
+    """
+    path = home / "agents" / agent / "identity" / "identity.json"
+    plan = AgentPlan(agent=agent, path=path)
+
+    existing: dict = {}
+    if path.exists():
+        try:
+            loaded = json.loads(path.read_text(encoding="utf-8"))
+            if isinstance(loaded, dict):
+                existing = loaded
+        except (json.JSONDecodeError, OSError) as exc:
+            plan.error = f"unreadable identity.json: {exc}"
+            return plan
+
+    # realm / operator come straight from cluster.json (cluster facts).
+    desired: dict[str, Optional[str]] = {}
+    if cluster is not None:
+        desired["realm"] = cluster.get("realm")
+        desired["operator"] = cluster.get("operator")
+
+    # fqid + pgp_fingerprint come from the canonical resolver — never
+    # reimplemented here (epic 2b264064; capauth is the source of truth).
+    try:
+        from capauth import resolve_agent_identity
+
+        ident = resolve_agent_identity(agent)
+        desired["fqid"] = getattr(ident, "fqid", None)
+        desired["pgp_fingerprint"] = getattr(ident, "fingerprint", None)
+    except Exception:  # noqa: BLE001 — resolver failure must not crash the walk
+        pass
+
+    for key in _MANAGED_FIELDS:
+        value = desired.get(key)
+        # Only add when we have a real value AND it is not already present.
+        if value and not existing.get(key):
+            plan.additions[key] = str(value)
+
+    return plan
+
+
+def migrate_identities(home: Path, *, apply: bool = False) -> MigrationPlan:
+    """Walk provisioned agents and backfill their identity.json.
+
+    For every provisioned agent (one with a CapAuth home, never a
+    ``*-template``), ensure its ``identity/identity.json`` carries ``realm``,
+    ``operator``, ``fqid`` and ``pgp_fingerprint``. Missing fields are merged
+    in without clobbering unrelated keys; files are only written when something
+    actually changed.
+
+    Args:
+        home: Shared root directory (``~/.skcapstone``).
+        apply: When ``True``, write the changes to disk. When ``False`` (the
+            default — these are live files), nothing is written and the
+            returned plan is a preview only.
+
+    Returns:
+        A :class:`MigrationPlan` describing per-agent additions and whether
+        each was applied.
+
+    Examples:
+        >>> plan = migrate_identities(Path("~/.skcapstone").expanduser())
+        >>> plan.dry_run
+        True
+    """
+    cluster = _load_cluster(home)
+    plan = MigrationPlan(
+        home=home,
+        dry_run=not apply,
+        cluster_found=cluster is not None,
+    )
+
+    for agent in _provisioned_agents(home):
+        agent_plan = _plan_agent(home, agent, cluster)
+        if apply and agent_plan.changed and not agent_plan.error:
+            try:
+                _apply_additions(agent_plan)
+                agent_plan.applied = True
+            except OSError as exc:
+                agent_plan.error = f"write failed: {exc}"
+        plan.agents.append(agent_plan)
+
+    return plan
+
+
+def _apply_additions(plan: AgentPlan) -> None:
+    """Merge a plan's additions into its identity.json on disk.
+
+    Reads the current file (or starts from ``{}`` if absent), updates only the
+    planned keys, and writes the result back with stable indentation. Unrelated
+    keys are preserved.
+
+    Args:
+        plan: The agent plan whose ``additions`` should be persisted.
+
+    Raises:
+        OSError: If the file cannot be read or written.
+    """
+    data: dict = {}
+    if plan.path.exists():
+        try:
+            loaded = json.loads(plan.path.read_text(encoding="utf-8"))
+            if isinstance(loaded, dict):
+                data = loaded
+        except json.JSONDecodeError:
+            data = {}
+    data.update(plan.additions)
+    plan.path.parent.mkdir(parents=True, exist_ok=True)
+    plan.path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def register_identity_commands(main: click.Group) -> None:
+    """Register the ``identity`` command group on the main CLI."""
+
+    @main.group()
+    def identity():
+        """Identity management — migrate per-agent identity.json files."""
+
+    @identity.command("migrate")
+    @click.option(
+        "--home", default=SHARED_ROOT, type=click.Path(),
+        help="Shared root directory (~/.skcapstone).",
+    )
+    @click.option(
+        "--apply", "--write", "apply_", is_flag=True,
+        help="Actually write changes. Default is a dry-run (writes nothing).",
+    )
+    @click.option(
+        "--dry-run", is_flag=True,
+        help="Explicitly preview only (the default). Overrides --apply if both given.",
+    )
+    @click.option("--json-out", is_flag=True, help="Output as machine-readable JSON.")
+    def migrate(home: str, apply_: bool, dry_run: bool, json_out: bool) -> None:
+        """Backfill realm/operator/fqid/pgp_fingerprint into agent identity.json.
+
+        Walks every provisioned agent (one with a CapAuth home, excluding
+        ``*-template`` dirs) under ``~/.skcapstone/agents/`` and ensures each
+        agent's ``identity/identity.json`` carries the explicit sovereign
+        fields. Delegates to ``capauth.resolve_agent_identity`` for the fqid
+        and fingerprint; realm/operator are mirrored from cluster.json.
+
+        SAFETY: defaults to a dry-run (prints a plan, writes nothing). Pass
+        ``--apply`` (or ``--write``) to actually modify the live identity
+        files. Idempotent — re-running on a complete home changes nothing.
+        """
+        home_path = Path(home).expanduser()
+        do_apply = apply_ and not dry_run
+        plan = migrate_identities(home_path, apply=do_apply)
+
+        if json_out:
+            click.echo(json.dumps(plan.to_dict(), indent=2))
+            return
+
+        _render_plan(plan)
+
+    return None
+
+
+def _render_plan(plan: MigrationPlan) -> None:
+    """Render a migration plan as human-readable Rich output."""
+    mode = "[yellow]DRY-RUN[/] (no files written — pass --apply to write)" \
+        if plan.dry_run else "[green]APPLY[/] (files written)"
+    console.print()
+    console.print(f"  [bold]identity migrate[/]  {mode}")
+    console.print(f"  [dim]{plan.home}[/]")
+    if not plan.cluster_found:
+        console.print(
+            "  [yellow]~ cluster.json not found — realm/operator unavailable, "
+            "fqid may be incomplete[/]"
+        )
+    console.print()
+
+    if not plan.agents:
+        console.print("  [dim]No provisioned agents found (none with a CapAuth home).[/]")
+        console.print()
+        return
+
+    for a in plan.agents:
+        if a.error:
+            console.print(f"  [red]✗ {a.agent}[/]  {a.error}")
+        elif not a.changed:
+            console.print(f"  [green]✓ {a.agent}[/]  [dim]unchanged (already complete)[/]")
+        else:
+            verb = "added" if a.applied else "would add"
+            fields = ", ".join(f"{k}={v}" for k, v in a.additions.items())
+            color = "green" if a.applied else "cyan"
+            console.print(f"  [{color}]→ {a.agent}[/]  {verb}: {fields}")
+        console.print(f"     [dim]{a.path}[/]")
+
+    console.print()
+    summary = (
+        f"  {plan.changed_count} to change, {plan.unchanged_count} unchanged"
+        if plan.dry_run
+        else f"  {plan.changed_count} changed, {plan.unchanged_count} unchanged"
+    )
+    console.print(f"[bold]{summary}[/]")
+    if plan.dry_run and plan.changed_count:
+        console.print("  [dim]Re-run with --apply to write these changes.[/]")
+    console.print()

package/src/skcapstone/cli/joule_cmd.py

@@ -439,7 +439,7 @@ def register_joule_commands(main: click.Group) -> None:
     @joule_group.command("dashboard")
     @click.option(
         "--agent", "-a", "agent_name", default=None,
-        help="Agent name (default: lumina).",
+        help="Agent name (default: current agent).",
     )
     def dashboard_cmd(agent_name: str | None):
         """Show a financial dashboard for an agent."""
@@ -451,7 +451,9 @@ def register_joule_commands(main: click.Group) -> None:
 
         from ..skjoule import JouleEngine, TransactionKind
 
-        agent_name = agent_name or "lumina"
+        from .. import active_agent_name
+
+        agent_name = agent_name or active_agent_name()
         engine = JouleEngine(home=Path(SHARED_ROOT).expanduser())
         wallet = engine.get_wallet(agent_name)
         balance = wallet.balance
@@ -624,4 +626,6 @@ def _resolve_agent(agent_name: str | None) -> str:
     if agent_name:
         return agent_name
     from .. import SKCAPSTONE_AGENT
-    return SKCAPSTONE_AGENT or "lumina"
+    from .. import active_agent_name
+
+    return SKCAPSTONE_AGENT or active_agent_name() or ""