packet-tracer-skill 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -4,6 +4,55 @@ All notable changes to this project should be recorded in this file.
 
 The format is intentionally simple and release-oriented.
 
+## [0.3.2] - 2026-09-12
+
+### Picking up a half-finished edit session
+
+Almost nothing here needs remembering between turns: `--doctor`,
+`--explain-plan` and `--parity-report` all recompute from the install, the
+donor registry and the bridge, so an agent that has lost its earlier context
+re-runs one and is exactly as certain as before. One question had no such
+source -- part-way through `--explain-plan` -> `--edit` -> `--parity-report`,
+*which lab am I working on and what comes next*.
+
+### Added
+
+- `output/session-log.jsonl`, one line per run, and two flags that read it
+  back: `--session-state` lists the labs in flight, `--resume <lab.pkt>` says
+  where one was left.
+- `--resume` re-hashes the lab and compares it with what the last step
+  recorded, and claims a position **only when the two agree**. When they do
+  not it says the lab has changed and to re-derive instead -- the same
+  refusal-first stance the rest of the skill takes. Verified first that a
+  digest can carry that weight: decoding a lab and re-encoding it reproduces
+  the file byte for byte.
+- Three constraints, each with a test. No secrets: facts are allow-listed
+  rather than filtered, because an edit prompt holds a passphrase in a field
+  called `passphrase` and a deny-list would leak whatever secret field is added
+  next; the prompt survives only as a non-reversible shape fingerprint. No
+  weight: a test regenerates a lab with and without the log and compares the
+  decoded content. Ships nowhere: `output/` is gitignored and in no
+  `package.json` file list, checked rather than assumed.
+
+### Fixed
+
+- `PKT_USAGE_LEDGER=on`, the obvious way to switch learning on, made the path
+  resolver treat `"on"` as a filename and write the ledger to a file called
+  `on` in the working directory. One variable carrying two meanings with only
+  one of its two readers knowing the switch words. Found by doing it.
+- `--session-state` and `--resume` were recorded as steps by the same wrapper
+  as the work they report on, so each recovery pushed itself in front of the
+  real chain. In a bounded log a reader that writes eventually evicts the steps
+  it exists to report.
+
+### Changed
+
+- `main()` is split into `_build_parser`, `_dispatch` and a wrapper that
+  records once around the whole dispatch. Fourteen branches with twelve return
+  points is not somewhere to repeat a hook.
+
+847 passed, 1 skipped. Corpus: 32 of 33 generated, 31 opened, 0 unexpected.
+
 ## [0.3.1] - 2026-09-06
 
 ### Wireless labs that actually carry traffic

package/README.md

@@ -10,7 +10,7 @@ This repository is built for one job: take a natural-language network request, b
 
 It is intended for networking labs where correctness matters more than producing a pretty but unverifiable diagram. The skill can plan, inspect, edit, compare, and explain Packet Tracer scenarios, but it deliberately separates "recognized by the parser", "visible in inventory", "edit-proven", "donor-backed ready", and "generate-ready" support.
 
-## What `0.3.1` does
+## What `0.3.2` does
 
 In this release a prompt produces a lab Packet Tracer opens.
 
@@ -229,6 +229,34 @@ Launch references:
 - [docs/security-edge-deepening-proof.md](docs/security-edge-deepening-proof.md)
 - [docs/packet-tracer-feature-gap-atlas.md](docs/packet-tracer-feature-gap-atlas.md)
 
+## Picking Up A Half-Finished Edit Session
+
+Almost nothing in this skill needs remembering between turns. `--doctor`,
+`--explain-plan` and `--parity-report` recompute from the install, the donor
+registry and the bridge, so an agent that has lost its earlier context re-runs
+one and is exactly as certain as before.
+
+One question has no such source: part-way through
+`--explain-plan` -> `--edit` -> `--parity-report`, *which lab am I working on
+and what comes next*. Each run now appends a line to
+`output/session-log.jsonl`, and two flags read it back:
+
+```powershell
+python scripts\generate_pkt.py --session-state
+python scripts\generate_pkt.py --resume output\lab.pkt
+```
+
+`--resume` re-hashes the lab and compares it with what the last step recorded.
+A position is reported **only when the two agree**; otherwise it says the lab
+has changed and to re-derive instead. That refusal is the useful answer, and it
+is the same stance the rest of the skill takes when it cannot prove something.
+
+The log carries no secrets (facts are allow-listed, and the prompt survives
+only as a non-reversible shape fingerprint), carries no weight (a test
+regenerates a lab with and without it and compares the decoded content), and
+ships nowhere (`output/` is gitignored and in no `package.json` file list).
+`PKT_SESSION_LOG=off` disables it.
+
 ## Runtime Doctor Contract
 
 `--doctor` is a product surface, not a debug afterthought. It reports:
@@ -598,7 +626,7 @@ See also:
 
 ## Release and Launch State
 
-The current line is `packet-tracer-skill@0.3.1`, and it is the first release
+The current line is `packet-tracer-skill@0.3.2`, and it is the first release
 where generation is the headline rather than a deferred promise. `0.2.3`, the
 previous published line, was a capability proof and readiness release that
 deliberately refused broad generation.
@@ -652,7 +680,7 @@ qurur, mövcud faylı redaktə edir və hər iddiasını ölçü ilə əsasland
 fayl Packet Tracer-də açılır və cihazları bir-birini ping edir; alınmayanda
 səbəbini açıq deyir.
 
-### `0.3.1` nə dəyişdi
+### `0.3.2` nə dəyişdi
 
 Bu, promptun Packet Tracer-in açdığı fayla çevrildiyi ilk buraxılışdır.
 

package/SKILL.md

@@ -175,6 +175,42 @@ There is no artificial device limit. The only ceiling is physical: a switch has
 the ports it has, and the generator says so plainly when it runs out. Ask for
 more switches, not fewer hosts.
 
+### If you lost the thread part-way through an edit chain
+
+Almost nothing here needs remembering. `--doctor`, `--explain-plan` and
+`--parity-report` all recompute from the install, the donor registry and the
+bridge, so re-running one costs time and nothing else. Losing the conversation
+does not make the skill less certain about anything it reports.
+
+One question has no such source. Part-way through
+`--explain-plan` -> `--edit` -> `--parity-report`, *which lab am I working on
+and what comes next* lived only in the conversation. So each run appends a line
+to `output/session-log.jsonl`, and two flags read it back:
+
+```bash
+python scripts/generate_pkt.py --session-state          # which labs are in flight
+python scripts/generate_pkt.py --resume output/lab.pkt  # where this one was left
+```
+
+`--resume` re-hashes the lab and compares it to what the last step recorded. It
+reports a position **only when the two agree**; when they do not, it says the
+lab has changed and tells you to re-derive instead. Treat "position not
+claimed" as the correct answer, not a failure -- it is the same refusal-first
+stance as everything else here.
+
+Three things the log deliberately is not:
+
+- **not a secret store.** Facts are allow-listed, never filtered. An edit
+  prompt carries a passphrase in an ordinary field, so nothing is written but
+  the named, known-safe keys, and the prompt survives only as the same
+  non-reversible shape fingerprint the usage ledger uses.
+- **not load-bearing.** Delete it and every result is identical; there is a
+  test that regenerates a lab with and without it and compares the content.
+- **not shipped.** It lives under `output/`, which is gitignored and in no
+  `package.json` file list.
+
+`PKT_SESSION_LOG=off` turns it off; `PKT_SESSION_LOG=<path>` moves it.
+
 ### A generated lab becomes the next build's donor
 
 Donor selection can pick a lab this skill produced, so every repair pass

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "packet-tracer-skill",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "private": false,
   "description": "Donor-backed Cisco Packet Tracer 9.x skill for natural-language planning, safe-open generation, editing, parity reporting, and runtime diagnostics across coding hosts.",
   "keywords": [

package/scripts/generate_pkt.py

@@ -341,7 +341,7 @@ def _local_donor_candidates(
 
 
 def _rank_generation_donors(
-    plan: IntentPlan,
+    plan: "IntentPlan",
     topology_tags: list[str],
     donor_roots: list[Path] | None = None,
 ) -> tuple[list[SampleCandidate], list[SampleCandidate], list[SampleCandidate]]:
@@ -405,7 +405,7 @@ def _default_import_cache_root() -> Path:
 
 
 def _resolve_remote_sources(
-    plan: IntentPlan,
+    plan: "IntentPlan",
     reference_roots: list[Path] | None,
     donor_roots: list[Path] | None,
     *,
@@ -658,7 +658,7 @@ def _candidate_archetype_alignment(
 
 
 def _build_support_reports(
-    plan: IntentPlan,
+    plan: "IntentPlan",
     *,
     blueprint: dict[str, object] | None = None,
     cisco_ranked: list[SampleCandidate] | None = None,
@@ -1486,7 +1486,7 @@ def _pool_selected_a_donor(diagnostics: list[dict[str, object]]) -> bool:
 
 
 def _evaluate_donor_prune_candidates(
-    plan: IntentPlan,
+    plan: "IntentPlan",
     blueprint: dict[str, object],
     donor_candidates: list[SampleCandidate],
 ) -> tuple[
@@ -3979,7 +3979,7 @@ def _address_hosts_per_vlan(
 
 
 def _unify_host_segment(
-    plan: IntentPlan,
+    plan: "IntentPlan",
     devices: list[dict[str, object]],
     links: list[dict[str, object]],
     donor_root=None,
@@ -10624,7 +10624,7 @@ def _build_donor_prune_plan_for_donor(plan: IntentPlan, blueprint: dict[str, obj
 
 
 def _build_donor_prune_plan(
-    plan: IntentPlan,
+    plan: "IntentPlan",
     blueprint: dict[str, object],
     donor_roots: list[Path] | None = None,
 ) -> tuple[IntentPlan, DonorArchetypePlan]:
@@ -11683,6 +11683,14 @@ def generate_from_prompt(
         donor_archetype=donor_archetype,
         outcome=usage_ledger.OUTCOME_GENERATED_UNVERIFIED,
     )
+    _record_session_generation(
+        output_path=output_path,
+        plan=raw_plan,
+        blueprint_plan=blueprint_plan,
+        scenario_decision=scenario_generate_decision,
+        donor_archetype=donor_archetype,
+        root=root,
+    )
     if blueprint_out_path is not None:
         blueprint_out_path.parent.mkdir(parents=True, exist_ok=True)
         blueprint_out_path.write_text(json.dumps(blueprint_plan, indent=2, ensure_ascii=False), encoding="utf-8")
@@ -11691,6 +11699,54 @@ def generate_from_prompt(
         print(f"Loaded reference-only samples: {len(references)}")
 
 
+def _record_session_generation(
+    *,
+    output_path: Path,
+    plan: "IntentPlan",
+    blueprint_plan: dict,
+    scenario_decision: dict,
+    donor_archetype: object,
+    root: ET.Element,
+) -> None:
+    """Note what was built, next to where the ledger notes that it worked.
+
+    Placed here because this is the one point where the answer to "what is this
+    lab" is fully known: the plan that asked for it, the donor it came from and
+    the file that was just written. Recording it anywhere earlier would be
+    recording an intention rather than an outcome.
+
+    The prompt itself is not passed on. What survives is what it parsed to --
+    counts, VLAN numbers, capability names -- which says what was being built
+    without saying who it was for, and carries none of the passphrases an edit
+    prompt can hold.
+    """
+    try:
+        from session_log import note_detailed, record
+
+        note_detailed()
+        donor = getattr(donor_archetype, "compat_donor", "")
+        record(
+            "generate",
+            artifact=output_path,
+            status="ok",
+            facts={
+                "goal": getattr(plan, "goal", ""),
+                "device_counts": dict(getattr(plan, "device_counts", {}) or {}),
+                "vlan_ids": list(getattr(plan, "vlan_ids", []) or []),
+                "capabilities": list(blueprint_plan.get("required_capabilities") or []),
+                "scenario_family": scenario_decision.get("family"),
+                "readiness_status": scenario_decision.get("readiness_status"),
+                "allow_generate": scenario_decision.get("allow_generate"),
+                "donor": Path(str(donor)).name if donor else "",
+                "device_count": len(root.findall(".//DEVICES/DEVICE")),
+                "link_count": len(root.findall(".//LINKS/LINK")),
+                "next_best_action": scenario_decision.get("what_would_make_it_pass") or "",
+            },
+        )
+    except Exception:
+        return
+
+
 def _resolve_edit_link_ports(pkt_path: Path, plan: IntentPlan) -> None:
     """Fill in real, free ports on link edits phrased without them.
 
@@ -12559,7 +12615,62 @@ def local_sample_audit(root: Path, audit_out: Path | None = None) -> None:
     print(json.dumps(payload, indent=2, ensure_ascii=False))
 
 
-def main() -> None:
+def _print_resume(artifact: Path) -> None:
+    """Say where this lab was left, and admit it when the answer cannot be trusted.
+
+    Deliberately not a claim. The log says what the last step was; the lab on
+    disk says what it is now. Only when the two agree is a position reported,
+    because a checkpoint believed without checking would be the same defect
+    this skill spends its passes hunting: one fact derived twice, with nothing
+    comparing the derivations.
+    """
+    from session_log import resume_report
+
+    report = resume_report(artifact)
+    if not report.get("known"):
+        print(f"No recorded steps for {artifact}.")
+        print("Nothing is lost: run --explain-plan to re-derive the plan, or --coherence-report to see where the lab stands.")
+        return
+
+    print(f"{artifact}")
+    print(f"  last step   : {report.get('last_command')} ({report.get('last_status')}) at {report.get('at')}")
+    print(f"  steps logged: {report.get('steps')}")
+    print(f"  {report.get('summary')}")
+    if not report.get("matches_log"):
+        print("  -> re-derive rather than resume: --explain-plan, then --coherence-report")
+    if report.get("next_best_action"):
+        print(f"  next        : {report['next_best_action']}")
+    facts = report.get("last_facts") or {}
+    for key in ("device_counts", "vlan_ids", "capabilities", "donor", "contradiction_counts"):
+        if facts.get(key):
+            print(f"  {key:12}: {facts[key]}")
+    history = report.get("history") or []
+    if len(history) > 1:
+        print("  history     :")
+        for step in history:
+            print(f"    {step.get('at')}  {step.get('command')} ({step.get('status')})")
+
+
+def _print_session_state() -> None:
+    from session_log import artifacts_seen, latest_for, log_enabled, log_path
+
+    if not log_enabled():
+        print("Session logging is off (PKT_SESSION_LOG).")
+        return
+    seen = artifacts_seen()
+    if not seen:
+        print(f"No session steps recorded yet ({log_path()}).")
+        return
+    print(f"{len(seen)} lab(s) touched, most recent first:")
+    for name in seen[:20]:
+        last = latest_for(name) or {}
+        print(f"  {name}")
+        print(f"    {last.get('command')} ({last.get('status')}) at {last.get('at')}")
+    print()
+    print("Run --resume <path> for one of them.")
+
+
+def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description="Generate or inspect Cisco Packet Tracer 9.0 .pkt files")
     parser.add_argument("--blueprint", help="Path to the topology blueprint JSON")
     parser.add_argument("--prompt", help="Natural language topology or edit request")
@@ -12598,7 +12709,19 @@ def main() -> None:
     parser.add_argument("--matrix-out", help="Optional JSON output path when using --compare-scenarios")
     parser.add_argument("--acceptance-json-out", help="Optional JSON output path for explain/compare/parity payloads")
     parser.add_argument("--device-family", help="Optional device family filter for --coverage-report")
-    args = parser.parse_args()
+    parser.add_argument(
+        "--resume",
+        help="Say where a multi-step edit session left this .pkt, and whether the file still matches what was recorded",
+    )
+    parser.add_argument(
+        "--session-state",
+        action="store_true",
+        help="List the labs a session has touched, most recently first",
+    )
+    return parser
+
+
+def _dispatch(args: argparse.Namespace) -> None:
     if args.compat_donor:
         os.environ["PACKET_TRACER_COMPAT_DONOR"] = args.compat_donor
     reference_roots = [Path(path) for path in (args.reference_root or [])]
@@ -12657,7 +12780,15 @@ def main() -> None:
             inventory_out=Path(args.inventory_out) if args.inventory_out else None,
         )
         return
+    if args.resume:
+        _print_resume(Path(args.resume))
+        return
+    if args.session_state:
+        _print_session_state()
+        return
     if args.coherence_report:
+        from collections import Counter
+
         from lab_coherence import check_lab_coherence, summarise
 
         root = decode_pkt_to_root(Path(args.coherence_report))
@@ -12665,6 +12796,23 @@ def main() -> None:
         print(summarise(findings))
         for finding in findings:
             print(f"  {finding}")
+        try:
+            from session_log import note_detailed, record
+
+            note_detailed()
+            record(
+                "coherence-report",
+                source=args.coherence_report,
+                status="ok" if not findings else "contradictions",
+                facts={
+                    "contradiction_counts": dict(Counter(getattr(f, "kind", "") for f in findings)),
+                    "next_best_action": (
+                        "" if not findings else "resolve the contradictions above, then re-run --coherence-report"
+                    ),
+                },
+            )
+        except Exception:
+            pass
         # A lab that contradicts itself opens perfectly well, so the exit code
         # is the only place the answer can be acted on.
         raise SystemExit(1 if findings else 0)
@@ -12734,5 +12882,102 @@ def main() -> None:
     generate_from_blueprint(Path(args.blueprint), Path(args.output), Path(args.xml_out) if args.xml_out else None)
 
 
+
+def main() -> None:
+    """Run the command, and leave a note saying it ran.
+
+    The note is for a later agent, not for this one. Everything this skill
+    decides is recomputed from the environment, so a lost conversation costs
+    only the time to run `--doctor` again -- except for one question, which has
+    no source but the conversation: part-way through a chain of
+    `--explain-plan` -> `--edit` -> `--parity-report`, which lab is being
+    worked on and which step is next. `--resume` answers that from the log.
+
+    Wrapped once, around the whole dispatch, rather than added to each of the
+    fourteen branches: a hook repeated fourteen times is a hook that will be
+    forgotten on the fifteenth.
+    """
+    args = _build_parser().parse_args()
+    status = "ok"
+    try:
+        _dispatch(args)
+    except SystemExit as exit_request:
+        status = "ok" if not exit_request.code else "refused"
+        raise
+    except BaseException:
+        status = "error"
+        raise
+    finally:
+        _record_session_step(args, status)
+
+
+def _record_session_step(args: argparse.Namespace, status: str) -> None:
+    """Append one line describing this invocation. Never raises."""
+    try:
+        from session_log import had_detailed, record
+        from usage_ledger import prompt_fingerprint
+
+        # Reading the log is not a step in the work. Recording it pushed two
+        # `other` entries in front of the real chain on every recovery, and in
+        # a bounded log a reader that writes eventually evicts the very steps
+        # it exists to report.
+        if getattr(args, "resume", None) or getattr(args, "session_state", False):
+            return
+        if had_detailed() and status == "ok":
+            return
+
+        command = next(
+            (
+                name
+                for name in (
+                    "explain_plan",
+                    "parity_report",
+                    "coherence_report",
+                    "compare_scenarios",
+                    "inventory",
+                    "validate_open",
+                    "validate_open_debug",
+                    "decode",
+                    "edit",
+                    "coverage_report",
+                    "feature_gap_report",
+                )
+                if getattr(args, name, None)
+            ),
+            "generate" if getattr(args, "prompt", None) else "other",
+        )
+
+        # The prompt is never written down. Its shape is: "3 switch 6 pc" and
+        # "5 switch 2 pc" share a fingerprint, which is the granularity that
+        # answers "what was I building" without recording who it was for.
+        text = ""
+        for candidate in (
+            getattr(args, "prompt", None),
+            getattr(args, "explain_plan", None),
+            getattr(args, "parity_report", None),
+        ):
+            if isinstance(candidate, str) and candidate:
+                text = candidate
+                break
+
+        facts = {}
+        if text:
+            facts["prompt_shape"] = prompt_fingerprint(text)
+
+        source = getattr(args, "edit", None) or getattr(args, "coherence_report", None)
+        if not source and isinstance(getattr(args, "validate_open", None), str):
+            source = args.validate_open
+
+        record(
+            command.replace("_", "-"),
+            artifact=getattr(args, "output", None),
+            source=source,
+            status=status,
+            facts=facts,
+        )
+    except Exception:
+        return
+
+
 if __name__ == "__main__":
     main()

package/scripts/session_log.py

@@ -0,0 +1,325 @@
+#!/usr/bin/env python3
+"""Where a multi-step edit session had got to, so a compacted agent can ask.
+
+Almost nothing in this skill lives in conversation memory: `--doctor`,
+`--parity-report` and `--explain-plan` all recompute from the environment, so
+losing an earlier turn costs nothing but the time to run them again. One thing
+is not recoverable that way. Part-way through a chain of `--explain-plan` ->
+`--edit` -> `--parity-report` calls, the question "which file am I working on,
+and which step of which plan am I on" has no source but the conversation --
+and that is exactly what compaction takes.
+
+So each invocation appends a line here, and `--resume` reads it back.
+
+The rules are the usage ledger's, for the same reasons:
+
+- local only. Written under `output/`, which is gitignored and appears in no
+  `package.json` file list, so it reaches neither a repository nor a registry.
+- **nothing is load-bearing.** Deleting this file must change no result
+  anywhere. It answers a question; it never feeds a decision.
+- bounded, and a corrupt or unreadable log is ignored rather than fatal.
+- `PKT_SESSION_LOG=off` disables it entirely.
+
+And one rule of its own. Facts are recorded by **allow-list**, never by copying
+a payload and stripping what looks sensitive. An edit prompt carries secrets in
+ordinary fields -- `passphrase` on `set_wireless_ssid`, `password` on three
+more operations, `community` on `set_bgp_neighbor` -- so a deny-list would leak
+the first secret field anyone adds after this was written. Operation *names and
+counts* are recorded; operation *values* never are, and neither is the prompt,
+which is kept as the same non-reversible shape fingerprint the ledger uses.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_LOG_PATH = SKILL_ROOT / "output" / "session-log.jsonl"
+MAX_ENTRIES = 500
+LOG_VERSION = 1
+
+# Every fact that may be written. A key absent from here is dropped whatever it
+# holds -- see the module docstring for why this is an allow-list.
+ALLOWED_FACTS = frozenset(
+    {
+        "goal",
+        "prompt_shape",
+        "device_counts",
+        "vlan_ids",
+        "capabilities",
+        "scenario_family",
+        "readiness_status",
+        "allow_generate",
+        "donor",
+        "target_version",
+        "operation_counts",
+        "next_best_action",
+        "parity_counts",
+        "contradiction_counts",
+        "device_count",
+        "link_count",
+        "opened",
+        "detail",
+    }
+)
+
+# Values are summarised, never copied wholesale, so a long list cannot become a
+# long line and a stray string cannot smuggle a secret through a counter.
+_MAX_STRING = 200
+_MAX_ITEMS = 40
+
+_OFF_WORDS = {"off", "0", "false", "none"}
+_ON_WORDS = {"on", "1", "true"}
+
+
+def log_path() -> Path:
+    override = (os.getenv("PKT_SESSION_LOG") or "").strip()
+    if override and override.lower() not in (_OFF_WORDS | _ON_WORDS):
+        return Path(override).expanduser()
+    return DEFAULT_LOG_PATH
+
+
+def log_enabled() -> bool:
+    return (os.getenv("PKT_SESSION_LOG") or "").strip().lower() not in _OFF_WORDS
+
+
+# Set when a branch has already written a fuller entry for this process, so the
+# wrapper around the dispatch does not add a thinner duplicate beside it. The
+# wrapper still fires for every command that writes nothing of its own, which
+# is the point of wrapping rather than hooking each branch.
+_DETAILED = False
+
+
+def note_detailed() -> None:
+    global _DETAILED
+    _DETAILED = True
+
+
+def had_detailed() -> bool:
+    return _DETAILED
+
+
+def _clean(value: Any) -> Any:
+    """Reduce a value to something small, printable and free of running text."""
+    if value is None or isinstance(value, bool) or isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return round(value, 3)
+    if isinstance(value, str):
+        return value[:_MAX_STRING]
+    if isinstance(value, dict):
+        return {str(key)[:_MAX_STRING]: _clean(item) for key, item in list(value.items())[:_MAX_ITEMS]}
+    if isinstance(value, (list, tuple, set)):
+        return [_clean(item) for item in list(value)[:_MAX_ITEMS]]
+    return str(value)[:_MAX_STRING]
+
+
+def normalise(path: Path | str | None) -> str:
+    """One spelling per file, so one lab is not mistaken for two.
+
+    The same lab arrived down two routes and was listed twice: the generation
+    branch passes a `Path`, which prints with backslashes on Windows, while the
+    flag branches pass the string the shell gave, which had forward slashes.
+    Resolving both collapses separators and relative prefixes together.
+    """
+    if not path:
+        return ""
+    try:
+        return str(Path(path).resolve())
+    except (OSError, ValueError):
+        return str(path)
+
+
+def artifact_digest(path: Path | str | None) -> str:
+    """A `.pkt` identifies itself by its bytes.
+
+    Measured before relying on it: decoding a lab and re-encoding it reproduces
+    the file byte for byte, so identical content always hashes identically and
+    a changed digest means the lab really changed. That is what lets `--resume`
+    check its own answer instead of asserting it.
+    """
+    if not path:
+        return ""
+    candidate = Path(path)
+    try:
+        if not candidate.is_file():
+            return ""
+        return hashlib.sha256(candidate.read_bytes()).hexdigest()
+    except OSError:
+        return ""
+
+
+def record(
+    command: str,
+    *,
+    artifact: Path | str | None = None,
+    source: Path | str | None = None,
+    status: str = "ok",
+    facts: dict[str, Any] | None = None,
+) -> None:
+    """Append one step. Never raises: a broken log must not break a build."""
+    if not log_enabled():
+        return
+    try:
+        entry: dict[str, Any] = {
+            "v": LOG_VERSION,
+            "at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+            "command": str(command)[:_MAX_STRING],
+            "status": str(status)[:_MAX_STRING],
+        }
+        if artifact:
+            entry["artifact"] = normalise(artifact)[:_MAX_STRING]
+            entry["artifact_sha256"] = artifact_digest(artifact)
+        if source:
+            entry["source"] = normalise(source)[:_MAX_STRING]
+            entry["source_sha256"] = artifact_digest(source)
+        kept = {key: _clean(value) for key, value in (facts or {}).items() if key in ALLOWED_FACTS}
+        if kept:
+            entry["facts"] = kept
+
+        path = log_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        # One write of one line, so concurrent runs interleave whole lines and
+        # never characters: two agents working at once cannot corrupt a log
+        # neither of them is allowed to depend on anyway.
+        with path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(entry, ensure_ascii=False) + "\n")
+        _trim(path)
+    except Exception:
+        return
+
+
+def _trim(path: Path) -> None:
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+        if len(lines) <= MAX_ENTRIES:
+            return
+        path.write_text("\n".join(lines[-MAX_ENTRIES:]) + "\n", encoding="utf-8")
+    except Exception:
+        return
+
+
+def read_entries(path: Path | None = None) -> list[dict[str, Any]]:
+    """Every readable entry, oldest first. An unreadable line is skipped."""
+    target = path or log_path()
+    try:
+        if not target.is_file():
+            return []
+        text = target.read_text(encoding="utf-8")
+    except OSError:
+        return []
+    entries: list[dict[str, Any]] = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            parsed = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict):
+            entries.append(parsed)
+    return entries
+
+
+def _names_match(entry: dict[str, Any], wanted: Path) -> bool:
+    target = normalise(wanted)
+    for key in ("artifact", "source"):
+        recorded = entry.get(key)
+        if not recorded:
+            continue
+        recorded = str(recorded)
+        if normalise(recorded) == target or Path(recorded).name == wanted.name:
+            return True
+    return False
+
+
+def history_for(artifact: Path | str, path: Path | None = None) -> list[dict[str, Any]]:
+    """The steps touching one lab, oldest first."""
+    wanted = Path(artifact)
+    return [entry for entry in read_entries(path) if _names_match(entry, wanted)]
+
+
+def latest_for(artifact: Path | str, path: Path | None = None) -> dict[str, Any] | None:
+    steps = history_for(artifact, path)
+    return steps[-1] if steps else None
+
+
+def artifacts_seen(path: Path | None = None) -> list[str]:
+    """Every lab the log mentions, most recently touched first."""
+    order: list[str] = []
+    for entry in read_entries(path):
+        for key in ("artifact", "source"):
+            name = entry.get(key)
+            if not name:
+                continue
+            name = str(name)
+            if name in order:
+                order.remove(name)
+            order.append(name)
+    return list(reversed(order))
+
+
+def resume_report(artifact: Path | str, path: Path | None = None) -> dict[str, Any]:
+    """Where this lab was left, and whether the log still describes it.
+
+    The check is the point. A log that simply asserted a position would be the
+    defect this repository keeps finding: a fact derived in one place and
+    believed in another, with nothing comparing them. So the lab is re-hashed
+    and a position is claimed only when the two agree. Otherwise the mismatch
+    is the answer -- which is the same refusal-first stance the rest of the
+    skill takes when it cannot prove something.
+    """
+    wanted = Path(artifact)
+    steps = history_for(wanted, path)
+    if not steps:
+        return {
+            "artifact": str(wanted),
+            "known": False,
+            "matches_log": False,
+            "steps": 0,
+            "summary": "no recorded steps for this lab",
+        }
+
+    last = steps[-1]
+    recorded = str(last.get("artifact_sha256") or last.get("source_sha256") or "")
+    on_disk = artifact_digest(wanted)
+    exists = wanted.is_file()
+    matches = bool(on_disk) and bool(recorded) and on_disk == recorded
+
+    if not exists:
+        summary = "the lab the log describes is not on disk any more"
+    elif not recorded:
+        summary = "the last step recorded no digest, so the position cannot be confirmed"
+    elif matches:
+        summary = f"last step was `{last.get('command')}` and the lab still matches it"
+    else:
+        summary = "the lab has changed since the last recorded step; position not claimed"
+
+    report: dict[str, Any] = {
+        "artifact": str(wanted),
+        "known": True,
+        "exists": exists,
+        "matches_log": matches,
+        "steps": len(steps),
+        "last_command": last.get("command"),
+        "last_status": last.get("status"),
+        "at": last.get("at"),
+        "summary": summary,
+        "history": [
+            {"at": step.get("at"), "command": step.get("command"), "status": step.get("status")}
+            for step in steps[-10:]
+        ],
+    }
+    facts = last.get("facts") or {}
+    if isinstance(facts, dict):
+        if facts.get("next_best_action"):
+            report["next_best_action"] = facts["next_best_action"]
+        if facts:
+            report["last_facts"] = facts
+    return report

package/scripts/usage_ledger.py

@@ -1,218 +1,230 @@
-#!/usr/bin/env python3
-"""A local, append-only record of what actually worked, so the skill improves with use.
-
-Donor selection is expensive and mostly repetitive: the same scenario families
-come back, and the same handful of donors keep winning or keep failing for the
-same reasons. Rediscovering that on every run wastes several seconds per
-candidate and, worse, throws away the only real evidence the skill ever gets
-about which donors survive a Packet Tracer open.
-
-The ledger records the outcome of each generation and feeds it back into donor
-ranking on the next run. Nothing is inferred or guessed: an entry is written
-only after a real attempt produced a real result.
-
-Privacy and safety rules, deliberately strict:
-
-- the ledger is local only. It is written under `output/`, which is gitignored,
-  and it is never committed, packaged, or transmitted anywhere.
-- prompts are stored as a normalised fingerprint, not verbatim text, so a lab
-  description containing names or addresses does not end up on disk.
-- the file is bounded. Old entries are dropped once the cap is reached.
-- a corrupt or unreadable ledger is ignored, never fatal. Learning is an
-  optimisation; the skill must work identically with the ledger deleted.
-"""
-
-from __future__ import annotations
-
-import hashlib
-import json
-import os
-import re
-from collections import defaultdict
-from dataclasses import dataclass, field
-from datetime import datetime, timezone
-from pathlib import Path
-
-SKILL_ROOT = Path(__file__).resolve().parents[1]
-DEFAULT_LEDGER_PATH = SKILL_ROOT / "output" / "usage-ledger.jsonl"
-MAX_ENTRIES = 2000
-LEDGER_VERSION = 1
-
-OUTCOME_GENERATED_VERIFIED = "generated_verified"
-OUTCOME_GENERATED_UNVERIFIED = "generated_unverified"
-OUTCOME_REFUSED = "refused"
-OUTCOMES = (OUTCOME_GENERATED_VERIFIED, OUTCOME_GENERATED_UNVERIFIED, OUTCOME_REFUSED)
-
-# Outcomes that count as evidence a donor works, best first.
-_SUCCESS_WEIGHT = {
-    OUTCOME_GENERATED_VERIFIED: 3,
-    OUTCOME_GENERATED_UNVERIFIED: 1,
-}
-
-
-def ledger_path() -> Path:
-    override = os.getenv("PKT_USAGE_LEDGER")
-    return Path(override).expanduser() if override else DEFAULT_LEDGER_PATH
-
-
-def ledger_enabled() -> bool:
-    """Learning is on by default; `PKT_USAGE_LEDGER=off` disables it entirely."""
-    return (os.getenv("PKT_USAGE_LEDGER") or "").strip().lower() not in {"off", "0", "false", "none"}
-
-
-def prompt_fingerprint(prompt: str) -> str:
-    """A stable, non-reversible fingerprint of a prompt's *shape*.
-
-    Digits are collapsed to `#` and case and spacing are normalised, so
-    "3 switch 6 pc" and "5 switch 2 pc" share a fingerprint: they are the same
-    kind of request, which is exactly the granularity donor reuse needs. The
-    result is hashed so no prompt text is ever written to disk.
-    """
-    normalised = re.sub(r"\d+", "#", (prompt or "").strip().lower())
-    normalised = re.sub(r"[^\w#]+", " ", normalised).strip()
-    return hashlib.sha256(normalised.encode("utf-8")).hexdigest()[:16]
-
-
-@dataclass
-class LedgerEntry:
-    scenario_family: str
-    donor: str
-    outcome: str
-    prompt_shape: str = ""
-    target_version: str = ""
-    donor_version: str = ""
-    rejected_donors: list[str] = field(default_factory=list)
-    rejection_codes: list[str] = field(default_factory=list)
-    recorded_at: str = ""
-
-    def to_json(self) -> dict[str, object]:
-        return {
-            "v": LEDGER_VERSION,
-            "recorded_at": self.recorded_at or datetime.now(timezone.utc).isoformat(timespec="seconds"),
-            "scenario_family": self.scenario_family,
-            "prompt_shape": self.prompt_shape,
-            "donor": self.donor,
-            "donor_version": self.donor_version,
-            "target_version": self.target_version,
-            "outcome": self.outcome,
-            "rejected_donors": self.rejected_donors[:20],
-            "rejection_codes": self.rejection_codes[:20],
-        }
-
-
-def record(entry: LedgerEntry, path: Path | None = None) -> bool:
-    """Append one outcome. Returns False if the ledger is off or unwritable."""
-    if not ledger_enabled():
-        return False
-    if entry.outcome not in OUTCOMES:
-        raise ValueError(f"unknown outcome: {entry.outcome}")
-
-    target = path or ledger_path()
-    try:
-        target.parent.mkdir(parents=True, exist_ok=True)
-        with target.open("a", encoding="utf-8") as handle:
-            handle.write(json.dumps(entry.to_json(), ensure_ascii=False) + "\n")
-    except OSError:
-        return False
-
-    _trim(target)
-    return True
-
-
-def _trim(path: Path) -> None:
-    try:
-        lines = path.read_text(encoding="utf-8").splitlines()
-    except OSError:
-        return
-    if len(lines) <= MAX_ENTRIES:
-        return
-    try:
-        path.write_text("\n".join(lines[-MAX_ENTRIES:]) + "\n", encoding="utf-8")
-    except OSError:
-        return
-
-
-def load_entries(path: Path | None = None) -> list[dict[str, object]]:
-    """Read the ledger. A damaged file yields whatever lines still parse."""
-    target = path or ledger_path()
-    if not ledger_enabled() or not target.exists():
-        return []
-    entries: list[dict[str, object]] = []
-    try:
-        raw_lines = target.read_text(encoding="utf-8").splitlines()
-    except OSError:
-        return []
-    for line in raw_lines:
-        line = line.strip()
-        if not line:
-            continue
-        try:
-            parsed = json.loads(line)
-        except json.JSONDecodeError:
-            continue
-        if isinstance(parsed, dict) and parsed.get("donor"):
-            entries.append(parsed)
-    return entries
-
-
-def donor_scores(
-    scenario_family: str,
-    prompt_shape: str = "",
-    path: Path | None = None,
-) -> dict[str, int]:
-    """Learned preference per donor, as `relative_path -> score`.
-
-    Positive means the donor has produced output for this kind of request
-    before; negative means it has been rejected. An exact prompt-shape match
-    counts double, because it is stronger evidence than family alone.
-    """
-    scores: dict[str, int] = defaultdict(int)
-    for entry in load_entries(path):
-        if str(entry.get("scenario_family") or "") != scenario_family:
-            continue
-        multiplier = 2 if prompt_shape and entry.get("prompt_shape") == prompt_shape else 1
-
-        donor = str(entry.get("donor") or "")
-        weight = _SUCCESS_WEIGHT.get(str(entry.get("outcome") or ""), 0)
-        if donor and weight:
-            scores[donor] += weight * multiplier
-
-        for rejected in entry.get("rejected_donors") or []:
-            name = str(rejected)
-            if name:
-                scores[name] -= multiplier
-    return dict(scores)
-
-
-def summary(path: Path | None = None) -> dict[str, object]:
-    """Human-facing view of what the skill has learned so far."""
-    entries = load_entries(path)
-    by_outcome: dict[str, int] = defaultdict(int)
-    by_family: dict[str, int] = defaultdict(int)
-    proven: dict[str, int] = defaultdict(int)
-    for entry in entries:
-        outcome = str(entry.get("outcome") or "")
-        by_outcome[outcome] += 1
-        by_family[str(entry.get("scenario_family") or "unknown")] += 1
-        if outcome in _SUCCESS_WEIGHT:
-            proven[str(entry.get("donor") or "")] += _SUCCESS_WEIGHT[outcome]
-    return {
-        "ledger_path": str(path or ledger_path()),
-        "enabled": ledger_enabled(),
-        "entry_count": len(entries),
-        "outcomes": dict(by_outcome),
-        "scenario_families": dict(by_family),
-        "proven_donors": sorted(
-            ({"donor": donor, "score": score} for donor, score in proven.items() if score > 0),
-            key=lambda item: (-int(item["score"]), str(item["donor"])),
-        )[:10],
-    }
-
-
-def main() -> int:
-    print(json.dumps(summary(), ensure_ascii=False, indent=2))
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
+#!/usr/bin/env python3
+"""A local, append-only record of what actually worked, so the skill improves with use.
+
+Donor selection is expensive and mostly repetitive: the same scenario families
+come back, and the same handful of donors keep winning or keep failing for the
+same reasons. Rediscovering that on every run wastes several seconds per
+candidate and, worse, throws away the only real evidence the skill ever gets
+about which donors survive a Packet Tracer open.
+
+The ledger records the outcome of each generation and feeds it back into donor
+ranking on the next run. Nothing is inferred or guessed: an entry is written
+only after a real attempt produced a real result.
+
+Privacy and safety rules, deliberately strict:
+
+- the ledger is local only. It is written under `output/`, which is gitignored,
+  and it is never committed, packaged, or transmitted anywhere.
+- prompts are stored as a normalised fingerprint, not verbatim text, so a lab
+  description containing names or addresses does not end up on disk.
+- the file is bounded. Old entries are dropped once the cap is reached.
+- a corrupt or unreadable ledger is ignored, never fatal. Learning is an
+  optimisation; the skill must work identically with the ledger deleted.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_LEDGER_PATH = SKILL_ROOT / "output" / "usage-ledger.jsonl"
+MAX_ENTRIES = 2000
+LEDGER_VERSION = 1
+
+OUTCOME_GENERATED_VERIFIED = "generated_verified"
+OUTCOME_GENERATED_UNVERIFIED = "generated_unverified"
+OUTCOME_REFUSED = "refused"
+OUTCOMES = (OUTCOME_GENERATED_VERIFIED, OUTCOME_GENERATED_UNVERIFIED, OUTCOME_REFUSED)
+
+# Outcomes that count as evidence a donor works, best first.
+_SUCCESS_WEIGHT = {
+    OUTCOME_GENERATED_VERIFIED: 3,
+    OUTCOME_GENERATED_UNVERIFIED: 1,
+}
+
+
+# One variable carries two meanings -- a switch and a path -- and only one of
+# them was reading the switch words. `PKT_USAGE_LEDGER=on`, the obvious way to
+# turn learning on, made `ledger_path` treat "on" as a filename and write the
+# ledger to a file called `on` in the working directory. Found by doing exactly
+# that while testing something else, which left an untracked `on` in the
+# repository root. Both readers share the vocabulary now.
+_OFF_WORDS = {"off", "0", "false", "none"}
+_ON_WORDS = {"on", "1", "true"}
+
+
+def ledger_path() -> Path:
+    override = (os.getenv("PKT_USAGE_LEDGER") or "").strip()
+    if override and override.lower() not in (_OFF_WORDS | _ON_WORDS):
+        return Path(override).expanduser()
+    return DEFAULT_LEDGER_PATH
+
+
+def ledger_enabled() -> bool:
+    """Learning is on by default; `PKT_USAGE_LEDGER=off` disables it entirely."""
+    return (os.getenv("PKT_USAGE_LEDGER") or "").strip().lower() not in _OFF_WORDS
+
+
+def prompt_fingerprint(prompt: str) -> str:
+    """A stable, non-reversible fingerprint of a prompt's *shape*.
+
+    Digits are collapsed to `#` and case and spacing are normalised, so
+    "3 switch 6 pc" and "5 switch 2 pc" share a fingerprint: they are the same
+    kind of request, which is exactly the granularity donor reuse needs. The
+    result is hashed so no prompt text is ever written to disk.
+    """
+    normalised = re.sub(r"\d+", "#", (prompt or "").strip().lower())
+    normalised = re.sub(r"[^\w#]+", " ", normalised).strip()
+    return hashlib.sha256(normalised.encode("utf-8")).hexdigest()[:16]
+
+
+@dataclass
+class LedgerEntry:
+    scenario_family: str
+    donor: str
+    outcome: str
+    prompt_shape: str = ""
+    target_version: str = ""
+    donor_version: str = ""
+    rejected_donors: list[str] = field(default_factory=list)
+    rejection_codes: list[str] = field(default_factory=list)
+    recorded_at: str = ""
+
+    def to_json(self) -> dict[str, object]:
+        return {
+            "v": LEDGER_VERSION,
+            "recorded_at": self.recorded_at or datetime.now(timezone.utc).isoformat(timespec="seconds"),
+            "scenario_family": self.scenario_family,
+            "prompt_shape": self.prompt_shape,
+            "donor": self.donor,
+            "donor_version": self.donor_version,
+            "target_version": self.target_version,
+            "outcome": self.outcome,
+            "rejected_donors": self.rejected_donors[:20],
+            "rejection_codes": self.rejection_codes[:20],
+        }
+
+
+def record(entry: LedgerEntry, path: Path | None = None) -> bool:
+    """Append one outcome. Returns False if the ledger is off or unwritable."""
+    if not ledger_enabled():
+        return False
+    if entry.outcome not in OUTCOMES:
+        raise ValueError(f"unknown outcome: {entry.outcome}")
+
+    target = path or ledger_path()
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with target.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(entry.to_json(), ensure_ascii=False) + "\n")
+    except OSError:
+        return False
+
+    _trim(target)
+    return True
+
+
+def _trim(path: Path) -> None:
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return
+    if len(lines) <= MAX_ENTRIES:
+        return
+    try:
+        path.write_text("\n".join(lines[-MAX_ENTRIES:]) + "\n", encoding="utf-8")
+    except OSError:
+        return
+
+
+def load_entries(path: Path | None = None) -> list[dict[str, object]]:
+    """Read the ledger. A damaged file yields whatever lines still parse."""
+    target = path or ledger_path()
+    if not ledger_enabled() or not target.exists():
+        return []
+    entries: list[dict[str, object]] = []
+    try:
+        raw_lines = target.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return []
+    for line in raw_lines:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            parsed = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict) and parsed.get("donor"):
+            entries.append(parsed)
+    return entries
+
+
+def donor_scores(
+    scenario_family: str,
+    prompt_shape: str = "",
+    path: Path | None = None,
+) -> dict[str, int]:
+    """Learned preference per donor, as `relative_path -> score`.
+
+    Positive means the donor has produced output for this kind of request
+    before; negative means it has been rejected. An exact prompt-shape match
+    counts double, because it is stronger evidence than family alone.
+    """
+    scores: dict[str, int] = defaultdict(int)
+    for entry in load_entries(path):
+        if str(entry.get("scenario_family") or "") != scenario_family:
+            continue
+        multiplier = 2 if prompt_shape and entry.get("prompt_shape") == prompt_shape else 1
+
+        donor = str(entry.get("donor") or "")
+        weight = _SUCCESS_WEIGHT.get(str(entry.get("outcome") or ""), 0)
+        if donor and weight:
+            scores[donor] += weight * multiplier
+
+        for rejected in entry.get("rejected_donors") or []:
+            name = str(rejected)
+            if name:
+                scores[name] -= multiplier
+    return dict(scores)
+
+
+def summary(path: Path | None = None) -> dict[str, object]:
+    """Human-facing view of what the skill has learned so far."""
+    entries = load_entries(path)
+    by_outcome: dict[str, int] = defaultdict(int)
+    by_family: dict[str, int] = defaultdict(int)
+    proven: dict[str, int] = defaultdict(int)
+    for entry in entries:
+        outcome = str(entry.get("outcome") or "")
+        by_outcome[outcome] += 1
+        by_family[str(entry.get("scenario_family") or "unknown")] += 1
+        if outcome in _SUCCESS_WEIGHT:
+            proven[str(entry.get("donor") or "")] += _SUCCESS_WEIGHT[outcome]
+    return {
+        "ledger_path": str(path or ledger_path()),
+        "enabled": ledger_enabled(),
+        "entry_count": len(entries),
+        "outcomes": dict(by_outcome),
+        "scenario_families": dict(by_family),
+        "proven_donors": sorted(
+            ({"donor": donor, "score": score} for donor, score in proven.items() if score > 0),
+            key=lambda item: (-int(item["score"]), str(item["donor"])),
+        )[:10],
+    }
+
+
+def main() -> int:
+    print(json.dumps(summary(), ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())