pdl-taskmaster 2.4.0__py3-none-any.whl

pdl_taskmaster/tracking/log_live_session.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import sys
+
+
+ROOT = Path(__file__).resolve().parents[3]
+if str(ROOT / "src") not in sys.path:
+    sys.path.insert(0, str(ROOT / "src"))
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+import mlflow
+from pdl_taskmaster.tracking.mlflow_sink import log_experiment_run
+
+
+def _default_tracking_db() -> Path:
+    """Resolve the MLflow SQLite tracking store.
+
+    MLflow telemetry is post-hoc and non-authoritative; the store lives in the
+    external archive by default (repo-restructure-plan §3.1):
+    1. PDLT_MLFLOW_DB environment variable (explicit db path override).
+    2. Sibling archive: <parent>/PDL-Standard-Archive/mlflow/mlflow.db.
+    3. Legacy repo-root mlflow.db fallback (isolated test trees, archive absent).
+    """
+    env = os.environ.get("PDLT_MLFLOW_DB", "").strip()
+    if env:
+        return Path(env)
+    archive = ROOT.parent / "PDL-Standard-Archive" / "mlflow" / "mlflow.db"
+    if (ROOT.parent / "PDL-Standard-Archive").is_dir():
+        return archive
+    return ROOT / "mlflow.db"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Log one live PDLt session to MLflow")
+    parser.add_argument("--session-dir", type=Path, required=True)
+    parser.add_argument("--run-name", default=None)
+    parser.add_argument("--worker-profile", default="api", help="worker identity to record (api|codex|recorded)")
+    args = parser.parse_args()
+
+    session_dir = args.session_dir.resolve()
+    session_json = session_dir / "session.json"
+    if not session_json.is_file():
+        raise SystemExit(f"session.json missing: {session_json}")
+    session_data = json.loads(session_json.read_text(encoding="utf-8"))
+    session_id = session_dir.name
+
+    observation_files = sorted((session_dir / "observations").glob("*.jsonl")) if (session_dir / "observations").is_dir() else []
+    observation_records = 0
+    final_stage = None
+    total_tokens = 0
+    for obs in observation_files:
+        rows = [json.loads(line) for line in obs.read_text(encoding="utf-8").splitlines() if line.strip()]
+        observation_records += len(rows)
+        if rows:
+            final_stage = ((rows[-1].get("controller_after") or {}).get("controller_state") or {}).get("stage")
+        for row in rows:
+            for call in row.get("calls", []):
+                usage = call.get("usage") or {}
+                total_tokens += int(usage.get("total_tokens") or 0)
+
+    transcript = session_dir / "transcript.log"
+    artifacts = [str(session_json)]
+    if transcript.is_file():
+        artifacts.append(str(transcript))
+    artifacts.extend(str(path) for path in observation_files)
+    worker_progress = session_dir / "worker-progress.log"
+    if worker_progress.is_file():
+        artifacts.append(str(worker_progress))
+
+    mlflow.set_tracking_uri(f"sqlite:///{_default_tracking_db().as_posix()}")
+    mlflow.set_experiment("PDL-R2S")
+    run_id = log_experiment_run(
+        args.run_name or f"live-session-{session_id}",
+        params={
+            "run_type": "live_session",
+            "session_id": session_id,
+            "candidate_repository": "PDL-Standard-R2S",
+            "candidate_commit": "6df3bf5733cd3fcd16b1560ff7a80810c96bbe6c",
+            "worker_profile": args.worker_profile,
+            "observation_jsonl_path": ",".join(str(path) for path in observation_files),
+            "transcript_path": str(transcript) if transcript.is_file() else "none",
+            "workspace_path": str(session_data.get("workspace_path", "none")),
+            "final_stage": final_stage or "unknown",
+        },
+        metrics={"observation_records": float(observation_records), "total_tokens": float(total_tokens)},
+        artifacts=artifacts,
+    )
+    print(f"LIVE_SESSION_MLFLOW_RUN {run_id} session={session_id} records={observation_records}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pdl_taskmaster/tracking/mlflow_sink.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import mlflow
+
+
+class MlflowRunLogger:
+    """Tracking-only run logger.
+
+    This logger lives outside the observed semantic path. It indexes evidence
+    after the fact.
+    """
+
+    def __init__(self, run_name: str, params: dict[str, Any] | None = None):
+        self._mlflow = mlflow
+        self._run = mlflow.start_run(run_name=run_name)
+        if params:
+            mlflow.log_params(params)
+
+    @property
+    def run_id(self) -> str:
+        return self._run.info.run_id
+
+    def log_params(self, params: dict[str, Any]) -> None:
+        self._mlflow.log_params(params)
+
+    def log_metrics(self, metrics: dict[str, float]) -> None:
+        self._mlflow.log_metrics(metrics)
+
+    def log_artifact(self, path: str | Path) -> None:
+        self._mlflow.log_artifact(str(path))
+
+    def finish(self) -> None:
+        self._mlflow.end_run()
+
+
+def log_experiment_run(
+    run_name: str,
+    *,
+    params: dict[str, Any],
+    metrics: dict[str, float],
+    artifacts: list[str | Path],
+) -> str:
+    """Log one tracking-only run.
+
+    This function is never called from the observed semantic path.
+    """
+    with mlflow.start_run(run_name=run_name) as run:
+        mlflow.log_params(params)
+        mlflow.log_metrics(metrics)
+        for artifact in artifacts:
+            path = Path(artifact)
+            if not path.is_file():
+                raise FileNotFoundError(f"required evidence pointer missing: {path}")
+            mlflow.log_artifact(str(path))
+        return run.info.run_id

pdl_taskmaster/verify/verify_repl_baseline.py

@@ -0,0 +1,299 @@
+from __future__ import annotations
+
+"""One deterministic verification entry point for the standalone REPL harness.
+
+Checks: required runtime/instructional files, import integrity, fixture
+integrity, external-source-repo leakage, fresh-workspace lifecycle, result
+delivery, and resume. All workspaces are created in temporary directories.
+"""
+
+import json
+import os
+import re
+import sys
+import tempfile
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[3]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+
+_SRC = "PDL-Standard-R2S"
+SOURCE_REPO_MARKERS = (
+    "Desktop" + "\\Frameworks\\" + _SRC,
+    "Desktop" + "\\Frameworks\\" + _SRC + "-Lab",
+    "Desktop" + "/Frameworks/" + _SRC,
+    "Desktop" + "/Frameworks/" + _SRC + "-Lab",
+)
+FORBIDDEN_TERMS = (
+    "phase6ev",
+    "cohort",
+    "recruitment",
+    "guardian",
+    "recurrence",
+    "OPEN_AUTHORIZATION",
+    "current-phase-docs",
+    "architecture-decisions",
+)
+SECRET_PATTERNS = (
+    re.compile(r"\bsk-[A-Za-z0-9]{16,}\b"),
+    re.compile(r"\b(?:api[_-]?key|openai_api_key|openrouter_api_key)\s*[:=]\s*['\"][^'\"]{8,}['\"]", re.I),
+)
+
+REQUIRED_FILES = (
+    "src/pdl_taskmaster/controller/mechanical_controller.py",
+    "src/pdl_taskmaster/runtime/session_engine.py",
+    "src/pdl_taskmaster/runtime/workspace.py",
+    "src/pdl_taskmaster/runtime/normative_store.py",
+    "src/pdl_taskmaster/runtime/operation_bridge.py",
+    "src/pdl_taskmaster/runtime/context_compiler.py",
+    "src/pdl_taskmaster/runtime/standard_registry.py",
+    "src/pdl_taskmaster/runtime/presentation.py",
+    "src/pdl_taskmaster/runtime/semantic_observer.py",
+    "contracts/CONTRACT_MANIFEST.json",
+    "contracts/EXECUTION_CONTRACT.json",
+    "confirm-with-pseudocode/SKILL.md",
+    "src/pdl_taskmaster/host/repl.py",
+    "src/pdl_taskmaster/host/app.py",
+    "src/pdl_taskmaster/observation/session.py",
+    "src/pdl_taskmaster/observation/records.py",
+    "src/pdl_taskmaster/observation/sinks.py",
+    "src/pdl_taskmaster/providers/base.py",
+    "src/pdl_taskmaster/providers/recorded.py",
+    "src/pdl_taskmaster/providers/fixtures.py",
+    "src/pdl_taskmaster/providers/codex_worker.py",
+    "src/pdl_taskmaster/providers/live_stub.py",
+    "src/pdl_taskmaster/tracking/mlflow_sink.py",
+    "src/pdl_taskmaster/tracking/log_live_session.py",
+    "src/pdl_taskmaster/eval/run_qualified_batch.py",
+    "src/pdl_taskmaster/eval/leak_scan.py",
+    "src/pdl_taskmaster/eval/fidelity_scan.py",
+    "README.md",
+    "SOURCE_PROVENANCE.json",
+)
+
+
+def _fixture_dir() -> Path:
+    """Resolve the recorded fixture directory.
+
+    Precedence (mirrors the Brain/Hands pattern of S1's NormativeStore):
+    1. PDLT_FIXTURES_PATH environment variable (points at the r4-recorded-worker dir).
+    2. tests/fixtures vendored location (self-contained offline suite).
+    3. Repository-relative vendored location (compat with pre-restructure checkouts).
+    4. Sibling PDL-Standard-Archive external fixtures.
+    """
+    env = os.environ.get("PDLT_FIXTURES_PATH", "").strip()
+    if env:
+        return Path(env)
+    vendored = ROOT / "tests" / "fixtures"
+    if vendored.is_dir() and (vendored / "recorded-cases.json").is_file():
+        return vendored
+    local = ROOT / "fixtures" / "r4-recorded-worker"
+    if local.is_dir():
+        return local
+    archive = ROOT.parent / "PDL-Standard-Archive" / "fixtures-r4-recorded-worker"
+    if archive.is_dir():
+        return archive
+    return vendored
+
+
+
+def _failures() -> list[str]:
+    problems: list[str] = []
+
+    # 1. Required runtime/instructional files.
+    for relative in REQUIRED_FILES:
+        if not (ROOT / relative).is_file():
+            problems.append(f"missing_required_file:{relative}")
+
+    # 1b. Zero-template invariant (S2 / ADR-0008): the workspace template must NOT exist.
+    if (ROOT / "workspace-template").exists():
+        problems.append("zero_template_violation:workspace-template directory must be absent")
+
+    # 1c. Clause-coverage invariant (D28): every clause defined in the normative
+    # standards must be either bound in a contract or explicitly registered as
+    # unbound. A clause added to a standards file without a contract binding
+    # fails the verifier exactly like a code regression.
+    defined: set[str] = set()
+    for std_file in (ROOT / "contracts" / "standards").glob("*.md"):
+        for m in re.finditer(r"\*\*([A-Z]+-\d+)(?:\s*[—-])", std_file.read_text(encoding="utf-8")):
+            defined.add(m.group(1))
+    bound: set[str] = set()
+    for contract_name in ("EXECUTION_CONTRACT.json", "VERIFICATION_CONTRACT.json"):
+        contract_data = json.loads((ROOT / "contracts" / contract_name).read_text(encoding="utf-8"))
+
+        def _walk_requirements(node: object) -> None:
+            if isinstance(node, dict):
+                for key, value in node.items():
+                    if key == "requirements" and isinstance(value, list):
+                        bound.update(x for x in value if isinstance(x, str) and re.match(r"^[A-Z]+-\d+$", x))
+                    _walk_requirements(value)
+            elif isinstance(node, list):
+                for item in node:
+                    _walk_requirements(item)
+
+        _walk_requirements(contract_data)
+    for clause in sorted(defined - bound):
+        problems.append(f"clause_coverage_uncovered:{clause} defined in standards but not bound in any contract")
+
+    # 1d. Subprocess script targets referenced by the REPL must exist.
+    repl_path = ROOT / "src" / "pdl_taskmaster" / "host" / "repl.py"
+    if repl_path.is_file():
+        repl_text = repl_path.read_text(encoding="utf-8")
+        for match in re.findall(r'-m",\s*"([^"]+)"', repl_text):
+            try:
+                __import__(match)
+            except ImportError:
+                problems.append(f"missing_repl_subprocess_module:{match}")
+
+    # 2. Broken imports.
+    try:
+        from pdl_taskmaster.host.app import PDLtHost  # noqa: F401
+        from pdl_taskmaster.host.repl import main as repl_main  # noqa: F401
+        from pdl_taskmaster.runtime.session_engine import SessionEngine  # noqa: F401
+        from pdl_taskmaster.providers.fixtures import build_recorded_fixture_from_vendored  # noqa: F401
+    except Exception as exc:
+        problems.append(f"import_failure:{exc}")
+
+    # 3. External-source-repo leakage.
+    for path in ROOT.rglob("*"):
+        if not path.is_file() or ".git" in path.parts or "__pycache__" in path.parts:
+            continue
+        if path.name == "SOURCE_PROVENANCE.json":
+            continue  # provenance must record source repository paths by design
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        for marker in SOURCE_REPO_MARKERS:
+            if marker in text:
+                problems.append(f"source_repo_path_leak:{path.relative_to(ROOT).as_posix()}")
+                break
+    for env_name in ("PYTHONPATH", "PYTHONHOME"):
+        value = os.environ.get(env_name, "")
+        for root in ("PDL-Standard-R2S", "PDL-Standard-R2S-Lab"):
+            if root in value:
+                problems.append(f"environment_leak:{env_name}={value}")
+
+    # 4. Fixture integrity (externalized: PDLT_FIXTURES_PATH -> repo-relative fallback).
+    fixture_dir = _fixture_dir()
+    if not fixture_dir.is_dir():
+        problems.append(
+            "fixture_dir_missing:" + str(fixture_dir) + " (set PDLT_FIXTURES_PATH to the r4-recorded-worker archive directory)"
+        )
+        fixture = {}
+        manifest = {}
+    else:
+        fixture_path = fixture_dir / "recorded-cases.json"
+        try:
+            fixture = json.loads(fixture_path.read_text(encoding="utf-8"))
+        except Exception as exc:
+            problems.append(f"fixture_load_failure:{exc}")
+            fixture = {}
+        manifest = json.loads((fixture_dir / "FIXTURE_MANIFEST.json").read_text(encoding="utf-8"))
+    manifest_prompts = {entry["source_evidence_run"]: entry["prompt_sha256"] for entry in manifest.get("entries", [])}
+    for entry in fixture.get("entries", []):
+        expected = manifest_prompts.get(entry.get("source"))
+        if expected is not None and entry.get("prompt_sha256") != expected:
+            problems.append(f"fixture_hash_mismatch:{entry.get('source')}")
+
+    # 5. Forbidden terms / secrets (classification; absolute source paths above are fatal).
+    for path in ROOT.rglob("*"):
+        if not path.is_file() or ".git" in path.parts or "__pycache__" in path.parts:
+            continue
+        if path.name == "verify_repl_baseline.py":
+            continue  # scanner's own source contains forbidden terms by definition
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        for pattern in SECRET_PATTERNS:
+            if pattern.search(text):
+                problems.append(f"possible_secret:{path.relative_to(ROOT).as_posix()}")
+        for term in FORBIDDEN_TERMS:
+            if term in text:
+                print(f"WARN forbidden-term {term!r} in {path.relative_to(ROOT).as_posix()}")
+
+    return problems
+
+
+def _fresh_workspace_lifecycle() -> dict[str, object]:
+    from pdl_taskmaster.host.app import PDLtHost
+    from pdl_taskmaster.providers.fixtures import build_recorded_fixture_from_vendored
+
+    fixture_file = _fixture_dir() / "recorded-cases.json"
+    fixture = json.loads(fixture_file.read_text(encoding="utf-8"))
+    turns = fixture["case_turns"]["G06"]
+
+    with tempfile.TemporaryDirectory(prefix="repl-baseline-") as tmp:
+        tmp_root = Path(tmp)
+        worker = build_recorded_fixture_from_vendored(ROOT, fixture_file, case_ids=["G06"])
+        host = PDLtHost(
+            ROOT,
+            worker=worker,
+            workspace_root=tmp_root / "workspaces",
+            run_id="baseline",
+            observation_dir=tmp_root / "observations",
+        ).start()
+        stages: list[str] = []
+        try:
+            for turn in turns:
+                result = host.handle(turn)
+                if result.state_after is not None:
+                    stage = (result.state_after.get("controller_state") or {}).get("stage")
+                    if stage:
+                        stages.append(str(stage))
+            status = host.status()
+            workspace_path = Path(status["workspace_path"])
+            final_stage = (status.get("controller_state") or {}).get("stage")
+            from pdl_taskmaster.runtime.workspace import WorkspaceRun as _WR
+            _ws = _WR.open(ROOT, workspace_path)
+            _stages = _ws.stages_root()
+            result_file = _stages / "50_execution" / "output" / "current.json"
+            stage_dirs = sorted(p.name for p in _stages.iterdir() if p.is_dir())
+            fresh_ok = "10_prompt" in stage_dirs and "30_plan" in stage_dirs and "50_execution" in stage_dirs
+            if final_stage != "CLOSED_SUCCESS":
+                raise AssertionError(f"final stage {final_stage!r} != CLOSED_SUCCESS")
+            if not result_file.is_file():
+                raise AssertionError("execution result file missing")
+            if not fresh_ok:
+                raise AssertionError("fresh workspace did not materialize stage directories")
+
+            # Resume the newly-created workspace.
+            worker2 = build_recorded_fixture_from_vendored(ROOT, fixture_file, case_ids=["G06"])
+            resumed = PDLtHost(
+                ROOT,
+                worker=worker2,
+                restore_path=workspace_path,
+                run_id="baseline-resume",
+                observation_dir=tmp_root / "observations-resume",
+            ).start()
+            resume_stage = (resumed.status().get("controller_state") or {}).get("stage")
+            if resume_stage != "CLOSED_SUCCESS":
+                raise AssertionError(f"resume stage {resume_stage!r} != CLOSED_SUCCESS")
+            resumed.close()
+        finally:
+            host.close()
+        return {"stages": stages, "final_stage": final_stage, "resume_stage": resume_stage, "fresh_workspace": fresh_ok}
+
+
+def main() -> int:
+    problems = _failures()
+    lifecycle: dict[str, object] = {}
+    if not problems:
+        try:
+            lifecycle = _fresh_workspace_lifecycle()
+        except Exception as exc:
+            problems.append(f"lifecycle_failure:{exc}")
+    for problem in problems:
+        print(f"FAIL {problem}")
+    print("REPL BASELINE VERIFICATION", "PASS" if not problems else "FAIL")
+    if lifecycle:
+        print(json.dumps(lifecycle, indent=2, sort_keys=True))
+    return 0 if not problems else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pdl_taskmaster-2.4.0.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: pdl-taskmaster
+Version: 2.4.0
+Summary: Deterministic protocol governance and bounded AI agent harness
+Author: PDL-Standard Contributors
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3.0.0,>=2.5.0
+Provides-Extra: dev
+Requires-Dist: anyio>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: tracking
+Requires-Dist: mlflow>=2.0.0; extra == 'tracking'
+Description-Content-Type: text/markdown
+
+# PDL Taskmaster
+*(PDL-Standard-REPL-Harness)*
+
+A REPL harness that makes a language model interpret your request — in short, readable pseudocode — and wait for you to confirm it before anything runs. The same mechanism that catches a misread request also blocks prompt injection: anything quoted or pasted into a task is treated as data at read time and never promoted to an instruction.
+
+**Why this exists:** [`docs/architecture/framing.md`](docs/architecture/framing.md) — the full case, including a live boundary test where the identical model, on one unprotected API call, leaked 2 of 5 injected probes while the protocol held 0 of 5. For the full mechanism, design history, and evidence: [`docs/architecture/whitepaper.md`](docs/architecture/whitepaper.md).
+
+## Repository layout
+
+```text
+contracts/                 versioned standards, contracts, and schemas (normative source)
+confirm-with-pseudocode/   bootstrap skill entrypoint used by the protocol
+src/pdl_taskmaster/        clean Python package root
+  host/                    REPL host, umbrella CLI (pdlt), and application wiring
+  runtime/                 session engine, context compiler, 4-tier standards store, workspace
+  controller/              deterministic mechanical controller
+  providers/               model-worker boundary: api / recorded / codex
+  observation/             JSONL telemetry sinks
+  tracking/                optional MLflow session logger (post-hoc, non-authoritative)
+  eval/                    adversarial battery, fidelity scoring, batch runner
+  verify/                  deterministic baseline verification entry point
+  contracts/               bundled package data contracts (Tier 4 normative store)
+tests/                     pytest suite and vendored self-contained test fixtures
+  fixtures/                vendored recorded cases and adversarial/fidelity batteries
+docs/                      documentation
+  architecture/            framing.md, whitepaper.md, protocol specs
+  operations/              eval-metrics.md, efficiency-report.md
+  governance/              roadmap.md, experiment-log.md (full decision history)
+  adr/ trd/                background architecture-decision records (history, not required reading)
+```
+
+The package ships with self-contained test fixtures vendored under `tests/fixtures/`, enabling 100% offline testing. Historical run ledgers and large evaluation archives are kept in external archives outside this repository and resolve via `PDLT_FIXTURES_PATH` (fixtures) and `PDLT_RUNS_ROOT` (evaluation runs).
+
+## Install
+
+Requirements: Python 3.11+, Pydantic v2 (`pydantic>=2.5.0,<3.0.0`).
+
+```powershell
+# From PyPI (once published)
+pip install pdl-taskmaster
+# or using uv:
+uv add pdl-taskmaster
+
+# Development / editable installation:
+cd PDL-Standard-REPL-Harness
+pip install -e ".[test]"
+# or with optional MLflow tracking:
+pip install -e ".[test,tracking]"
+```
+
+Run every command from this repository root or anywhere when installed as a package.
+
+## Umbrella CLI (`pdlt`)
+
+When installed, the `pdlt` command line tool provides the complete entry point:
+
+```powershell
+pdlt --help                 # View CLI command options and REPL flags
+pdlt version                # Print package version, protocol spec, and manifest hash
+pdlt init --global          # Initialize standards in ~/.pdlt/versions/v2/contracts/
+pdlt init --local           # Seed standards into ./contracts/ in current directory
+pdlt verify                 # Run deterministic baseline verification gate
+pdlt                        # Launch interactive REPL (default)
+```
+
+## Deterministic baseline verification
+
+```powershell
+pdlt verify                 # Deterministic baseline verifier
+pytest                      # Run complete test suite (offline, 87 passed)
+```
+
+The verifier checks required runtime/instructional files, imports, the zero-template workspace invariant, fixture hashes, REPL subprocess-script presence, source-repository isolation, a fresh-workspace lifecycle test (prompt → plan → execute → result), and resuming that same workspace. All verifier workspaces are temporary.
+
+## Interactive REPL (recorded / deterministic)
+
+```powershell
+pdlt --worker recorded --case-ids G06 --new-session
+# or: python -m pdl_taskmaster.host.repl --worker recorded --case-ids G06 --new-session
+```
+
+Recorded mode is **exact, deterministic replay**: it only responds to the exact interaction sequences captured in the fixture (`G06`: full lifecycle; `A02`: prompt revision). Use `--quit` to exit — there's no `/exit` command.
+
+Commands: `/help`, `/status`, `/session`, `/new`, `/resume`, `/mlflow [on|off]`, `/tokens [on|off]`, `/timeout [seconds]`, `/model [name]`, `/worker [api|codex|recorded]`, `/config` (codex only), `/sandbox` (codex only), `/workdir [path]`, `/transcript [path]`, `/quit`.
+
+Fast-path review commands: `/confirm`, `/revise <feedback>`, `/stop`.
+
+## Live model worker (default)
+
+```powershell
+# Default worker is 'api' with model 'z-ai/glm-4.7'
+pdlt --new-session
+# or: python -m pdl_taskmaster.host.repl --candidate-repo . --new-session
+```
+
+> **System 1 / System 2 Architecture Note**: Production default is `--worker api` (System 2, e.g. `z-ai/glm-4.7`). Local fast System 1 classification models are undergoing contrastive RLCD fine-tuning (ADR-0012) and fail-closed to System 2 via the confidence ladder if threshold ($0.85$) or top-2 margin ($0.40$) are unmet.
+
+`--worker api` sends the compiled interpretation/plan directly to an OpenAI-compatible `/responses` endpoint (instructions bundled in `src/pdl_taskmaster/runtime/worker-bootstrap.txt`), with no tool definitions, sandbox, or agentic system prompt attached — deliberately; see the "instruction-lightness" finding in the whitepaper (§3).
+
+### Efficiency flags (`--worker api`)
+
+- `--api-reasoning-effort low|medium|high` — reasoning budget override, applied globally.
+- `--api-reasoning-operation OP=EFFORT` (repeatable) — per-step override; sensible per-model defaults are already wired in (see whitepaper §4).
+- `--api-model-operation OP=MODEL` (repeatable) — per-step model override, e.g. keep interpretation on a frontier model and route everything else to a cheaper instruction-following one.
+- `--render-compact` / `--render-pretty` — how the interpretation/plan is serialized on the wire (compact is the default for `--worker api`).
+- `--cache-order-render` — opt-in reordering for provider-side prefix caching.
+
+Per-call cost data, and which optimizations were tried and rejected: [`docs/operations/efficiency-report.md`](docs/operations/efficiency-report.md).
+
+## Adversarial evaluation
+
+```powershell
+python -m pdl_taskmaster.eval.run_qualified_batch --case-id BND-00 --stub --trials 1
+python -m pdl_taskmaster.eval.run_qualified_batch --case-id BND-00 --trials 1 --model z-ai/glm-4.7
+python -m pdl_taskmaster.eval.compare_eval_runs <summary.json>
+```
+
+The battery manifest and prior run ledgers resolve via `PDLT_RUNS_ROOT` (defaults to a sibling archive directory not included in this repository — point it at your own results directory to run the battery from scratch). Measured baselines so far: [`docs/operations/eval-metrics.md`](docs/operations/eval-metrics.md).
+
+## Notes
+
+- Run artifacts (`runs/`, `mlruns/`) and external evaluation archives are **not** runtime dependencies and are kept outside the repository. The optional MLflow tracking store follows the same pattern (override with `PDLT_MLFLOW_DB`; falls back to a repo-root `mlflow.db` if unset).
+- Workspaces are zero-template and dynamic: a fresh run scaffolds only `state/`, `events/`, `stages/`, `shared/`, and stage folders materialize as they're needed (see whitepaper §5).
+- `SOURCE_PROVENANCE.json` records per-file provenance (source repo, commit, hashes, byte-identical vs. adapted) from the original extraction.
+- Internal architecture/technical decision records referenced elsewhere in these docs (`docs/adr/`, `docs/trd/`) are background only and not required reading to use the harness.
+
+## Optional MLflow logging
+
+MLflow logging is post-hoc and non-authoritative; the protocol never requires it. Enable it by answering `y` to the startup prompt, launching with `--mlflow`, or toggling with `/mlflow on`. When enabled, closed sessions are logged via `pdl_taskmaster.tracking.log_live_session` to a local SQLite store (default location follows the archive-resolution pattern described above) under experiment `PDL-R2S`, printing a `LIVE_SESSION_MLFLOW_RUN` line per logged session. Only sessions that completed at least one protocol turn are logged. Requires `pip install "pdl-taskmaster[tracking]"`.