@event4u/agent-config 2.26.0 → 3.1.0

package/scripts/_cli/cmd_doctor.py

@@ -17,14 +17,21 @@ Drift categories (manifest ↔ filesystem):
   (P5.2). Hand-edited tags or accidental cross-package writes show up
   here; files without frontmatter are skipped (P5.1 contract).
 
-Health checks (nine categories, see :data:`CHECK_IDS`):
+Health checks (see :data:`CHECK_IDS`):
 scope · manifest-integrity · lockfile-freshness · bridge-drift ·
 mcp-mode · mcp-beta-readiness · offline-readiness · python-runtime ·
-unsupported-combos.
+tier-usage-readiness · council-cli · unsupported-combos ·
+wizard-state.
 Each emits a structured ``{id, status, message, remedy}`` record with
 ``status`` ∈ ``ok`` / ``warn`` / ``fail`` (rendered ``✅`` / ``⚠️`` /
 ``❌``). ``--check <id>`` runs a single check.
 
+Repair affordances: ``--repair wizard-state`` resets a malformed or
+orphaned ``state/wizard-state.json`` under the user-global root (the
+file the unified Setup-Wizard uses for resume continuity). Used as the
+recovery path when ``1.9``'s npm downgrade is not viable
+(road-to-global-only-install § 1.10 / A6).
+
 Exit codes: ``0`` (clean) · ``1`` (drift or any ``fail`` check) · ``2``
 (error such as "manifest missing"). Both human and ``--json`` output
 emit the drift category lists and the structured checks array. Every
@@ -443,8 +450,16 @@ CHECK_IDS = (
     "tier-usage-readiness",
     "council-cli",
     "unsupported-combos",
+    "wizard-state",
 )
 
+#: Repair targets that ``--repair <id>`` accepts. Each id maps to a
+#: function in :func:`_run_repair` that resets the named artefact and
+#: returns an exit code. Additive set: introduce by adding a new id
+#: here, a runner inside :func:`_run_repair`, and (optionally) a
+#: matching health check above.
+REPAIR_IDS = ("wizard-state",)
+
 #: Six gates that govern the MCP `experimental → beta` promotion. The
 #: artefact path under each gate id mirrors `tests/test_mcp_beta_gates.py`
 #: and the contract in `docs/contracts/mcp-beta-criteria.md`.
@@ -846,7 +861,7 @@ _CLI_PROVIDER_META: dict[str, tuple[str, bool]] = {
 def _check_council_cli(project_root: Path) -> dict[str, Any]:
     """Health-probe each enabled ``mode: cli`` council member.
 
-    For every CLI member in ``agents/.ai-council.yml`` reports binary
+    For every CLI member in ``agents/settings/.ai-council.yml`` reports binary
     presence (via ``shutil.which``), billable flag, daily-quota state
     (used/cap or used/—), and rolls up to a single status icon.
 
@@ -862,14 +877,14 @@ def _check_council_cli(project_root: Path) -> dict[str, Any]:
     - ``warn`` — at least one binary is missing OR usage crosses
       ``warn_at`` for at least one capped member.
     - returns ``ok`` with "no council config" if
-      ``agents/.ai-council.yml`` is absent (consumer project that
+      ``agents/settings/.ai-council.yml`` is absent (consumer project that
       hasn't enabled the council yet).
     """
-    council_path = project_root / "agents" / ".ai-council.yml"
+    council_path = project_root / "agents" / "settings" / ".ai-council.yml"
     if not council_path.exists():
         return {
             "id": "council-cli", "status": "ok",
-            "message": "no council config (agents/.ai-council.yml not present)",
+            "message": "no council config (agents/settings/.ai-council.yml not present)",
             "remedy": "",
         }
     try:
@@ -887,7 +902,7 @@ def _check_council_cli(project_root: Path) -> dict[str, Any]:
         return {
             "id": "council-cli", "status": "warn",
             "message": f"council config invalid: {exc}",
-            "remedy": "fix agents/.ai-council.yml and re-run doctor",
+            "remedy": "fix agents/settings/.ai-council.yml and re-run doctor",
         }
     cli_members: list[tuple[str, Any]] = [
         (name, m) for name, m in cfg.members.items()
@@ -983,6 +998,88 @@ def _check_unsupported_combos(manifest: dict[str, Any]) -> dict[str, Any]:
     }
 
 
+def _wizard_state_path() -> Path:
+    """Return the on-disk location of the unified Setup-Wizard state file.
+
+    Mirrors ``STATE_REL`` in :mod:`src/server/routes/wizard.ts` — the
+    server writes ``<writeRoot>/state/wizard-state.json``. Under the
+    global-only install scope (ADR-020) ``writeRoot`` resolves to
+    :func:`user_global_paths.event4u_root` (typically
+    ``~/.event4u/agent-config/``); the ``EVENT4U_CONFIG_HOME`` override
+    is honoured implicitly so tests stay hermetic.
+    """
+    from scripts._lib.user_global_paths import event4u_root
+    return event4u_root() / "state" / "wizard-state.json"
+
+
+def _check_wizard_state() -> dict[str, Any]:
+    """Health-check the resumable Setup-Wizard state file.
+
+    Returns ``ok`` when the file is absent (no active session) or when
+    its JSON shape matches the contract from
+    :mod:`src/server/routes/wizard.ts` (``step: int``, ``partial: dict``,
+    optional ``totalSteps: int``, ``startedAt: str | null``).
+    Returns ``fail`` when the file exists but is unreadable, not valid
+    JSON, or violates the shape — ``--repair wizard-state`` resets it.
+    """
+    state_pth = _wizard_state_path()
+    if not state_pth.exists():
+        return {
+            "id": "wizard-state", "status": "ok",
+            "message": "no active wizard session",
+            "remedy": "",
+        }
+    try:
+        raw = state_pth.read_text(encoding="utf-8")
+    except OSError as exc:
+        return {
+            "id": "wizard-state", "status": "fail",
+            "message": f"unreadable wizard-state at {state_pth}: {exc}",
+            "remedy": "agent-config doctor --repair wizard-state",
+        }
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        return {
+            "id": "wizard-state", "status": "fail",
+            "message": f"malformed JSON in wizard-state ({exc.msg} at line {exc.lineno})",
+            "remedy": "agent-config doctor --repair wizard-state",
+        }
+    if not isinstance(data, dict):
+        return {
+            "id": "wizard-state", "status": "fail",
+            "message": f"wizard-state root is {type(data).__name__}, expected object",
+            "remedy": "agent-config doctor --repair wizard-state",
+        }
+    step = data.get("step")
+    partial = data.get("partial", {})
+    if not isinstance(step, int) or step < 0:
+        return {
+            "id": "wizard-state", "status": "fail",
+            "message": f"wizard-state.step is {step!r}, expected non-negative integer",
+            "remedy": "agent-config doctor --repair wizard-state",
+        }
+    if not isinstance(partial, dict):
+        return {
+            "id": "wizard-state", "status": "fail",
+            "message": f"wizard-state.partial is {type(partial).__name__}, expected object",
+            "remedy": "agent-config doctor --repair wizard-state",
+        }
+    total = data.get("totalSteps")
+    if total is not None and (not isinstance(total, int) or total < 1):
+        return {
+            "id": "wizard-state", "status": "fail",
+            "message": f"wizard-state.totalSteps is {total!r}, expected positive integer or omitted",
+            "remedy": "agent-config doctor --repair wizard-state",
+        }
+    suffix = f" of {total}" if isinstance(total, int) else ""
+    return {
+        "id": "wizard-state", "status": "ok",
+        "message": f"resumable wizard session at step {step + 1}{suffix}",
+        "remedy": "",
+    }
+
+
 def _run_checks(
     project_root: Path,
     manifest: dict[str, Any],
@@ -1008,6 +1105,7 @@ def _run_checks(
         "tier-usage-readiness": lambda: _check_tier_usage_readiness(project_root),
         "council-cli": lambda: _check_council_cli(project_root),
         "unsupported-combos": lambda: _check_unsupported_combos(manifest),
+        "wizard-state": _check_wizard_state,
     }
     out: list[dict[str, Any]] = []
     for cid in CHECK_IDS:
@@ -1115,6 +1213,14 @@ def _parse(argv: list[str]) -> argparse.Namespace:
               "layer chain, wrapper, and install-mode; short-circuits "
               "the drift report"),
     )
+    parser.add_argument(
+        "--repair", default=None, metavar="ID",
+        choices=list(REPAIR_IDS),
+        help=("reset a recoverable artefact and exit "
+              f"({' · '.join(REPAIR_IDS)}); short-circuits the drift "
+              "report. Idempotent — absent files report 'nothing to "
+              "repair' and exit 0."),
+    )
     return parser.parse_args(argv)
 
 
@@ -1165,8 +1271,50 @@ def _run_context(opts: argparse.Namespace) -> int:
     return 0
 
 
+def _run_repair(opts: argparse.Namespace) -> int:
+    """Handle ``--repair <id>``: reset the named artefact, no drift report.
+
+    Currently the only target is ``wizard-state`` — unlinks the
+    resumable session file so the next ``agent-config setup`` boots
+    from step 1. Absent files are a no-op (idempotent re-run).
+    """
+    target = opts.repair
+    if target == "wizard-state":
+        state_pth = _wizard_state_path()
+        payload = {
+            "id": "wizard-state",
+            "path": str(state_pth),
+            "action": "remove" if state_pth.exists() else "noop",
+        }
+        if state_pth.exists():
+            try:
+                state_pth.unlink()
+            except OSError as exc:
+                payload["action"] = "error"
+                payload["error"] = str(exc)
+                if opts.json:
+                    print(json.dumps(payload, indent=2))
+                else:
+                    print(f"❌  doctor: could not remove {state_pth}: {exc}",
+                          file=sys.stderr)
+                return 2
+        if opts.json:
+            print(json.dumps(payload, indent=2))
+        else:
+            if payload["action"] == "remove":
+                print(f"✅  doctor: reset wizard-state ({state_pth})")
+            else:
+                print(f"✅  doctor: nothing to repair (no wizard-state at {state_pth})")
+        return 0
+    # argparse `choices=` already constrains target; defensive default.
+    print(f"❌  doctor: unknown repair target {target!r}", file=sys.stderr)
+    return 2
+
+
 def main(argv: list[str] | None = None) -> int:
     opts = _parse(list(argv) if argv is not None else sys.argv[1:])
+    if opts.repair is not None:
+        return _run_repair(opts)
     if opts.trace_root:
         return _run_trace_root(opts)
     if opts.context:

package/scripts/_cli/cmd_explain.py

@@ -3,7 +3,7 @@
 Step-15 Phase 1 item 3. Answers the silent "why did the agent do that?"
 question by showing which inputs the loader / router consulted, in what
 order, and which one won. Read-only; never edits state, never dispatches
-network calls. Three subjects in the v1 surface:
+network calls. Four subjects in the surface:
 
 * ``config``           — full resolution chain for the active profile +
                          preset. Uses :mod:`scripts.config.profiles` and
@@ -15,6 +15,11 @@ network calls. Three subjects in the v1 surface:
 * ``route <text>``     — given prompt text, returns every tier-1 rule
                          whose trigger list matches plus kernel rules
                          (always active).
+* ``last``             — execution trace for the most recent ``/work``
+                         run. Aggregates the persisted ``.work-state.json``,
+                         council session, and memory hits into the
+                         ``ExplainTrace`` v1 contract (see
+                         ``docs/contracts/explain-trace.schema.json``).
 
 Exit codes: ``0`` clean, ``1`` not found / no match, ``2`` invocation
 error (bad project root, malformed ``router.json``).
@@ -37,6 +42,7 @@ from scripts._lib.agent_settings import (
 from scripts.config import presets, profiles
 
 ROUTER_FILENAME = "router.json"
+ROUTER_RELATIVE = Path("dist") / ROUTER_FILENAME
 
 
 def _resolve_root(arg: str | None) -> tuple[Path, str]:
@@ -55,7 +61,7 @@ def _load_user_settings(project_root: Path) -> dict[str, Any]:
 
 
 def _load_router(project_root: Path) -> dict[str, Any]:
-    path = project_root / ROUTER_FILENAME
+    path = project_root / ROUTER_RELATIVE
     if not path.exists():
         return {}
     try:
@@ -207,7 +213,92 @@ def _explain_route(project_root: Path, text: str, *, as_json: bool) -> int:
     return 0
 
 
+def _explain_last(
+    project_root: Path,
+    state_file: Path | None,
+    *,
+    as_json: bool,
+    quiet: bool,
+) -> int:
+    """Render the execution trace for the most recent ``/work`` run."""
+    from scripts._cli.explain_last import build_trace
+    from scripts._cli.explain_last.render import render as render_md
+    from scripts._cli.explain_last.state_loader import StateLoadError
+
+    settings = _load_user_settings(project_root)
+    explain_cfg = settings.get("explain") if isinstance(settings.get("explain"), dict) else {}
+    if explain_cfg.get("enable_last") is False:
+        print("explain last disabled by settings (explain.enable_last)")
+        return 0
+    target_state = state_file or project_root / ".work-state.json"
+    try:
+        trace = build_trace(project_root, target_state)
+    except StateLoadError as exc:
+        # BLOCKING council fix — never print absolute paths in errors;
+        # username leakage via /Users/<name>/... hits Slack / CI logs.
+        try:
+            rel = target_state.relative_to(project_root)
+        except ValueError:
+            rel = Path(target_state.name)
+        msg = str(exc).replace(str(target_state), str(rel))
+        print(f"❌  explain last: {msg}", file=sys.stderr)
+        return exc.exit_code
+    if as_json:
+        json.dump(trace, sys.stdout, indent=2, sort_keys=True)
+        sys.stdout.write("\n")
+        return 0
+    sys.stdout.write(render_md(trace, with_footer=not quiet))
+    return 0
+
+
+_LAST_HELP = """\
+usage: agent-config explain last [--project PATH] [--state-file PATH]
+                                 [--json] [--quiet]
+
+Reconstruct the execution trace for the most recent /work,
+/implement-ticket, /council, or /video run. Read-only; never
+makes network calls. Output is the ExplainTrace v1 contract:
+  docs/contracts/explain-trace.schema.json
+
+why-slots answered (Markdown sections; JSON keys in parens):
+
+  inputs       — profile / preset / cost_profile with per-knob source
+                 (pack | profile | preset | user | env | runtime |
+                  default)
+  route        — matched tier-1 rules · kernel rules · active persona
+                 (route)
+  memory       — memory-MCP entries that influenced this run, with
+                 hit-score + step-id (memory)
+  council      — council members consulted with per-member verdict
+                 (council)
+  assumptions  — assumptions recorded during refine + per-halt
+                 (assumptions)
+  pack         — discovery-manifest pack selection rationale (pack)
+  halt         — reason · step · surface for the most recent halt
+                 (halt; Phase 3)
+  provider     — /video provider selection rationale; omitted for
+                 non-video runs (provider; Phase 3)
+
+options:
+  --project PATH       project root (defaults to anchor walk from cwd)
+  --state-file PATH    .work-state.json path (default <root>/.work-state.json)
+  --json               emit ExplainTrace JSON instead of Markdown
+  --quiet              suppress the trailing tip footer
+
+exit codes:
+  0  trace rendered, or disabled by settings (explain.enable_last)
+  1  no recent run found (state file missing or unreadable)
+  2  invocation error (bad project root, bad --state-file path)
+"""
+
+
 def main(argv: list[str] | None = None) -> int:
+    argv_list = list(sys.argv[1:] if argv is None else argv)
+    if argv_list[:1] == ["last"] and any(
+        a in ("-h", "--help") for a in argv_list[1:]
+    ):
+        sys.stdout.write(_LAST_HELP)
+        return 0
     parser = argparse.ArgumentParser(
         prog="agent-config explain",
         description=(
@@ -216,7 +307,7 @@ def main(argv: list[str] | None = None) -> int:
         ),
     )
     parser.add_argument(
-        "subject", choices=("config", "rule", "route"),
+        "subject", choices=("config", "rule", "route", "last"),
         help="what to explain",
     )
     parser.add_argument(
@@ -227,14 +318,28 @@ def main(argv: list[str] | None = None) -> int:
         "--project", default=None,
         help="project root (defaults to anchor walk from cwd)",
     )
+    parser.add_argument(
+        "--state-file", default=None, dest="state_file",
+        help="path to .work-state.json (subject=last; default <root>/.work-state.json)",
+    )
     parser.add_argument(
         "--json", action="store_true", dest="as_json",
         help="emit JSON instead of human-readable text",
     )
+    parser.add_argument(
+        "--quiet", action="store_true",
+        help="suppress the trailing tip footer (subject=last)",
+    )
     opts = parser.parse_args(argv)
     project_root, _origin = _resolve_root(opts.project)
     if opts.subject == "config":
         return _explain_config(project_root, as_json=opts.as_json)
+    if opts.subject == "last":
+        state_path = Path(opts.state_file) if opts.state_file else None
+        return _explain_last(
+            project_root, state_path,
+            as_json=opts.as_json, quiet=opts.quiet,
+        )
     if opts.target is None:
         print(
             f"❌  explain: '{opts.subject}' requires a target argument",

package/scripts/_cli/cmd_migrate.py

@@ -49,8 +49,8 @@ GITIGNORE_BLOCK_END = "# <<< event4u/agent-config (managed) <<<"
 GITIGNORE_NEW_BODY = (
     ".agent-settings.yml\n"
     "agents/sessions/\n"
-    "agents/council-responses/\n"
-    "agents/council-sessions/\n"
+    "agents/runtime/council/responses/\n"
+    "agents/runtime/council/sessions/\n"
 )