Skip to main content

phase-loop-runtime

The harness-neutral phase-loop orchestration runtime and CLI. It drives the roadmap → plan → execute workflow by dispatching each phase to whatever harness you choose (Claude / Codex / Gemini / Grok / OpenCode / Pi); the runtime itself makes no model calls. Part of the public agent-harness monorepo (Apache-2.0).

Install

Version 0.7.31 requires Python 3.12+ (agent-harness#1549). The host-side jail helpers remain 3.10-compatible, but a governed-review falsifier node importing the runtime under an older host interpreter ends in error and remains a blocking receipt. The agy live qualification is renewed on the exact 0.7.31 release-cut commit. Exact-candidate package and compatibility checks remain release-cut gates; qualification evidence and historical runtime smoke limitations are recorded in the release handoff.

Most users should use the repo's installer (it also installs the workflow skills):

git clone https://github.com/Consiliency/agent-harness
agent-harness/install-agent-harness.sh --harness claude

To install just this runtime package directly (0.7.34 is an unpublished candidate; the exact pin below becomes available only after publication):

pip install phase-loop-runtime              # latest compatible release
pip install phase-loop-runtime==0.7.34      # candidate pin; unavailable before publication

To pin a specific tag from source instead, substitute a tag from Releases:

uv tool install "git+https://github.com/Consiliency/agent-harness@<TAG>#subdirectory=phase-loop-runtime"

This exposes five console scripts: phase-loop and codex-phase-loop (both calling phase_loop_runtime.cli:main), phase-loop-closeout-audit (the closeout ignored-output audit), phase-loop-skill-eval (the opt-in diagnostic planning evaluator; see the guide) and roadmap-ownership (the roadmap-ownership preflight). The canonical protocol document ships in the wheel as package data (from src/phase_loop_runtime/_contract_docs/phase-loop/protocol.md); an older copy is also installed to share/phase-loop-runtime/protocol/protocol.md.

Offline repository-map artifacts

Legacy phase-loop fleet-map --repo <path> --json output remains unchanged. Artifact mode accepts a closed fleet_scan_input.v1 manifest and explicit provenance:

phase-loop fleet-map --manifest scan-input.json \
  --producer-commit <producer-source-sha> --generated-at <UTC-timestamp> \
  --output fleet-map.json

The packaged artifact schema defines the output and the input and source-pin $defs. Input repository entries use qualified identities such as Example/source, numeric provider IDs, captured default-branch SHAs, collection states and paths relative to an absolute clone root. Account counts must describe the complete declared enumeration. Failed collection or file inspection stays explicit and never becomes covered zero relationships.

The extractor runs offline, reads regular files through a no-follow boundary, and executes no repository code. It emits pin presence, undirected paired-file drift and host-path observations. Supplied pin observations must bind the exact declaration and captured target SHA; unequal SHAs alone never prove ancestry. Versions are as of the supplied scan timestamp. Missing/ambiguous targets and unresolved comparisons remain explicit. Local paths and source lines are not output. The caller owns collection, dependency installation, credential handling, freshness policy and reviewed artifact adoption; this command performs none of those operations. Artifact mode requires descriptor-based no-follow file access. The identity adapter is intended for this strict artifact path. Scanning omits VCS, dependency and build directories named .git, node_modules, __pycache__, .venv, venv, .mypy_cache, .pytest_cache, dist and build; coverage applies to the supported file kinds outside those directories. Unsupported host-path identities fail that repository's scan. Branch names and pin refs must satisfy the bounded Git-ref rules in the packaged schema.

Contributor test environment

From the repository root, install the declared test tools and visual extra, then run the packaging and visual-evidence tests with the project environment:

uv sync --project phase-loop-runtime --group test --extra visual --python 3.14 --locked
PYTHONPATH=phase-loop-runtime/src:phase-loop-runtime/tests phase-loop-runtime/.venv/bin/python -m pytest -q phase-loop-runtime/tests/test_outside_agent_contract_drift.py phase-loop-runtime/tests/test_visual_avatar_evidence_validator.py

The test group supplies pytest and package build/install tools, including pip; the visual extra supplies Pillow for image decoding. Both are opt-in. The native repository-wide interpreter guard includes the dagger subproject's Python 3.14 floor, which is separate from this runtime package's Python 3.12 minimum and CI's interpreter matrix. These commands verify the two selected files; they do not establish complete CI equivalence, behavior without Pillow, full-suite acceptance or production readiness.

Python verification environments

An explicit automation.python pin to a virtual environment preserves that environment for bare python/python3 commands and Python pip refresh. The interpreter still must satisfy the repository's requires-python constraints. The verification shim uses an exec launcher so interpreter symlinks retain their venv identity and installed packages.

During guarded discovery, version probes and verification, relative or empty PATH entries anchor to the invoking process's working directory. This deliberately changes empty-PATH discovery to search that directory. Missing PATH retains the C-library discovery default (with Python's default fallback); guarded execution uses that same default instead of its previous trailing-empty cwd search. Entry order and duplicates remain intact. Leading PATH= overrides consumed by the verification command parser anchor to the target repository, including overrides equal to the inherited value. Shell payloads and external env arguments are not parsed. Execution without a constraint or pin is unchanged.

Discovery and log metadata preserve the lexical interpreter selection. For execution, traversable directory components containing .. are resolved before version probes, launchers, pip refresh and guarded child PATH lookup. The final Python executable symlink is retained. This preserves the physical virtual environment reached through a symlink/.. path, even when direct Python startup would normalize that spelling to another environment. Recorded pip argv uses the execution spelling while the log retains the declared selection. Missing, looping, non-directory or inaccessible entries retain their original spelling; they cannot become new search directories through normalization. Absolute PATH entries without .. keep their exact strings, including repeated separators.

Post-aggregate commands reuse the absolute pinned launcher, while inherited PATH anchors to the later invoking process's directory and consumed overrides to the repository. They do not reconstruct historical PATH or revalidate every name in a reused shim. Without an explicit pin, distinct satisfying python and python3 aliases keep their environments; metadata and pip prefer python3, then python. Login profiles and explicit overrides can select another environment. Known nested-discovery and diagnostic-redaction test failures remain separate work under agent-harness#428; this repair does not establish full-suite success or completion of agent-harness#841's dependency repair.

Publication source audit

Normal FABPUB publication can distinguish an existing Python implementation such as credentials.py from a credential artifact (Consiliency/agent-harness#893). The path must be owned, regular Python source in both the frozen parent and staged tree, parse and compile without warnings, and contain a top-level function or class. New Python files still do not receive this exception.

Regular .ts files whose first path component is src, test or tests may qualify through a separate frozen source check. Both revisions of an existing file must be strict UTF-8 without NUL and parse without warnings, error or missing nodes (has_error must be false). A new file requires proven parent absence and membership in the frozen changed-path set. Each present revision must contain a named function, generator-function or class declaration with a body, optionally wrapped in one top-level export; imports, interfaces and type aliases may coexist. Other forms alone do not qualify. Declaration files (.d.ts), other roots, TSX/JavaScript and other languages, data-only files, nonregular entries, deletions, and .env*, .key, .pem, .p12 and .pfx path components stay refused.

The complete staged blob is scanned with pinned detect-secrets 1.5.0 built-in detectors. Repository configuration, inline suppressions, filter exemptions and online verification are not consulted. Findings and scanner failures block the exception without printing matched data. Parsing/compilation warnings reject the candidate rather than rendering source lines. No candidate code is executed. This heuristic scan is not proof that secrets are absent; source review remains required. For example, the quote-required TypeScript keyword rules can miss typed assignments or a keyword split from its literal across lines unless another detector fires. Encoded, obfuscated or separator-split values can also evade detection. New heuristic-named TypeScript files expose those detector limitations on the same basis as the existing Python exception; ordinary filenames already publish without this scan.

Metadata-only evidence (parent/tree and blob identifiers, content hash and policy version) is retained in the local publication checkpoint and checked again on recovery against the frozen Git objects. The existing FABPUB tree binding and transaction identity are unchanged. Legacy and prebuilt publication do not gain the source exception; there is no caller-controlled path allowlist.

The TypeScript parser pins are tree-sitter==0.26.0 and tree-sitter-typescript==0.23.2. Its flat JSON evidence records both versions and a null parent blob only for a proven addition. Python evidence is unchanged.

Fresh FABPUB publication refuses unstaged or untracked workspace changes with publication_workspace_invalid before creating a transaction or advancing the branch. Private plan, verification and handoff files under the .dev-skills directory must be Git-ignored: phase-loop init adds the /.dev-skills/ rule to .gitignore, or a local Git info/exclude rule can keep this setup out of committed source. The publisher does not add ignore rules or suppress workspace changes itself.

If a previous attempt already committed and then refused, repair the workspace and retry the same normal publication with its original plan and verification artifact. The exact committed transaction resumes without another commit. Conflicted transactions refuse before staging; switching to prebuilt mode does not repair a normal transaction. Authority and recovery checks still apply.

Roadmap validation

Lint a phase-plan roadmap spec (required headings, unique aliases, acyclic dependency DAG, IF-gate reconciliation, lane-count hints) via the always-installed runtime:

phase-loop validate-roadmap specs/phase-plans-v1.md
# module form — only when phase_loop_runtime is on the ACTIVE python's path (a pip
# install into your env); under `uv tool install` isolation use the console command:
python3 -m phase_loop_runtime.roadmap_lint specs/phase-plans-v1.md

Both wrap phase_loop_runtime.roadmap_lint (the single source of truth). Exit 0 = clean; non-zero prints each issue on stderr.

Local Gemini model preference

The shipped Gemini planning and review defaults use Gemini 4 Argon. To use that family for all local Gemini role defaults, add this to the environment that runs phase-loop:

export PHASE_LOOP_GEMINI_MODEL=gemini-4-argon

Use a registered canonical base model without an effort suffix. The runtime preserves action and seat effort: executor policy normalizes unsupported max requests to high, and the default review board keeps medium. Explicit task models, plan/roadmap model pins and configured board seats take precedence. Other providers, subscription authentication and sandbox admission retain their existing behavior. Invalid preferences fail without model fallback. Unsetting the variable restores the shipped role defaults, including regular/lite Flash routing. This setting does not change the standalone agy CLI's own local configuration.

Attended agy canary evidence

The six phase-loop agy-canary-* commands are an opt-in, attended evidence pipeline for the Gemini/agy review seat. They never add an Antigravity allow rule or use a permission-bypass flag. agy-canary-clean-settings is the sole writer for removing the historical command(pwd) rule; it requires a direct, mode-0700 child of /tmp, a quiescent settings tree, and an exclusive maintenance lock. The later probe, prepare, verify, and finalize steps fail closed until an attended agy 1.1.13 stream-json schema probe has selected a complete authority. That probe and every capture-enabled Gemini launch use /usr/bin/bwrap, a fresh /tmp, /run, and /proc, the fixed /run/phase-loop-review stage mapping, and a reducer-generated minimal HOME. A missing effective namespace, active customization source, unsupported stream schema, or absent direct bootstrap attestation blocks the canary rather than falling back to the operator HOME.

When PHASE_LOOP_AGY_CANARY_EVIDENCE_DIR is set, advisor-board --json consumes that variable before spawning any seat. The complete board JSON must be written through --agy-canary-private-board-name <basename> into that private directory; stdout contains only the redacted ledger binding. Capture requires exactly one resolved Gemini seat and retains the two staged review inputs using descriptor relative, no-follow writes. A normal board has no new output field or capture work.

Placement process boundary (agent-harness-placement)

agent-harness-placement --client agent-harness|agent-toolkit reserve|release|reap|version is the JSON process boundary for placement reservations (v13 PLACECLI). It speaks placement process protocol v1, which ships as src/phase_loop_runtime/contracts/placement/process-v1.schema.json, and reads one request on stdin. It writes one response line on stdout and exits 0, 10, 20 or 70.

--client alone selects the operator configuration under ~/.config/agent-harness/placement/, the certificate OU and the inventory. Live routes stay disabled: no production OpenShell backend is registered and E2B is off.

The full reference is docs/placement-process-cli.md. It covers:

  • messages and exit classes;
  • configuration and config_sha256;
  • provider refusal and the effective-egress digest;
  • barriers and caller-scoped reap;
  • local headroom and caps readiness;
  • the credential-proxy bridge.

Workflow skills bundle

The runtime also installs the harness-neutral workflow-skills bundle. The skill sources live in the phase-loop-skills/ directory of the monorepo, with unprefixed base directories and optional _overrides/<harness>/ overlays.

phase-loop install --harness codex --source <path-to>/phase-loop-skills --copy --dry-run
phase-loop install --harness codex --source <path-to>/phase-loop-skills --copy --apply

These commands install copies and replace existing managed skill directories. Back up customizations before applying. See Team onboarding for provider prerequisites, governance choices and the first-run check.

Path resolution is provided by phase_loop_runtime.skill_paths, which keeps handoffs repo-local, preserves harness-specific reflection roots, and documents the default install roots for Claude, Codex, Gemini, and OpenCode.

Zero-history FABPUB bootstrap

When FABPUB is active on a host that has no compatible legacy run-train broker ledger, create its persistent authority with a read-only probe followed by an explicit apply:

phase-loop fabpub-bootstrap --probe \
  --inventory /secure/operator/fabpub-probe.json \
  --worktree /path/to/repo \
  --legacy-root /path/to/declared/ledger/broker \
  --search-root /path/to/workspaces \
  --historical-evidence-root /path/to/standalone/receipt

phase-loop fabpub-bootstrap --apply \
  --inventory /secure/operator/fabpub-probe.json \
  --confirm-zero-history

The default authority is $XDG_STATE_HOME/phase-loop/fabpub/authority-v1, falling back to ~/.local/state/phase-loop/fabpub/authority-v1. Override it with PHASE_LOOP_FABPUB_AUTHORITY_ROOT or --authority-root during the probe. Receipts created by apply retain that custom authority location for later fresh-process validation; keep the environment override configured when onboarding repositories that were not named by the original probe. Apply is irreversible and refuses changed bytes, symlinks, live allocator state, held generation leases, or an authority owned by another bootstrap.

A failed run-train on a repository with no partition receipt leaves an empty <git-common-dir>/phase-loop-fabpub-broker-v1/run-train-writer.lock behind. The probe treats that file as runtime lock residue, not inventory state, only when it is a regular, 0-byte, singly linked file owned by the operator; the sealed inventory is identical with or without it. Anything else under that name (content, a directory, a socket or FIFO, a symlink, a hardlink, a foreign owner) is refused, as is a namespace root that is a symlink (dangling or not) or not a directory. The refusal names the entry and what it is. It is not runtime residue: inspect it, and remove it yourself only after confirming it is not yours, then re-run the probe. The runtime never deletes it. The probe classifies the namespace through one descriptor opened without following symlinks and refuses if the root is replaced while it is inspected. These checks keep an honest operator from mis-sealing; they are not a boundary against the operator's own account, since a same-uid actor who can rewrite the namespace can already forge broker state directly. Apply always holds every repository's writer lock, creating it if absent, from before its re-probe until it returns, and refuses while a run-train or another apply holds it. Never delete broker files to clear a refusal.

Before apply, stop every run-train on the host, not only those for the named repositories: the drain counts live run-train processes host-wide. A train that starts during apply waits behind the writer lock, is counted as live, and makes apply fail after DRAINING with WriterGenerationBlocked. To recover, stop the trains and re-run the same --apply --inventory <same file>; that resumes the sealed bootstrap and must not be preceded by a new probe. Until the resume completes, trains in those repositories obtain generation leases but no admission or provider effects.

Inventory completeness is bounded to the named worktrees, explicit and environment-declared legacy roots, historical-evidence roots, and hashed broker directories directly beneath .train-ledger directories under each --search-root. The confirmation attests that no compatible allocator exists outside that inspected universe. Standalone historical receipts are hashed and left in place; they are not silently adopted as current allocator authority.

Closeout ownership gate & operator break-glass

When a phase verifies green but the executor touched files outside the plan's declared owned-files globs, the graduated closeout gate classifies the beyond-ownership remainder (closeout_classifier.classify_unowned_path):

  • SAFE classes (docs, plans, handoffs, config_nonsource) auto-commit as a recorded soft exception.
  • UNSAFE classes (source, ci, secrets, lockfile) block with closeout_scope_violation.

The operator escape is phase-loop run --phase <P> --closeout-allow-unowned "<reason>" (also valid on resume/dry-run; reason required and non-empty; --phase required, bounding the override to a single phase). It folds the source/ci/lockfile remainder into the closeout commit as a recorded break_glass exception carrying the reason. secrets are never break-glassable — a .env*/*.pem/secrets/** path blocks regardless of the reason. See protocol.md → "Closeout Exceptions".

The closeout verdict is runner-authoritative: when the runner rejects a child's closeout, the persisted terminal-summary.json reflects the runner's blocking verdict (the child's self-reported complete/passed is not overlaid back), preventing a stale "complete" summary from reconcile-skipping the work on the next run.

The phase-loop-closeout-audit --repo . command grades ignored paths by producer. It accepts harness handoffs that carry the handoff contract, and a project's declared build outputs backed by a recorded producer run. Declare those outputs in a committed .phase-loop-generated-outputs.json; anything else still blocks. See docs/phase-loop/closeout-generated-outputs.md (agent-harness#1139).

Conformance library (one library, two roles)

phase_loop_runtime.conformance is the named, stable, importable surface for the deterministic .consiliency/ conformance evaluator. It is a re-export (not a re-implementation) of the same function the actor already runs, so an external CR-fence — in gp CI, a git-host pre-merge check, anywhere — can import and run the identical check:

from phase_loop_runtime.conformance import scan_consiliency_gates

verdict = scan_consiliency_gates("/path/to/repo")   # {"status": "passed" | "warn" | "blocked" | "skipped", "gates": {...}, ...}

The surface also exposes the pure cores (evaluate_git_discipline, self_heal_partition, evaluate_governance_scope) for consumers that already hold the injected facts.

Two roles, one library. This is meant to be mounted BOTH as the actor-side self-check (a pre-PR sanity pass the author runs locally) AND as the authoritative CR-fence (the real validator). The actor-side result is never authoritative — the fence always re-runs the check itself. Because it is the same function versioned with the same consiliency_contract dependency, the honest actor sees exactly the verdict the fence will; a stale or dishonest actor result simply does not matter.

Scope. The surface spans the shape + governance tier and the certificate / projection / outside-agent tiers it re-exports (see the module docstring for the authoritative tier list). Authority and provenance verification remain out of scope, delegated downstream.

consiliency-ingest --check-only

--check-only decouples "run the check" from "is this repo adopted". It is strictly read-only (never shapes; ignores --adopt). It makes the exit code verdict-significant so a pre-PR actor is never misled into reading a no-op — or a failing verify — as a pass:

Repo state mode exit
adopted, verify clean (or warn) verify 0
adopted, gate scan blocked verify 1
un-adopted (no .consiliency/manifest) not-adopted 3
usage error — 2

The plain (non---check-only) path is unchanged — it keeps the silent green skipped no-op on an un-adopted repo and its existing exit 0.

Metadata

Release files for phase-loop-runtime 0.7.34

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for phase-loop-runtime 0.7.34
File Size Uploaded Provenance Actions
phase_loop_runtime-0.7.34.tar.gz 6.7 MB With provenance Details for phase_loop_runtime-0.7.34.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for phase-loop-runtime 0.7.34
File Interpreter ABI Platform Actions
phase_loop_runtime-0.7.34-py3-none-any.whl Python 3 none any Details for phase_loop_runtime-0.7.34-py3-none-any.whl

Total release size: 10.5 MB

Release files / phase_loop_runtime-0.7.34.tar.gz

Download URL phase_loop_runtime-0.7.34.tar.gz
Size 6.7 MB
Tags Source
SHA-256 checksum
How to use checksums
f5a8f99103b716cb8583499178431b404e12f5b13b1490120fde6edef47929e9
BLAKE2b-256 checksum
How to use checksums
b081f1ca04fe9bb0be64bf7940a05399ba0d7df84cfdb696bc962e47a77ab52c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / phase_loop_runtime-0.7.34-py3-none-any.whl

Download URL phase_loop_runtime-0.7.34-py3-none-any.whl
Size 3.8 MB
Tags Python 3
SHA-256 checksum
How to use checksums
2ef70206c01929e8db1cf514e752abe391606a688fe7c1d0cd7302f3ecca49d0
BLAKE2b-256 checksum
How to use checksums
acedba5b8ad69241bbebfdb999ba0b488591d2253197902abe08638834a0db77
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for phase-loop-runtime 0.7.34

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for phase_loop_runtime-0.7.34.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.7.34 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page