simplicio-loop 3.25.1__tar.gz → 3.31.1__tar.gz

{simplicio_loop-3.25.1/simplicio_loop.egg-info → simplicio_loop-3.31.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplicio-loop
-Version: 3.25.1
+Version: 3.31.1
 Summary: The Universal Looping AI Orchestrator — a runtime-agnostic super-plugin (7 skills) that drains any queue of work end-to-end on any LLM/runtime.
 Author-email: Wesley Simplicio <wesleybob4@gmail.com>
 License: MIT

{simplicio_loop-3.25.1 → simplicio_loop-3.31.1}/README.md

@@ -55,6 +55,9 @@
 
 - **Contract first** — acceptance criteria, dependencies, risks, source state, and the completion oracle are explicit before execution.
 - **Parallel without corruption** — ready tasks run in isolated lanes/worktrees and converge through an operational ledger.
+- **Automatic fan-out by default** — `batch` provisions one owned worktree per independent,
+  authorized task; overlap, missing evidence, or unavailable isolation falls back to a
+  visible serial lane. See [`docs/AUTO_FAN_OUT.md`](docs/AUTO_FAN_OUT.md).
 - **Proof before completion** — tests, impact/flow checks, watcher challenges, delivery receipts, and HBP evidence reject false done states.
 - **Memory that changes behavior** — the journal, stall detector, checkpoints, and cross-agent wiki prevent oscillation and make handoffs durable.
 
@@ -124,6 +127,23 @@ company work. `simplicio-runtime` is the unified entrypoint going forward, but i
 reuse this loop's evidence-gated converge/drain discipline, durable attempt journal, and worker
 coordination patterns instead of creating a separate task semantics.
 
+### 👁️ Progresso visual, honesto e portátil
+
+Cada execução pode ser acompanhada por texto, Markdown, JSON ou uma animação ANSI. Todas as
+superfícies consomem o mesmo evento `simplicio.progress/v1`, incluindo ícones de etapa, gates de
+evidence/watcher/oracle, lanes de worktrees e eventos de `worker_claimed` até `delivery_reconciled`.
+
+```powershell
+simplicio-loop progress <run-id> --format text --once
+simplicio-loop progress <run-id> --format markdown --once   # LLM/chat
+simplicio-loop progress <run-id> --format json --once       # dashboard/adapters
+simplicio-loop progress <run-id> --format text --ascii --no-animation  # log/PowerShell
+```
+
+`100%` só aparece com receipt do oracle pronto (`COMPLETE`/`DRAINED`); uma fase `done` sem prova
+fica quase concluída e mostra o blocker. Consulte o contrato completo em
+[`docs/PROGRESS_PROTOCOL.md`](docs/PROGRESS_PROTOCOL.md).
+
 ---
 
 ## 🤖 LLM front door

{simplicio_loop-3.25.1 → simplicio_loop-3.31.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simplicio-loop"
-version = "3.25.1"
+version = "3.31.1"
 description = "The Universal Looping AI Orchestrator — a runtime-agnostic super-plugin (7 skills) that drains any queue of work end-to-end on any LLM/runtime."
 readme = "PYPI.md"
 requires-python = ">=3.8"

{simplicio_loop-3.25.1 → simplicio_loop-3.31.1}/simplicio_loop/__init__.py

@@ -13,6 +13,6 @@ try:
     try:
         __version__ = _v("simplicio-loop")
     except PackageNotFoundError:
-        __version__ = "3.25.1"
+        __version__ = "3.31.1"
 except Exception:  # pragma: no cover
-    __version__ = "3.25.1"
+    __version__ = "3.31.1"

simplicio_loop-3.31.1/simplicio_loop/agent_contract.py

@@ -0,0 +1,79 @@
+"""Identity, context-isolation and receipt bindings for distributed workers.
+
+The queue identifies *who* owns a lease; this module defines the smaller
+contract that may cross a device boundary.  A context pack contains only the
+assigned work item and allow-listed source references.  Prompts, transcripts,
+environment variables and another worker's private state are never copied.
+"""
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any, Mapping, Sequence
+
+SCHEMA = "simplicio.agent-context/v1"
+RECEIPT_SCHEMA = "simplicio.agent-receipt/v1"
+IDENTITY_FIELDS = ("agent_id", "runtime", "device_id", "session_id")
+CAPABILITIES = frozenset(("claim", "heartbeat", "fencing", "receipts", "events", "evidence", "completion"))
+
+
+class AgentContractError(ValueError):
+    """Raised when an identity, capability set, or context pack is unsafe."""
+
+
+def validate_identity(identity: Mapping[str, Any], *, capabilities: Sequence[str] | None = None) -> dict[str, Any]:
+    if not isinstance(identity, Mapping):
+        raise AgentContractError("agent identity must be an object")
+    result = {field: str(identity.get(field) or "").strip() for field in IDENTITY_FIELDS}
+    missing = [field for field, value in result.items() if not value]
+    if missing:
+        raise AgentContractError("agent identity missing: " + ", ".join(missing))
+    raw_caps = list(capabilities if capabilities is not None else (identity.get("capabilities") or []))
+    if any(not isinstance(cap, str) or not cap.strip() for cap in raw_caps):
+        raise AgentContractError("capabilities must contain non-empty strings")
+    normalized = [cap.strip() for cap in raw_caps]
+    if len(set(normalized)) != len(normalized):
+        raise AgentContractError("duplicate capabilities are not allowed")
+    unknown = sorted(set(normalized).difference(CAPABILITIES))
+    if unknown:
+        raise AgentContractError("unsupported capabilities: " + ", ".join(unknown))
+    result["capabilities"] = normalized
+    result["protocol"] = str(identity.get("protocol") or "simplicio-distributed/v1")
+    return result
+
+
+def build_context_pack(*, task_id: str, goal: str, identity: Mapping[str, Any],
+                       acs: Sequence[str] = (), source_refs: Sequence[str] = (),
+                       depends_on: Sequence[str] = (), allowed_paths: Sequence[str] = ()) -> dict[str, Any]:
+    """Build a deterministic, minimum-necessary context for one worker."""
+    normalized = validate_identity(identity)
+    allow = {str(path).strip() for path in allowed_paths if str(path).strip()}
+    refs = [str(path).strip() for path in source_refs if str(path).strip() and str(path).strip() in allow]
+    return {
+        "schema": SCHEMA,
+        "task_id": str(task_id).strip(),
+        "goal": str(goal).strip(),
+        "acs": [str(ac).strip() for ac in acs if str(ac).strip()],
+        "source_refs": refs,
+        "depends_on": [str(dep).strip() for dep in depends_on if str(dep).strip()],
+        "assigned_to": {field: normalized[field] for field in IDENTITY_FIELDS},
+        "capabilities": list(normalized["capabilities"]),
+    }
+
+
+def bind_receipt(receipt: Mapping[str, Any], identity: Mapping[str, Any], *, context_pack: Mapping[str, Any] | None = None) -> dict[str, Any]:
+    """Return a receipt carrying immutable agent identity and isolated context."""
+    normalized = validate_identity(identity)
+    result = deepcopy(dict(receipt))
+    existing = result.get("agent")
+    if existing is not None and validate_identity(existing) != normalized:
+        raise AgentContractError("receipt agent identity mismatch")
+    result["schema"] = result.get("schema") or RECEIPT_SCHEMA
+    result["agent"] = normalized
+    if context_pack is not None:
+        if context_pack.get("assigned_to") != {field: normalized[field] for field in IDENTITY_FIELDS}:
+            raise AgentContractError("context pack is assigned to another agent")
+        result["context"] = deepcopy(dict(context_pack))
+    return result
+
+
+__all__ = ["AgentContractError", "CAPABILITIES", "IDENTITY_FIELDS", "RECEIPT_SCHEMA", "SCHEMA", "bind_receipt", "build_context_pack", "validate_identity"]

simplicio_loop-3.31.1/simplicio_loop/attempt_journal.py

@@ -0,0 +1,251 @@
+"""Typed, append-only attempt observations for Loop/Runtime reconciliation.
+
+``loop_journal.py`` is intentionally human-friendly and accepts legacy rows.  This
+module is the machine-facing companion: every row has stable identity, causal
+lineage, a hash-chain link and an explicit claim class.  It is transport agnostic
+and can therefore be exported to Runtime or replayed after a provider handoff.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Mapping, Optional
+
+from .ops_ledger import _locks
+
+SCHEMA = "simplicio.loop-observation/v1"
+EVENT_KINDS = frozenset((
+    "hypothesis", "action", "tool_execution", "validation", "failure",
+    "observation", "decision",
+))
+CLAIM_TYPES = frozenset(("MEASURED", "UNVERIFIED", "ESTIMATED"))
+
+
+class AttemptJournalError(ValueError):
+    """Raised when journal data cannot be safely appended or replayed."""
+
+
+def _canonical(value: Mapping[str, Any]) -> str:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+def _hash(value: Mapping[str, Any]) -> str:
+    return hashlib.sha256(_canonical(value).encode("utf-8")).hexdigest()
+
+
+def _text(value: Any, name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise AttemptJournalError("%s must be a non-empty string" % name)
+    return value.strip()
+
+
+def build_observation(*, run_id: str, work_item_id: str, attempt_id: str,
+                      actor: str, kind: str, payload: Mapping[str, Any],
+                      sequence: int, event_id: str, causation_id: Optional[str] = None,
+                      claim_type: str = "UNVERIFIED", ac_ids: Optional[Iterable[str]] = None,
+                      observed_at: Optional[str] = None) -> Dict[str, Any]:
+    """Build one validated typed observation envelope.
+
+    ``event_id`` is caller-owned so retries can reuse it.  Reusing an ID with a
+    changed envelope is rejected by :class:`AttemptJournal` rather than silently
+    creating a second attempt.
+    """
+    if isinstance(sequence, bool) or not isinstance(sequence, int) or sequence < 1:
+        raise AttemptJournalError("sequence must be a positive integer")
+    kind = _text(kind, "kind")
+    if kind not in EVENT_KINDS:
+        raise AttemptJournalError("unsupported observation kind: %s" % kind)
+    if not isinstance(payload, Mapping):
+        raise AttemptJournalError("payload must be an object")
+    claim_type = _text(claim_type, "claim_type").upper()
+    if claim_type not in CLAIM_TYPES:
+        raise AttemptJournalError("unsupported claim_type: %s" % claim_type)
+    criteria = list(ac_ids or ())
+    if any(not isinstance(item, str) or not item.strip() for item in criteria):
+        raise AttemptJournalError("ac_ids must contain non-empty strings")
+    event: Dict[str, Any] = {
+        "schema": SCHEMA,
+        "sequence": sequence,
+        "event_id": _text(event_id, "event_id"),
+        "run_id": _text(run_id, "run_id"),
+        "work_item_id": _text(work_item_id, "work_item_id"),
+        "attempt_id": _text(attempt_id, "attempt_id"),
+        "actor": _text(actor, "actor"),
+        "kind": kind,
+        "causation_id": _text(causation_id or event_id, "causation_id"),
+        "claim_type": claim_type,
+        "ac_ids": criteria,
+        "payload": dict(payload),
+    }
+    if kind == "failure":
+        # Providers may supply the loop_journal fingerprint; otherwise derive a
+        # provider-independent digest from the failure payload.  This is the
+        # identity used to decide whether a resumed retry is genuinely new.
+        supplied = payload.get("failure_fingerprint", payload.get("fingerprint"))
+        event["failure_fingerprint"] = _text(supplied, "failure_fingerprint") if supplied else _hash(payload)[:12]
+    if observed_at is not None:
+        event["observed_at"] = _text(observed_at, "observed_at")
+    return event
+
+
+def validate_observation(event: Mapping[str, Any]) -> Dict[str, Any]:
+    if not isinstance(event, Mapping) or event.get("schema") != SCHEMA:
+        raise AttemptJournalError("unsupported observation schema")
+    required = ("event_id", "run_id", "work_item_id", "attempt_id", "actor",
+                "kind", "causation_id", "claim_type", "ac_ids", "payload")
+    for field in required:
+        if field not in event:
+            raise AttemptJournalError("observation missing %s" % field)
+    checked = build_observation(
+        run_id=event["run_id"], work_item_id=event["work_item_id"],
+        attempt_id=event["attempt_id"], actor=event["actor"], kind=event["kind"],
+        payload=event["payload"], sequence=event["sequence"], event_id=event["event_id"],
+        causation_id=event.get("causation_id"), claim_type=event["claim_type"],
+        ac_ids=event.get("ac_ids"), observed_at=event.get("observed_at"),
+    )
+    if event.get("kind") == "failure" and event.get("failure_fingerprint") != checked.get("failure_fingerprint"):
+        raise AttemptJournalError("failure fingerprint mismatch")
+    if set(event) - set(checked):
+        # Forward-compatible fields are allowed, but are included in the hash and
+        # therefore cannot be changed during replay.
+        checked.update({key: event[key] for key in set(event) - set(checked)})
+    return checked
+
+
+class AttemptJournal:
+    """Hash-chained JSONL journal with idempotent append and deterministic import."""
+
+    def __init__(self, path: str | os.PathLike[str]):
+        self.path = Path(path)
+        self.lock_path = Path(str(self.path) + ".lock")
+
+    def _lock(self):
+        if _locks is None:
+            raise AttemptJournalError("cross-process locking helper is unavailable")
+        _locks._ensure_lock_file(str(self.lock_path))
+        if _locks.fcntl is not None:
+            handle = self.lock_path.open("a+b")
+            if not _locks._acquire_posix(handle, _locks.DEFAULT_TIMEOUT_MS):
+                handle.close()
+                raise AttemptJournalError("journal lock acquisition timed out")
+            return handle, _locks._release_posix
+        if _locks.msvcrt is not None:  # pragma: no cover - exercised on Windows CI
+            handle = self.lock_path.open("r+b")
+            if not _locks._acquire_windows(handle, _locks.DEFAULT_TIMEOUT_MS):
+                handle.close()
+                raise AttemptJournalError("journal lock acquisition timed out")
+            return handle, _locks._release_windows
+        raise AttemptJournalError("no cross-process locking primitive is available")
+
+    def _read(self) -> List[Dict[str, Any]]:
+        if not self.path.exists():
+            return []
+        rows: List[Dict[str, Any]] = []
+        for n, line in enumerate(self.path.read_text(encoding="utf-8").splitlines(), 1):
+            if not line.strip():
+                continue
+            try:
+                row = json.loads(line)
+            except ValueError as exc:
+                raise AttemptJournalError("invalid JSON at journal line %d" % n) from exc
+            if not isinstance(row, dict):
+                raise AttemptJournalError("journal line %d is not an object" % n)
+            rows.append(row)
+        return rows
+
+    @staticmethod
+    def _verify(rows: List[Dict[str, Any]]) -> None:
+        previous = ""
+        for expected, row in enumerate(rows, 1):
+            validate_observation(row)
+            if row.get("sequence") != expected or row.get("prev_hash", "") != previous:
+                raise AttemptJournalError("journal sequence/hash gap at %s" % row.get("event_id", "?"))
+            body = dict(row)
+            recorded = body.pop("hash", None)
+            if recorded != _hash(body):
+                raise AttemptJournalError("journal hash mismatch at %s" % row.get("event_id", "?"))
+            previous = recorded
+
+    def replay(self) -> List[Dict[str, Any]]:
+        handle, release = self._lock()
+        try:
+            rows = self._read()
+            self._verify(rows)
+            return rows
+        finally:
+            release(handle)
+            handle.close()
+
+    def append(self, event: Mapping[str, Any]) -> Dict[str, Any]:
+        normalized = validate_observation(event)
+        handle, release = self._lock()
+        try:
+            rows = self._read()
+            self._verify(rows)
+            for prior in rows:
+                if prior.get("event_id") == normalized["event_id"]:
+                    prior_core = {key: value for key, value in prior.items()
+                                  if key not in ("sequence", "prev_hash", "hash")}
+                    normalized_core = {key: value for key, value in normalized.items()
+                                       if key not in ("sequence", "prev_hash", "hash")}
+                    if prior_core == normalized_core:
+                        return prior
+                    raise AttemptJournalError("event_id already exists with a different envelope")
+            body = dict(normalized)
+            # Imported envelopes carry their source chain metadata.  Recompute
+            # local sequence/link/hash instead of hashing the old hash field.
+            body.pop("hash", None)
+            body.pop("prev_hash", None)
+            body["sequence"] = len(rows) + 1
+            body["prev_hash"] = rows[-1].get("hash", "") if rows else ""
+            body["hash"] = _hash(body)
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            with self.path.open("a", encoding="utf-8", newline="\n") as stream:
+                stream.write(json.dumps(body, ensure_ascii=False, sort_keys=True) + "\n")
+                stream.flush()
+                os.fsync(stream.fileno())
+            return body
+        finally:
+            release(handle)
+            handle.close()
+
+    def import_legacy(self, path: str | os.PathLike[str], *, run_id: str,
+                      work_item_id: str, attempt_id: str, actor: str) -> List[Dict[str, Any]]:
+        """Migrate human journal rows deterministically; source is never modified."""
+        source = Path(path)
+        if not source.exists():
+            raise AttemptJournalError("legacy journal does not exist")
+        imported: List[Dict[str, Any]] = []
+        for index, raw in enumerate(source.read_text(encoding="utf-8").splitlines(), 1):
+            if not raw.strip():
+                continue
+            try:
+                old = json.loads(raw)
+            except ValueError as exc:
+                raise AttemptJournalError("invalid legacy JSON at line %d" % index) from exc
+            gate = str(old.get("gate", "blocked")).lower()
+            kind = "validation" if gate == "pass" else ("failure" if gate == "fail" else "observation")
+            event = build_observation(
+                run_id=run_id, work_item_id=work_item_id, attempt_id=attempt_id,
+                actor=actor, kind=kind, sequence=index, event_id="legacy-%d" % index,
+                causation_id="legacy-%d" % index,
+                claim_type="MEASURED" if gate == "pass" else "UNVERIFIED",
+                payload={"legacy": old},
+            )
+            imported.append(self.append(event))
+        return imported
+
+    def export(self) -> List[Dict[str, Any]]:
+        """Return the verified canonical envelopes for Runtime ingestion."""
+        return self.replay()
+
+    def import_events(self, events: Iterable[Mapping[str, Any]]) -> List[Dict[str, Any]]:
+        """Validate and idempotently ingest envelopes from Runtime or another host."""
+        return [self.append(event) for event in events]
+
+
+__all__ = ["AttemptJournal", "AttemptJournalError", "CLAIM_TYPES", "EVENT_KINDS",
+           "SCHEMA", "build_observation", "validate_observation"]

{simplicio_loop-3.25.1 → simplicio_loop-3.31.1}/simplicio_loop/cli.py

@@ -42,6 +42,8 @@ from .ops_ledger import (
     LedgerError,
     validate_handshake,
 )
+from .progress import stream as stream_progress
+from .oracle import evaluate_matrix, persist_completion_receipt
 
 BUNDLE = Path(__file__).resolve().parent / "_bundle"
 DASHBOARD = BUNDLE / "hooks" / "simplicio_dashboard.py"
@@ -208,7 +210,8 @@ def tick(repo: str, run_id: str, task_index: int) -> int:
     return 0
 
 
-def batch(repo: str, run_id: str, task_indices: str, max_workers: int, retry_budget: int) -> int:
+def batch(repo: str, run_id: str, task_indices: str, max_workers: int, retry_budget: int,
+          serial: bool = False) -> int:
     """Run selected ready tasks through the durable real-operator pool."""
     indices = None
     if task_indices.strip():
@@ -222,6 +225,7 @@ def batch(repo: str, run_id: str, task_indices: str, max_workers: int, retry_bud
         indices,
         max_workers=max_workers or None,
         retry_budget=retry_budget,
+        auto_fan_out=not serial,
     )
     print(json.dumps(payload, ensure_ascii=False, indent=2))
     return 0
@@ -233,6 +237,38 @@ def cancel(repo: str, run_id: str) -> int:
     return 0
 
 
+def oracle(loop_dir: str, run_dir: str, response_text: str, flow_gap: str,
+           write_receipt: bool) -> int:
+    """Evaluate the shared completion oracle and its cross-runtime parity."""
+    payload = evaluate_matrix(loop_dir, run_dir, response_text=response_text, flow_gap=flow_gap)
+    if write_receipt:
+        # Persist the canonical verdict once; the matrix is only the parity proof.
+        from .oracle import evaluate_completion
+        verdict = evaluate_completion(loop_dir, run_dir, response_text=response_text,
+                                      flow_gap=flow_gap)
+        payload["receipt_path"] = persist_completion_receipt(verdict, loop_dir, run_dir)
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0 if payload.get("parity") and payload.get("signature", [False])[0] else 1
+
+
+def progress(repo: str, run_id: str, fmt: str, once: bool, interval: float,
+             no_animation: bool = False, ascii_only: bool = False) -> int:
+    """Render a run's portable progress event for an LLM, terminal, or dashboard."""
+    try:
+        status = read_status(repo, run_id)
+    except (FileNotFoundError, OSError, ValueError, KeyError) as exc:
+        print(json.dumps({"schema": "simplicio.progress/v1", "status": "UNVERIFIED",
+                          "reason_code": "run_missing", "error": str(exc)}, ensure_ascii=False))
+        return 2
+    if not status or not status.get("run_dir"):
+        print(json.dumps({"schema": "simplicio.progress/v1", "status": "UNVERIFIED",
+                          "reason_code": "run_missing"}, ensure_ascii=False))
+        return 2
+    stream_progress(status["run_dir"], fmt=fmt, once=once, interval=interval,
+                    no_animation=no_animation, ascii_only=ascii_only)
+    return 0
+
+
 def maintenance_deferred(repo: str, run_id: str, mode: str, disposition: str,
                          correction_summary: str, deferral_reason: str,
                          resume_instructions: list[str], evidence_status: str) -> int:
@@ -484,10 +520,30 @@ def main(argv=None) -> int:
     p_run.add_argument("--delivery", default="verified", help="requested delivery target")
     p_run.add_argument("--max-iterations", type=int, default=12, help="safety cap")
 
+    p_oracle = sub.add_parser("oracle", help="evaluate completion and cross-runtime parity")
+    p_oracle.add_argument("--loop-dir", default=os.path.join(".orchestrator", "loop"))
+    p_oracle.add_argument("--run-dir", default=os.environ.get("SIMPLICIO_RUN_DIR", ""))
+    p_oracle.add_argument("--response-text", default="")
+    p_oracle.add_argument("--flow-gap", default="")
+    p_oracle.add_argument("--write-receipt", action="store_true")
+
     p_status = sub.add_parser("status", help="show the latest run state or a specific run")
     p_status.add_argument("--repo", default=".", help="repository root")
     p_status.add_argument("--run-id", default="", help="run id to inspect")
 
+    p_progress = sub.add_parser("progress", help="render visual progress for a run")
+    p_progress.add_argument("--repo", default=".", help="repository root")
+    p_progress.add_argument("run_id", help="run id to render")
+    p_progress.add_argument("--format", choices=("text", "json", "markdown", "ansi"),
+                            default="text", dest="fmt", help="output format")
+    p_progress.add_argument("--once", action="store_true", help="render one snapshot")
+    p_progress.add_argument("--no-animation", action="store_true",
+                            help="emit one static snapshot without spinner/ANSI control codes")
+    p_progress.add_argument("--ascii", action="store_true", dest="ascii_only",
+                            help="use ASCII icons/bar for terminals without Unicode support")
+    p_progress.add_argument("--interval", type=float, default=0.25,
+                            help="animation polling interval in seconds")
+
     p_resume = sub.add_parser("resume", help="resume a non-terminal run")
     p_resume.add_argument("--repo", default=".", help="repository root")
     p_resume.add_argument("run_id", help="run id to resume")
@@ -512,6 +568,10 @@ def main(argv=None) -> int:
         help="maximum live operator workers (default: SIMPLICIO_LOOP_OPERATOR_WORKERS/6)",
     )
     p_batch.add_argument("--retry-budget", type=int, default=3, help="retries after the first attempt")
+    p_batch.add_argument(
+        "--serial", action="store_true",
+        help="disable the default isolated fan-out and force the shared-run serial lane",
+    )
 
     p_cancel = sub.add_parser("cancel", help="cancel a non-terminal run")
     p_cancel.add_argument("--repo", default=".", help="repository root")
@@ -611,14 +671,20 @@ def main(argv=None) -> int:
         return plan(args.task, args.out)
     if command == "run":
         return run(args.repo, args.task, args.delivery, args.max_iterations)
+    if command == "oracle":
+        return oracle(args.loop_dir, args.run_dir, args.response_text, args.flow_gap,
+                      args.write_receipt)
     if command == "status":
         return status(args.repo, args.run_id)
+    if command == "progress":
+        return progress(args.repo, args.run_id, args.fmt, args.once, args.interval,
+                        args.no_animation, args.ascii_only)
     if command == "resume":
         return resume(args.repo, args.run_id)
     if command == "tick":
         return tick(args.repo, args.run_id, args.task_index)
     if command == "batch":
-        return batch(args.repo, args.run_id, args.task_indices, args.max_workers, args.retry_budget)
+        return batch(args.repo, args.run_id, args.task_indices, args.max_workers, args.retry_budget, args.serial)
     if command == "cancel":
         return cancel(args.repo, args.run_id)
     if command in {"maintenance-deferred", "defer-maintenance"}:

simplicio_loop-3.31.1/simplicio_loop/driver_contract.py

@@ -0,0 +1,101 @@
+"""Host-neutral loop driver contract.
+
+Hook callbacks and scheduler ticks are transports, not separate state machines.  This
+module normalizes either transport into one deterministic decision and canonical event
+stream.  It is intentionally stdlib-only so runtimes can import it without the CLI.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Dict, Iterable, List, Mapping
+
+SCHEMA = "simplicio.loop-driver/v1"
+
+
+class DriverContractError(ValueError):
+    pass
+
+
+def _canon(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+def event_id(event: Mapping[str, Any]) -> str:
+    """Return a stable id when a transport did not provide one."""
+    explicit = str(event.get("event_id") or "").strip()
+    if explicit:
+        return explicit
+    seed = {k: event.get(k) for k in ("run_id", "iteration", "phase", "decision", "reason_code")}
+    return "evt-" + hashlib.sha256(_canon(seed).encode("utf-8")).hexdigest()[:20]
+
+
+def normalize_event(raw: Mapping[str, Any], source: str) -> Dict[str, Any]:
+    """Normalize hook/self-paced observations into the same envelope."""
+    if not isinstance(raw, Mapping):
+        raise DriverContractError("driver event must be an object")
+    source = str(source or raw.get("source") or "").strip().lower()
+    if source not in {"hook", "self-paced"}:
+        raise DriverContractError("source must be hook or self-paced")
+    event = {
+        "schema": SCHEMA,
+        "event_id": event_id(raw),
+        "source": source,
+        "run_id": str(raw.get("run_id") or "").strip(),
+        "iteration": int(raw.get("iteration") or 0),
+        "phase": str(raw.get("phase") or "tick").strip(),
+        "decision": str(raw.get("decision") or "continue").strip().lower(),
+        "reason_code": str(raw.get("reason_code") or "").strip(),
+        "gates": dict(raw.get("gates") or {}),
+    }
+    if event["iteration"] < 0:
+        raise DriverContractError("iteration must be non-negative")
+    if event["decision"] not in {"continue", "stop", "block"}:
+        raise DriverContractError("invalid driver decision")
+    return event
+
+
+def reconcile_events(events: Iterable[Mapping[str, Any]]) -> List[Dict[str, Any]]:
+    """Deduplicate identical callbacks and reject conflicting duplicate ids."""
+    seen: Dict[str, Dict[str, Any]] = {}
+    for raw in events:
+        source = str(raw.get("source") or "").strip().lower()
+        event = normalize_event(raw, source)
+        key = event["event_id"]
+        prior = seen.get(key)
+        if prior is not None:
+            # Hook and scheduler may deliver the same logical tick.  Transport
+            # identity is deliberately excluded from the conflict comparison.
+            left = dict(prior); right = dict(event)
+            left.pop("source", None); right.pop("source", None)
+            if _canon(left) != _canon(right):
+                raise DriverContractError("conflicting duplicate event: %s" % key)
+            continue
+        seen[key] = event
+    return sorted(seen.values(), key=lambda item: (item["iteration"], item["event_id"]))
+
+
+def evaluate_tick(snapshot: Mapping[str, Any]) -> Dict[str, Any]:
+    """Apply shared cap/STOP/evidence gates; absent hook delivery never completes."""
+    if not isinstance(snapshot, Mapping):
+        raise DriverContractError("snapshot must be an object")
+    mode = str(snapshot.get("mode") or "self-paced").strip().lower()
+    if mode not in {"hook", "self-paced"}:
+        raise DriverContractError("mode must be hook or self-paced")
+    iteration = int(snapshot.get("iteration") or 0)
+    maximum = int(snapshot.get("max_iterations") or 1)
+    if iteration < 0 or maximum < 1:
+        raise DriverContractError("invalid iteration cap")
+    gates = dict(snapshot.get("gates") or {})
+    if snapshot.get("hook_delivered") is False:
+        return {"schema": SCHEMA, "decision": "block", "reason_code": "hook_missing", "tag": "UNVERIFIED", "mode": mode}
+    if snapshot.get("stop_requested") is True:
+        return {"schema": SCHEMA, "decision": "block", "reason_code": "stop_requested", "tag": "UNVERIFIED", "mode": mode}
+    if iteration >= maximum:
+        return {"schema": SCHEMA, "decision": "block", "reason_code": "iteration_cap", "tag": "UNVERIFIED", "mode": mode}
+    if snapshot.get("promise_exact") is True and all(bool(gates.get(name)) for name in ("watcher", "evidence", "oracle")):
+        return {"schema": SCHEMA, "decision": "stop", "reason_code": "completion_verified", "tag": "MEASURED", "mode": mode}
+    return {"schema": SCHEMA, "decision": "continue", "reason_code": "gates_pending", "tag": "UNVERIFIED", "mode": mode}
+
+
+__all__ = ["SCHEMA", "DriverContractError", "event_id", "normalize_event", "reconcile_events", "evaluate_tick"]

{simplicio_loop-3.25.1 → simplicio_loop-3.31.1}/simplicio_loop/evidence.py

@@ -79,8 +79,12 @@ def _command_policy(check: Dict[str, Any]) -> tuple[List[str] | None, str]:
         return None, "no argv resolved"
     exe = Path(normalized[0]).name.lower()
     if exe.endswith(".exe"):
-        exe = exe
-    if exe not in SAFE_EXECUTABLES and not normalized[0].lower().endswith(".py"):
+        exe = exe[:-4]
+    # Test runners and receipts often pass an absolute interpreter path
+    # (python3.11, python3.14, ...). Treat versioned Python executables as
+    # equivalent to the explicitly allowlisted python/python3 commands.
+    python_executable = exe == "python" or exe.startswith("python3.")
+    if exe not in SAFE_EXECUTABLES and not python_executable and not normalized[0].lower().endswith(".py"):
         return None, f"command executable not allowlisted: {normalized[0]}"
     return normalized, "allowed"