lastlight 0.18.6 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lastlight",
-  "version": "0.18.6",
+  "version": "0.20.0",
   "description": "Last Light CLI — a lean global client + host-local `server` lifecycle for the Last Light GitHub maintenance agent, plus the Claude Code plugin.",
   "type": "module",
   "bin": {
@@ -33,8 +33,8 @@
     "@clack/prompts": "^1.2.0",
     "chalk": "^5.6.2",
     "cli-table3": "^0.6.5",
-    "lastlight-workflow-engine": "0.1.1",
-    "lastlight-shared": "0.1.1"
+    "lastlight-workflow-engine": "0.1.2",
+    "lastlight-shared": "0.1.2"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/plugins/lastlight/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin.json",
   "name": "lastlight",
   "displayName": "Last Light",
-  "version": "0.18.6",
+  "version": "0.20.0",
   "description": "Install, configure and operate Last Light (GitHub maintenance agent) — its server, CLI client, deployment overlay, and the Last Light Evals harness.",
   "author": {
     "name": "Clifton Cunningham"

package/plugins/lastlight/README.md

@@ -16,6 +16,7 @@ Light's *internal* sandbox skills under the repo's top-level `skills/` dir
 | `lastlight-guide` | **Not sure which of the below you need** — orientation & router across all the Last Light skills. Start here (or `/lastlight-guide`). |
 | `lastlight-server` | Install & configure a Last Light **server** (the agent + docker stack) on a host. |
 | `lastlight-client` | Point the `lastlight` **CLI client** at an existing server and log in. |
+| `lastlight-debug` | **Debug a running instance** over its admin API (no SSH): find failed/stuck workflows, tail sessions, read server/docker logs, crons, approvals, stats. |
 | `lastlight-overlay` | Create a deployment **overlay** instance and fork/customize workflows, prompts, skills, or the agent persona. |
 | `lastlight-evals` | Scaffold and run a **Last Light Evals** workspace (datasets, models, model comparisons). |
 | `lastlight-evals-loop` | **Drive an eval toward a target score** with a disciplined, anti-gaming improvement loop — diagnose on a train split, validate on a blind held-out split, propose one generic fix at a time. |

package/plugins/lastlight/skills/lastlight-client/SKILL.md

@@ -76,6 +76,9 @@ lastlight logs search "<text>"         # search errors / transcripts
 lastlight approvals list|approve|reject
 ```
 
+For a full debugging runbook (find a failed/stuck run, tail sessions, read
+server/docker logs, crons, stats) use **`lastlight-debug`**.
+
 ## Done when
 
 `lastlight status` reports the server healthy and the token valid. Report the

package/plugins/lastlight/skills/lastlight-debug/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: lastlight-debug
+description: Debug a running Last Light instance over its admin API with the `lastlight` CLI — no SSH. Use when the user wants to "look at / debug a failed or stuck workflow", "why didn't the bot do X", "check a bad agent run / phase error on <instance>", "tail a session", "search the logs", "read the server/docker logs", "list/trigger a cron", "resolve an approval", or "check stats/cost" against a deployed server. Needs a CLI already connected (see lastlight-client to log in). For standing up the server use lastlight-server; for editing config/workflows use lastlight-overlay.
+version: 1.0.0
+tags: [lastlight, debug, ops, cli, workflows, sessions, logs]
+---
+
+# Debug a Last Light instance via the CLI
+
+Read a running instance's state over its admin API with the `lastlight` CLI — no
+SSH, no poking SQLite or jsonl files on the box. Every command takes `--json`
+for machine-parseable output; prefer it when you need to extract fields.
+
+This is the operator counterpart to **`lastlight-client`** (which logs the CLI
+in). If `lastlight status` errors with no saved config, run `lastlight-client`
+first.
+
+## 1. Connect
+
+The CLI talks to whatever instance you logged into (saved in
+`~/.lastlight/config.json`). Confirm you're pointed at the right one and the
+token is valid:
+
+```bash
+lastlight status            # instance URL, server health, token validity
+```
+
+If the token is missing/expired, log in (`lastlight login https://<instance>`,
+or `--password` for headless) — that's the **`lastlight-client`** flow. For
+one-off targeting without saving, pass `--url` / `--token` on any command, or
+set `LASTLIGHT_URL` / `LASTLIGHT_TOKEN` (env wins over the saved config).
+
+## 2. Find the broken run
+
+```bash
+lastlight workflow list --status failed          # recent failures
+lastlight workflow list --status active          # running + paused now
+lastlight workflow list --workflow pr-review --limit 50
+```
+
+Copy the run `ID` from the table. The `PHASE` column names the phase the run is
+at (or failed on).
+
+## 3. Inspect the run's phases
+
+```bash
+lastlight workflow log <run-id>          # run header + per-phase table (✓/✗/…, duration, session id, error)
+lastlight workflow log <run-id> --follow # then tail the current phase live
+```
+
+The phase table shows which phase failed, its error snippet, and the `SESSION`
+id you need for the transcript. A phase stuck at `…` never finished (still
+`started`); a `✗` finished failed.
+
+If it failed on a transient/infra hiccup, re-run from the failed phase:
+
+```bash
+lastlight workflow retry <run-id>        # resumes from the phase that failed (same workspace/context)
+```
+
+## 4. Read / tail the agent transcript
+
+```bash
+lastlight session list                   # recent sandbox sessions (TYPE, MODEL, LIVE)
+lastlight session log <session-id>       # full transcript
+lastlight session log <session-id> --follow   # live tail (SSE) of an in-flight phase
+```
+
+## 5. Search across runs
+
+```bash
+lastlight logs search "ECONNREFUSED"                 # errors ledger (default)
+lastlight logs search "rate limit" --scope all       # errors + transcript content
+lastlight logs search "could not clone" --scope messages --limit 20
+```
+
+`--scope errors` (default) matches the executions ledger (error/skill/repo);
+`messages` greps recent session transcripts; `all` does both.
+
+## 6. Raw server / docker logs
+
+When the workflow + session views aren't enough — a crash before any session was
+written, a sidecar misbehaving, harness boot errors — read the actual container
+logs (`docker logs`) over the API:
+
+```bash
+lastlight server list                    # the lastlight-* containers + status
+lastlight server logs                    # the agent harness (default), last 200 lines
+lastlight server logs --tail 500 --since 10m
+lastlight server logs --follow           # live tail (Ctrl-C to stop)
+lastlight server logs coredns-strict     # a specific sidecar by service or container name
+```
+
+## 7. Crons
+
+Scheduled workflows (health scans, PR-review fanout, dependabot merge, …):
+
+```bash
+lastlight cron list                      # schedule, next/last run, status
+lastlight cron trigger <name>            # run one now (fire-and-forget; handy for repro)
+lastlight cron disable <name>            # pause a noisy/broken job (idempotent)
+lastlight cron enable  <name>            # re-enable it
+```
+
+## 8. Approvals & stats
+
+```bash
+lastlight approvals list                 # paused gates waiting on a human
+lastlight approvals approve <id> --reason "looks good"
+lastlight approvals reject  <id> --reason "wrong approach"
+
+lastlight stats                          # totals + per-skill success/fail
+lastlight stats --daily 14               # last 14 days of cost/tokens
+lastlight stats --hourly 24              # last 24 hours (spot a spike / stuck loop)
+```
+
+## Tips
+
+- Add `--json` to any command to pipe into `jq` (e.g.
+  `lastlight workflow list --status failed --json | jq -r '.workflowRuns[].id'`).
+- Per-command help is authoritative: `lastlight <cmd> help` (e.g.
+  `lastlight cron help`); the bare `lastlight --help` is a compact index.
+- Triage flow: `workflow list --status failed` → `workflow log <id>` → grab the
+  failed phase's session → `session log <session-id>` → if it's a recurring
+  symptom, `logs search "<error text>"` to see how often it happens.
+- These are read-only except `approvals approve/reject`, `cron
+  enable/disable/trigger`, `workflow retry`, and the trigger commands
+  (`build`/`triage`/`review`/…) — plain debugging never mutates the box.
+
+## Done when
+
+You've located the failing run/phase and its cause — named the phase, quoted the
+error, and pointed at the session transcript (or server log) that shows it — and,
+if asked, kicked off a `workflow retry` or resolved the approval. Report findings
+concisely; don't dump whole transcripts.

package/plugins/lastlight/skills/lastlight-guide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lastlight-guide
-description: Orientation & router for the Last Light skills. Use ONLY when the user has NOT named a concrete Last Light task — i.e. they're unsure which skill/flow they need, ask "what can Last Light do / where do I start", say "help me with Last Light" with no specific goal, or want a guided tour across server / client / overlay / evals. Do NOT use when the ask already names a task — "set up/deploy a server" → lastlight-server, "connect/log in my CLI" → lastlight-client, "customize a workflow/prompt/persona/config" → lastlight-overlay, "run evals / compare models / author a case / build a PR-review dataset" → lastlight-evals, "iteratively improve an eval toward a target score" → lastlight-evals-loop: invoke that skill directly. This skill only routes and, when the goal is ambiguous, asks. Also invocable as /lastlight-guide.
+description: Orientation & router for the Last Light skills. Use ONLY when the user has NOT named a concrete Last Light task — i.e. they're unsure which skill/flow they need, ask "what can Last Light do / where do I start", say "help me with Last Light" with no specific goal, or want a guided tour across server / client / overlay / debug / evals. Do NOT use when the ask already names a task — "set up/deploy a server" → lastlight-server, "connect/log in my CLI" → lastlight-client, "customize a workflow/prompt/persona/config" → lastlight-overlay, "debug a failed/stuck workflow or run on an instance" → lastlight-debug, "run evals / compare models / author a case / build a PR-review dataset" → lastlight-evals, "iteratively improve an eval toward a target score" → lastlight-evals-loop: invoke that skill directly. This skill only routes and, when the goal is ambiguous, asks. Also invocable as /lastlight-guide.
 version: 1.0.0
 tags: [lastlight, guide, router, orientation, help]
 ---
@@ -43,6 +43,11 @@ first time; each is also usable on its own later.
    (`agent-context`), and tune `config.yaml` — overriding only what you name,
    layered over the packaged defaults. Reach for it whenever you want to change
    *what the agent does or how it behaves* on an existing deployment.
+4. **`lastlight-debug`** — inspect a **running** instance over its admin API
+   (no SSH): find a failed/stuck workflow, read the phase table, tail a session
+   transcript, search logs, read server/docker logs, trigger/pause crons,
+   resolve approvals, check stats. Reach for it when something already deployed
+   *misbehaved* and you need to see why.
 
 ## Flow 2 — measure quality with Last Light Evals
 
@@ -77,6 +82,7 @@ time (stopping for sign-off before it touches a gold answer).
 |---|---|
 | Stand up / install / deploy a server for the first time | **`lastlight-server`** |
 | Connect my CLI to a server / log in / run commands against it | **`lastlight-client`** |
+| Debug a failed/stuck workflow, tail a session, read logs, check crons/stats | **`lastlight-debug`** |
 | Customize a workflow, prompt, skill, or the agent's persona; tune config | **`lastlight-overlay`** |
 | Run evals, compare models, browse past runs | **`lastlight-evals`** |
 | Author an eval case from a GitHub PR or issue | **`lastlight-evals`** (§6) |