richfrem/agent-plugins-skills / plugins/agent-agentic-os/.apm/skills/running-control-plane
running-control-plane
FlaggedCRITICAL INTAKE GATEWAY: use at the start of any non-trivial engineering task, feature, refactor, multi-file bugfix, work package or new idea, including requests to explore, brainstorm, build, fix or change something, before planning or code changes. Enforces read-only discovery, 1-3 structured questions with defaults, control-plane registration and the immutable four-pillar TASK_SPEC.md. Also runs the rest of the control plane: health ("run health check", "check os metrics", "system monitor", event bus, locks, memory, "is my signing identity ready" status check), transition simulation ("dry run transition", "simulate transition", "check edge X -> Y"), worktree selection, and gating on/off ("disable the control plane", "turn off the push guard", "stop gating my commits"). Not for project setup or key creation (use setting-up-agentic-os) or improving skills (use improving-skills-in-lab).
scripts/control_plane/adapters.py
View on GitHub"""
control_plane/adapters.py — Concrete Port Implementations (issue-524)
========================================================================
Purpose:
Concrete adapters implementing the port interfaces declared in control_plane/ports.py
against real infrastructure. Populated incrementally as agent_control.py's ControlPlane
responsibilities are extracted (docs/plans/issue-524-spec.md, Section 5). Step 3 added
FilesystemAdapter. Step 6 added CryptoAdapter. Step 7 added ModelCatalogAdapter. Step 5 was
revised after external post-implementation review (round 2) found the original
SqlitePersistenceAdapter only covered connection management and schema migration, leaving
all task/transition/receipt CRUD SQL still directly embedded in ControlPlane — contradicting
the plan's stated goal of a real persistence boundary. SqlitePersistenceAdapter now fully
implements PersistencePort: every CRUD operation ControlPlane needs has a concrete method
here, and ControlPlane composes this port instead of ever calling sqlite3 itself. This
revision also adds ClockAdapter (ClockPort was declared in Step 2 but never wired to
anything — flagged by the same review as dead architecture). issue-552 fixed
_rebuild_schema_transactional()'s broken atomicity guarantee (conn.executescript()
silently commits any open transaction) by adding _split_schema_sql_statements() and
executing SCHEMA_SQL as individual statements inside the real transaction; also deferred
_log_orphan_merge_conflicts()'s filesystem write until after COMMIT, and added
_check_no_orphaned_migration_tables() as ensure_schema()'s first operation.
Layer:
OS Kernel / Execution Control Plane Substrate — Adapters (hexagonal boundary)
Key Input Dependencies:
- Local filesystem (FilesystemAdapter, CryptoAdapter.sha256_file, ModelCatalogAdapter)
- SQLite database file (SqlitePersistenceAdapter)
- Wall clock (ClockAdapter)
Key Functions:
- FilesystemAdapter.append_text() — appends text to a file, no-op if the file doesn't exist
- FilesystemAdapter.read_text() — reads a file's full text content
- FilesystemAdapter.exists() — checks file existence
- ClockAdapter.current_time() / strftime() — real wall-clock time, real strftime formatting
- _split_schema_sql_statements() — issue-552: splits SCHEMA_SQL into individual statements
(preserving CREATE TRIGGER...BEGIN...END; bodies, filtering leading PRAGMAs) for atomic
statement-by-statement execution inside _rebuild_schema_transactional()'s transaction
- SqlitePersistenceAdapter — full PersistencePort implementation: connection management,
schema migration (self-healing, verbatim from the original init_db()/_schema_needs_rebuild()/
_rebuild_schema_transactional()/_copy_common_columns()/_merge_orphaned_tasks_old()), plus
every task/transition/receipt/review/verifier/log/worktree CRUD operation formerly issued
directly by ControlPlane. _check_no_orphaned_migration_tables() (issue-552) is
ensure_schema()'s first operation, failing loudly on a DB stuck mid-rebuild.
- CryptoAdapter.sha256_file() — SHA256 hex digest of a file, verbatim from the former
module-level _sha256_file()
- CryptoAdapter.sha256_hex() — SHA256 hex digest of a string (receipt token generation)
- ModelCatalogAdapter.load_catalog() — reads/parses a model-catalog JSON file, or None
- ModelCatalogAdapter.load_cheapest() — reads cheapest_models.json for a tool_key, or None
"""
import hashlib
import inspect
import json
import sqlite3
import warnings
import subprocess
import time
from pathlib import Path
from typing import Any, Dict, List, Optional
from control_plane.approver_policy import enforce_pipeline_approver, pipeline_context, record_gate_evidence, stamp_database_identity
from control_plane.ports import (
FilesystemPort,
CryptoPort,
ModelCatalogPort,
PersistencePort,
ClockPort,
TransitionRecord,
TransitionDecision,
InterviewAnswerRecord,
TransitionCommitRequest,
PhaseCapability,
PersistenceInvariantViolation,
)
from control_plane.snapshot import SnapshotError
from control_plane.ssh_signing import SigningError
from control_plane.transition_request import TransitionRequestError, consume_with_signature, preverify_signature
from control_plane.state_machine import ALLOWED_TRANSITIONS, CANONICAL_STATES
from control_plane.constants import (
REBUILD_RECOVERY_DOC,
STATE_INTAKE, STATE_DONE, STATE_WORKTREE_REVIEW, STATE_VERIFY_EXIT, STATE_APPROVED,
DECISION_TYPE_APPROVAL, DECISION_TYPES,
ACTOR_HUMAN, ACTOR_AGENT, ACTOR_SYSTEM,
COST_TIER_LOW, COST_TIERS,
CONFIRMATION_STATUS_PENDING, CONFIRMATION_STATUS_CONFIRMED,
GATE_MULTI_AGENT_REVIEW_SKIPPED, GATE_MULTI_AGENT_CODE_REVIEW_SKIPPED,
TASK_TYPE_GENERAL, TASK_TYPES,
WORKTREE_STATES,
QUESTION_ID_RETROSPECTIVE_DECISION,
CRITIC_VERDICTS,
PERSISTENCE_LOG_STATUSES,
RETROSPECTIVE_DECISION_OPT_IN, RETROSPECTIVE_DECISION_SKIP, RETROSPECTIVE_DECISIONS,
RETROSPECTIVE_COMPLETION_MODE_COMPLETED, RETROSPECTIVE_COMPLETION_MODE_SKIPPED,
RETROSPECTIVE_COMPLETION_MODES,
FOLLOW_UP_KIND_ISSUE, FOLLOW_UP_KINDS,
FOLLOW_UP_STATUS_PROPOSED, FOLLOW_UP_STATUS_CONFIRMED, FOLLOW_UP_STATUS_CREATED,
FOLLOW_UP_STATUSES,
DELEGATION_STATUSES,
DISALLOWED_MODEL_STATUSES, STRATEGY_FALLBACK_KEYS,
CLI_AGENT_CATALOG_DIR,
TOOL_CATALOG_ALIASES,
sql_in_list,
)
# NOTE: SCHEMA_MIGRATIONS below is an immutable historical record of DDL actually
# executed against real databases over time -- it deliberately keeps its own literal
# strings and must NEVER be rewritten to reference the shared constants above, even
# though some values overlap. Only SCHEMA_SQL (the fresh-create target schema) and the
# Python logic after SCHEMA_MIGRATIONS derive from control_plane/constants.py.
def _resolve_repo_root() -> Path:
"""Single shared resolver for the repository root: the repository the process is working
in (`git rev-parse --show-toplevel` from the current directory), falling back to the current
directory when git is unavailable or it is not inside a repository.
It deliberately does not look at where this file lives: APM installs the skill under a
project harness folder, or under a user-level folder shared by every repository, so the
file's location says nothing about which repository is being governed."""
try:
result = subprocess.run(
["git", "rev-parse", "--show-toplevel"],
capture_output=True, text=True, timeout=5,
)
if result.returncode == 0 and result.stdout.strip():
return Path(result.stdout.strip())
except (subprocess.SubprocessError, OSError):
pass
return Path.cwd()
class FilesystemAdapter(FilesystemPort):
"""Real-filesystem implementation of FilesystemPort. Mirrors the exact current behavior
of agent_control.py's _log_orphan_merge_conflicts(): silently does nothing if the target
file does not already exist (never creates it), matching the original guard
`if not map_debt_path.exists(): return`."""
def append_text(self, path: Path, content: str) -> None:
"""Appends `content` to the file at `path`. No-op if the file does not already exist —
preserves the original _log_orphan_merge_conflicts() behavior exactly."""
if not path.exists():
return
with open(path, "a", encoding="utf-8") as f:
f.write(content)
def read_text(self, path: Path) -> str:
"""Reads and returns the full text content of the file at `path`."""
return path.read_text(encoding="utf-8")
def exists(self, path: Path) -> bool:
"""Returns whether a file exists at `path`."""
return path.exists()
class ClockAdapter(ClockPort):
"""Real wall-clock implementation of ClockPort, backed by the stdlib `time` module."""
def current_time(self) -> float:
"""Returns the current time as a float (seconds since epoch)."""
return time.time()
def strftime(self, fmt: str) -> str:
"""Returns the current local time formatted per `fmt`."""
return time.strftime(fmt)
# auth-ciba-poc-transition-mechanics (2026-09-18, live multi-agent code review finding):
# destinations a recovery approval may never target directly, because at least one
# normal inbound edge to each of them carries real human authorization (a human_only
# classification and/or a trigger-enforced human_questions entry) that the recovery
# path -- by design a non-DAG bypass for legitimate operational recovery -- would
# otherwise defeat entirely. Confirmed live: an agent calling record_recovery_approval
# + apply_recovery_transition could reach VERIFY_EXIT directly from any state,
# recreating the exact IN_WORKTREE -> VERIFY_EXIT backdoor removed from the DAG.
# Recovery into these two states remains possible only through their normal gated
# edges (WORKTREE_REVIEW/MULTI_AGENT_CODE_REVIEW -> VERIFY_EXIT,
# AWAITING_APPROVAL -> APPROVED), never through this recovery side-channel.
RECOVERY_FORBIDDEN_DESTINATIONS = (STATE_VERIFY_EXIT, STATE_APPROVED, STATE_DONE)
_RECOVERY_FORBIDDEN_SQL_LIST = ", ".join(f"'{s}'" for s in RECOVERY_FORBIDDEN_DESTINATIONS)
# Factored out of SCHEMA_SQL so the identical trigger definition can also be applied
# as a migration (DROP + CREATE) for databases created before this fix, since
# `CREATE TRIGGER IF NOT EXISTS` is a silent no-op against an already-existing
# (and, before this fix, vulnerable) trigger of the same name.
ENFORCE_VALID_TRANSITION_TRIGGER_SQL = f"""
CREATE TRIGGER IF NOT EXISTS enforce_valid_transition
AFTER UPDATE ON tasks
WHEN NEW.state != OLD.state
AND (
NOT EXISTS (
SELECT 1 FROM transition_decisions recovery_td
WHERE recovery_td.task_id = OLD.task_id
AND recovery_td.source_occupancy_transition_id = (
SELECT MAX(current_td.transition_id)
FROM task_transitions current_td
WHERE current_td.task_id = OLD.task_id
)
AND recovery_td.from_state = OLD.state
AND recovery_td.to_state = NEW.state
AND recovery_td.to_state NOT IN ({_RECOVERY_FORBIDDEN_SQL_LIST})
AND recovery_td.decision_type = '{DECISION_TYPE_APPROVAL}'
AND recovery_td.actor = '{ACTOR_HUMAN}'
AND recovery_td.answer IS NOT NULL
AND trim(recovery_td.answer) != ''
AND recovery_td.consumed_at IS NULL
)
AND (
NOT EXISTS (
SELECT 1 FROM valid_transitions WHERE from_state = OLD.state AND to_state = NEW.state
)
OR EXISTS (
SELECT 1 FROM required_transition_questions rq
WHERE rq.from_state = OLD.state AND rq.to_state = NEW.state
AND NOT EXISTS (
SELECT 1 FROM transition_decisions td
WHERE td.task_id = OLD.task_id
AND td.from_state = OLD.state
AND td.to_state = NEW.state
AND td.question_id = rq.question_id
AND td.answer IS NOT NULL
AND trim(td.answer) != ''
AND td.actor = '{ACTOR_HUMAN}'
AND td.consumed_at IS NULL
)
)
)
OR (
-- Cryptographic-proof edges (APPROVED, VERIFY_EXIT, DONE): the ONLY authority is a transition_request
-- that a verified OpenSSH signature consumed for THIS edge and THIS occupancy. No decision row, actor
-- string or typed word can substitute; the recovery bypass above cannot reach these destinations.
EXISTS (
SELECT 1 FROM valid_transitions vt
WHERE vt.from_state = OLD.state AND vt.to_state = NEW.state AND vt.requires_proof = 1
)
AND NOT EXISTS (
SELECT 1 FROM transition_request tr
WHERE tr.task_id = OLD.task_id
AND tr.from_state = OLD.state
AND tr.to_state = NEW.state
AND tr.status = 'CONSUMED'
AND tr.occupancy_id = (SELECT MAX(x.transition_id) FROM task_transitions x WHERE x.task_id = OLD.task_id AND x.to_state = OLD.state)
)
)
)
BEGIN
INSERT INTO transition_violations (task_id, attempted_from_state, attempted_to_state)
VALUES (OLD.task_id, OLD.state, NEW.state);
UPDATE tasks SET state = OLD.state, updated_at = OLD.updated_at WHERE task_id = NEW.task_id;
END;
"""
SCHEMA_SQL = f"""
PRAGMA foreign_keys = ON;
PRAGMA journal_mode = WAL;
PRAGMA busy_timeout = 5000;
CREATE TABLE IF NOT EXISTS tasks (
task_id TEXT PRIMARY KEY,
title TEXT NOT NULL,
state TEXT NOT NULL CHECK (
state IN (
{sql_in_list(CANONICAL_STATES)}
)
),
task_type TEXT NOT NULL DEFAULT '{TASK_TYPE_GENERAL}' CHECK (task_type IN ({sql_in_list(TASK_TYPES)})),
runtime_tool TEXT NOT NULL,
worktree_path TEXT,
worktree_branch TEXT,
worktree_state TEXT CHECK (
worktree_state IS NULL OR worktree_state IN (
{sql_in_list(WORKTREE_STATES)}
)
),
spec_path TEXT,
model_tier TEXT CHECK (model_tier IS NULL OR model_tier IN ({sql_in_list(COST_TIERS)})),
model_id TEXT,
guidance_block_reason TEXT,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE IF NOT EXISTS task_transitions (
transition_id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT NOT NULL REFERENCES tasks(task_id) ON DELETE CASCADE,
from_state TEXT NOT NULL,
to_state TEXT NOT NULL,
actor TEXT NOT NULL,
reason TEXT,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE IF NOT EXISTS locked_verifier_baselines (
baseline_id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT NOT NULL REFERENCES tasks(task_id) ON DELETE CASCADE,
file_path TEXT NOT NULL,
expected_sha256 TEXT NOT NULL,
verified_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE IF NOT EXISTS critic_reviews (
review_id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT NOT NULL REFERENCES tasks(task_id) ON DELETE CASCADE,
iteration INTEGER NOT NULL CHECK(iteration >= 1),
model_used TEXT NOT NULL,
verdict TEXT NOT NULL CHECK (verdict IN ({sql_in_list(CRITIC_VERDICTS)})),
critique_findings TEXT,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE IF NOT EXISTS verification_receipts (
receipt_id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT NOT NULL REFERENCES tasks(task_id) ON DELETE CASCADE,
gate_name TEXT NOT NULL,
command_executed TEXT NOT NULL,
exit_code INTEGER NOT NULL,
receipt_token TEXT NOT NULL,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
actor TEXT,
provenance TEXT NOT NULL DEFAULT 'api',
invalidated_at TIMESTAMP,
invalidation_reason TEXT
);
CREATE TABLE IF NOT EXISTS receipt_audit (
audit_id INTEGER PRIMARY KEY AUTOINCREMENT,
receipt_id INTEGER NOT NULL,
task_id TEXT NOT NULL,
gate_name TEXT NOT NULL,
event TEXT NOT NULL CHECK (event IN ('created', 'invalidated')),
actor TEXT,
provenance TEXT,
reason TEXT,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE TRIGGER IF NOT EXISTS receipt_audit_no_update BEFORE UPDATE ON receipt_audit
BEGIN SELECT RAISE(ABORT, 'receipt_audit is append-only'); END;
CREATE TRIGGER IF NOT EXISTS receipt_audit_no_delete BEFORE DELETE ON receipt_audit
BEGIN SELECT RAISE(ABORT, 'receipt_audit is append-only'); END;
CREATE TABLE IF NOT EXISTS asymmetric_persistence_log (
log_id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT NOT NULL REFERENCES tasks(task_id) ON DELETE CASCADE,
destination TEXT NOT NULL,
status TEXT NOT NULL CHECK(status IN ({sql_in_list(PERSISTENCE_LOG_STATUSES)})),
details TEXT,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE IF NOT EXISTS transition_decisions (
decision_id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT NOT NULL REFERENCES tasks(task_id) ON DELETE CASCADE,
source_occupancy_transition_id INTEGER NOT NULL,
from_state TEXT NOT NULL,
to_state TEXT NOT NULL,
question_id TEXT NOT NULL,
answer TEXT NOT NULL,
decision_type TEXT NOT NULL CHECK(decision_type IN ({sql_in_list(DECISION_TYPES)})),
actor TEXT NOT NULL,
recorded_at REAL NOT NULL,
consumed_at REAL,
bound_transition_id INTEGER REFERENCES task_transitions(transition_id)
);
CREATE TABLE IF NOT EXISTS done_closeout_decisions (
closeout_decision_id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT NOT NULL REFERENCES tasks(task_id) ON DELETE CASCADE,
source_occupancy_transition_id INTEGER NOT NULL REFERENCES task_transitions(transition_id),
question_id TEXT NOT NULL,
answer TEXT NOT NULL,
actor TEXT NOT NULL CHECK(actor = '{ACTOR_HUMAN}'),
recorded_at REAL NOT NULL,
UNIQUE(task_id, source_occupancy_transition_id, question_id)
);
CREATE TABLE IF NOT EXISTS retrospective_entries (
retrospective_id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT NOT NULL UNIQUE REFERENCES tasks(task_id) ON DELETE CASCADE,
decision TEXT NOT NULL CHECK(decision IN ({sql_in_list(RETROSPECTIVE_DECISIONS)})),
completion_mode TEXT NOT NULL CHECK(completion_mode IN ({sql_in_list(RETROSPECTIVE_COMPLETION_MODES)})),
actor TEXT NOT NULL CHECK(actor IN ('{ACTOR_AGENT}', '{ACTOR_HUMAN}')),
outcome TEXT NOT NULL DEFAULT '',
strengths TEXT NOT NULL DEFAULT '',
friction TEXT NOT NULL DEFAULT '',
learning TEXT NOT NULL DEFAULT '',
improvement TEXT NOT NULL DEFAULT '',
follow_up TEXT NOT NULL DEFAULT '',
skip_reason TEXT NOT NULL DEFAULT '',
created_at REAL NOT NULL,
updated_at REAL NOT NULL
);
CREATE TABLE IF NOT EXISTS retrospective_follow_ups (
follow_up_id INTEGER PRIMARY KEY AUTOINCREMENT,
retrospective_id INTEGER NOT NULL REFERENCES retrospective_entries(retrospective_id) ON DELETE CASCADE,
kind TEXT NOT NULL CHECK(kind IN ({sql_in_list(FOLLOW_UP_KINDS)})),
description TEXT NOT NULL,
status TEXT NOT NULL CHECK(status IN ({sql_in_list(FOLLOW_UP_STATUSES)})),
duplicate_checked INTEGER NOT NULL DEFAULT 0 CHECK(duplicate_checked IN (0, 1)),
issue_url TEXT,
issue_number TEXT,
created_at REAL NOT NULL,
updated_at REAL NOT NULL
);
CREATE TABLE IF NOT EXISTS delegation_contracts (
contract_id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT NOT NULL REFERENCES tasks(task_id) ON DELETE CASCADE,
objective TEXT NOT NULL,
scope_json TEXT NOT NULL,
authority_json TEXT NOT NULL,
tool_limits_json TEXT NOT NULL,
budget_json TEXT NOT NULL,
artifacts_json TEXT NOT NULL,
verifier_json TEXT NOT NULL,
escalation_json TEXT NOT NULL,
fallback_candidates_json TEXT NOT NULL,
backend TEXT NOT NULL,
model_id TEXT NOT NULL,
cost_tier TEXT NOT NULL CHECK(cost_tier IN ({sql_in_list(COST_TIERS)})),
capability_class TEXT NOT NULL,
status TEXT NOT NULL CHECK(status IN ({sql_in_list(DELEGATION_STATUSES)})),
approved_by TEXT,
created_at REAL NOT NULL,
updated_at REAL NOT NULL
);
CREATE TABLE IF NOT EXISTS delegation_receipts (
receipt_id INTEGER PRIMARY KEY AUTOINCREMENT,
contract_id INTEGER NOT NULL REFERENCES delegation_contracts(contract_id) ON DELETE CASCADE,
task_id TEXT NOT NULL REFERENCES tasks(task_id) ON DELETE CASCADE,
backend TEXT NOT NULL,
model_id TEXT NOT NULL,
cost_tier TEXT NOT NULL CHECK(cost_tier IN ({sql_in_list(COST_TIERS)})),
capability_class TEXT NOT NULL,
write_capable INTEGER NOT NULL DEFAULT 0 CHECK(write_capable IN (0, 1)),
written_paths_json TEXT NOT NULL DEFAULT '[]',
backend_available INTEGER NOT NULL DEFAULT 1 CHECK(backend_available IN (0, 1)),
created_at REAL NOT NULL
);
CREATE TABLE IF NOT EXISTS delegation_verifier_receipts (
verifier_receipt_id INTEGER PRIMARY KEY AUTOINCREMENT,
contract_id INTEGER NOT NULL REFERENCES delegation_contracts(contract_id) ON DELETE CASCADE,
command TEXT NOT NULL,
exit_code INTEGER NOT NULL,
created_at REAL NOT NULL
);
CREATE TABLE IF NOT EXISTS premium_consents (
consent_id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT NOT NULL REFERENCES tasks(task_id) ON DELETE CASCADE,
stage TEXT NOT NULL,
round_id TEXT NOT NULL,
model_id TEXT NOT NULL,
actor TEXT NOT NULL CHECK(actor = '{ACTOR_HUMAN}'),
consented_at REAL NOT NULL,
UNIQUE(task_id, stage, round_id, model_id)
);
CREATE TABLE IF NOT EXISTS source_assisted_answer_candidates (
candidate_id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT NOT NULL REFERENCES tasks(task_id) ON DELETE CASCADE,
stage TEXT NOT NULL,
round_id TEXT NOT NULL,
question_id TEXT NOT NULL,
answer TEXT NOT NULL,
source_path TEXT NOT NULL,
source_authorized INTEGER NOT NULL CHECK(source_authorized IN (0, 1)),
confirmation_status TEXT NOT NULL DEFAULT 'pending'
CHECK(confirmation_status IN ('{CONFIRMATION_STATUS_PENDING}', '{CONFIRMATION_STATUS_CONFIRMED}')),
confirmed_by TEXT,
confirmed_at REAL,
created_at REAL NOT NULL,
CHECK(
(confirmation_status = '{CONFIRMATION_STATUS_PENDING}' AND confirmed_by IS NULL AND confirmed_at IS NULL)
OR (confirmation_status = '{CONFIRMATION_STATUS_CONFIRMED}' AND confirmed_by = '{ACTOR_HUMAN}' AND confirmed_at IS NOT NULL)
)
);
CREATE TABLE IF NOT EXISTS interview_plan_outlines (
task_id TEXT PRIMARY KEY REFERENCES tasks(task_id) ON DELETE CASCADE,
outline_json TEXT NOT NULL,
artifact_path TEXT NOT NULL,
revision INTEGER NOT NULL CHECK(revision >= 1),
created_at REAL NOT NULL,
updated_at REAL NOT NULL
);
CREATE TABLE IF NOT EXISTS schema_version (
version INTEGER NOT NULL
);
CREATE TABLE IF NOT EXISTS valid_transitions (
from_state TEXT,
to_state TEXT NOT NULL,
authorized_actor TEXT NOT NULL DEFAULT 'agent_or_human',
requires_proof INTEGER NOT NULL DEFAULT 0,
PRIMARY KEY (from_state, to_state)
);
CREATE TABLE IF NOT EXISTS transition_request (
request_id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT NOT NULL REFERENCES tasks(task_id) ON DELETE CASCADE,
from_state TEXT NOT NULL,
to_state TEXT NOT NULL,
occupancy_id INTEGER NOT NULL,
nonce TEXT NOT NULL UNIQUE,
expiration REAL NOT NULL,
revision_hash TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'PENDING' CHECK(status IN ('PENDING', 'CONSUMED', 'DENIED', 'EXPIRED')),
jti TEXT,
consumed_at REAL,
created_at REAL NOT NULL,
challenge_version TEXT,
content_snapshot TEXT
);
CREATE INDEX IF NOT EXISTS idx_transition_request_task ON transition_request(task_id);
CREATE TABLE IF NOT EXISTS required_transition_questions (
from_state TEXT NOT NULL,
to_state TEXT NOT NULL,
question_id TEXT NOT NULL,
PRIMARY KEY (from_state, to_state, question_id)
);
CREATE TABLE IF NOT EXISTS transition_violations (
violation_id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT NOT NULL,
attempted_from_state TEXT,
attempted_to_state TEXT NOT NULL,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
actor TEXT,
reason TEXT,
detail TEXT,
kind TEXT NOT NULL DEFAULT 'ILLEGAL_TRANSITION'
);
CREATE INDEX IF NOT EXISTS idx_tasks_state ON tasks(state);
CREATE INDEX IF NOT EXISTS idx_transitions_task ON task_transitions(task_id);
CREATE INDEX IF NOT EXISTS idx_decisions_lookup ON transition_decisions(task_id, source_occupancy_transition_id);
CREATE INDEX IF NOT EXISTS idx_done_closeout_decisions_lookup
ON done_closeout_decisions(task_id, source_occupancy_transition_id);
CREATE INDEX IF NOT EXISTS idx_retrospective_follow_ups_entry ON retrospective_follow_ups(retrospective_id);
CREATE INDEX IF NOT EXISTS idx_source_answer_candidates_scope
ON source_assisted_answer_candidates(task_id, stage, round_id, confirmation_status);
CREATE INDEX IF NOT EXISTS idx_interview_plan_outlines_artifact
ON interview_plan_outlines(artifact_path);
-- issue-523 & pipeline-guard: DB-level backstop enforcing legal state transitions and
-- required human decisions on state transitions. Checks both adjacency-legality (valid_transitions)
-- and human question requirements (required_transition_questions -> transition_decisions with actor='human').
-- Reverts silently (no SQL error), logs to transition_violations. Both state and updated_at are restored.
{ENFORCE_VALID_TRANSITION_TRIGGER_SQL}
-- issue-523: closes the cheaper INSERT/DELETE+INSERT bypass identified by external security
-- review (finding #5) — deletes an illegally-seeded initial-state row. Revised from an
-- original coerce-to-INTAKE design: coercing via a corrective UPDATE fired
-- enforce_valid_transition (e.g. DONE -> INTAKE isn't a legal edge), which reverted the
-- coercion right back, silently defeating the fix. Delete avoids the UPDATE trigger
-- entirely. This does NOT reverse the UPDATE trigger's own coerce-not-delete decision — a
-- freshly-inserted illegal row has no accumulated transitions/receipts/decisions to protect,
-- unlike an existing task record (see spec guardrail table).
CREATE TRIGGER IF NOT EXISTS enforce_valid_initial_state
AFTER INSERT ON tasks
WHEN NOT EXISTS (
SELECT 1 FROM valid_transitions WHERE from_state IS NULL AND to_state = NEW.state
)
BEGIN
INSERT INTO transition_violations (task_id, attempted_from_state, attempted_to_state)
VALUES (NEW.task_id, NULL, NEW.state);
DELETE FROM tasks WHERE task_id = NEW.task_id;
END;
"""
CURRENT_SCHEMA_VERSION = 14
# issue-523: the only state ControlPlane.create_task() ever seeds a new task at. Not derived
# from TransitionRegistry (which only declares state-to-state edges among existing states, not
# initial states) — this is the closest available source of truth for the INSERT-side trigger.
LEGAL_INITIAL_STATES = [STATE_INTAKE]
CHILD_TABLES = [
"task_transitions",
"locked_verifier_baselines",
"critic_reviews",
"verification_receipts",
"asymmetric_persistence_log",
"transition_decisions",
"done_closeout_decisions",
"retrospective_entries",
"retrospective_follow_ups",
"delegation_contracts",
"delegation_receipts",
"delegation_verifier_receipts",
"premium_consents",
"source_assisted_answer_candidates",
"interview_plan_outlines",
"transition_request",
]
ALL_REBUILD_TABLES = ["tasks"] + CHILD_TABLES
SCHEMA_MIGRATIONS = [
# Migration: persist the canonical interview plan outline and its Markdown projection (v10)
"""CREATE TABLE IF NOT EXISTS interview_plan_outlines (
task_id TEXT PRIMARY KEY REFERENCES tasks(task_id) ON DELETE CASCADE,
outline_json TEXT NOT NULL,
artifact_path TEXT NOT NULL,
revision INTEGER NOT NULL CHECK(revision >= 1),
created_at REAL NOT NULL,
updated_at REAL NOT NULL
);""",
"CREATE INDEX IF NOT EXISTS idx_interview_plan_outlines_artifact ON interview_plan_outlines(artifact_path);",
"""CREATE TABLE IF NOT EXISTS done_closeout_decisions (
closeout_decision_id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT NOT NULL REFERENCES tasks(task_id) ON DELETE CASCADE,
source_occupancy_transition_id INTEGER NOT NULL REFERENCES task_transitions(transition_id),
question_id TEXT NOT NULL,
answer TEXT NOT NULL,
actor TEXT NOT NULL CHECK(actor = 'human'),
recorded_at REAL NOT NULL,
UNIQUE(task_id, source_occupancy_transition_id, question_id)
);""",
"CREATE INDEX IF NOT EXISTS idx_done_closeout_decisions_lookup ON done_closeout_decisions(task_id, source_occupancy_transition_id);",
# Migration: add task_type column if not present (for existing DBs)
"ALTER TABLE tasks ADD COLUMN task_type TEXT NOT NULL DEFAULT 'GENERAL' CHECK (task_type IN ('GENERAL', 'EVOLUTION'));",
# Migration: add transition_decisions table if not present (v4)
"""CREATE TABLE IF NOT EXISTS transition_decisions (
decision_id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT NOT NULL REFERENCES tasks(task_id) ON DELETE CASCADE,
source_occupancy_transition_id INTEGER NOT NULL,
from_state TEXT NOT NULL,
to_state TEXT NOT NULL,
question_id TEXT NOT NULL,
answer TEXT NOT NULL,
decision_type TEXT NOT NULL CHECK(decision_type IN ('ANSWER', 'APPROVAL', 'REJECTION', 'SKIP', 'CONFIRMATION', 'RESET')),
actor TEXT NOT NULL,
recorded_at REAL NOT NULL,
consumed_at REAL,
bound_transition_id INTEGER REFERENCES task_transitions(transition_id)
);""",
"CREATE INDEX IF NOT EXISTS idx_decisions_lookup ON transition_decisions(task_id, source_occupancy_transition_id);",
# Migration: add valid_transitions/transition_violations tables + enforcement triggers (v5)
"""CREATE TABLE IF NOT EXISTS valid_transitions (
from_state TEXT,
to_state TEXT NOT NULL,
PRIMARY KEY (from_state, to_state)
);""",
"""CREATE TABLE IF NOT EXISTS transition_violations (
violation_id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT NOT NULL,
attempted_from_state TEXT,
attempted_to_state TEXT NOT NULL,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);""",
"""CREATE TRIGGER IF NOT EXISTS enforce_valid_transition
AFTER UPDATE ON tasks
WHEN NEW.state != OLD.state
AND NOT EXISTS (
SELECT 1 FROM valid_transitions WHERE from_state = OLD.state AND to_state = NEW.state
)
BEGIN
INSERT INTO transition_violations (task_id, attempted_from_state, attempted_to_state)
VALUES (OLD.task_id, OLD.state, NEW.state);
UPDATE tasks SET state = OLD.state, updated_at = OLD.updated_at WHERE task_id = NEW.task_id;
END;""",
"""CREATE TRIGGER IF NOT EXISTS enforce_valid_initial_state
AFTER INSERT ON tasks
WHEN NOT EXISTS (
SELECT 1 FROM valid_transitions WHERE from_state IS NULL AND to_state = NEW.state
)
BEGIN
INSERT INTO transition_violations (task_id, attempted_from_state, attempted_to_state)
VALUES (NEW.task_id, NULL, NEW.state);
DELETE FROM tasks WHERE task_id = NEW.task_id;
END;""",
# Migration: add authorized_actor column to valid_transitions (auth-ciba-poc-transition-mechanics, issues #621/#626/#634)
"ALTER TABLE valid_transitions ADD COLUMN authorized_actor TEXT NOT NULL DEFAULT 'agent_or_human';",
# Migration: harden enforce_valid_transition's recovery bypass against forbidden
# destinations (auth-ciba-poc-transition-mechanics, 2026-09-18 review finding).
# CREATE TRIGGER IF NOT EXISTS is a no-op against an already-existing trigger, so
# a database created before this fix must have its stale trigger explicitly
# dropped before the hardened definition (same ENFORCE_VALID_TRANSITION_TRIGGER_SQL
# embedded in SCHEMA_SQL, applied here for pre-existing databases) is recreated.
"DROP TRIGGER IF EXISTS enforce_valid_transition;",
ENFORCE_VALID_TRANSITION_TRIGGER_SQL,
# Migration: content-bound approvals (auth-ciba-increment-b T2, issue #639). Nullable
# so existing rows and Increment A callers are untouched; ensure_schema() ignores
# "duplicate column" on a database that already has them.
"ALTER TABLE transition_request ADD COLUMN challenge_version TEXT;",
"ALTER TABLE transition_request ADD COLUMN content_snapshot TEXT;",
# Migration: receipt provenance and revocation (auth-ciba-increment-b T15, issue #639). receipt_audit has
# no FK so it survives the deletion of receipts on occupancy exit; its triggers abort UPDATE/DELETE. The
# append-only receipt_audit table and its triggers are created by SCHEMA_SQL (IF NOT EXISTS).
"ALTER TABLE verification_receipts ADD COLUMN actor TEXT;",
"ALTER TABLE verification_receipts ADD COLUMN provenance TEXT NOT NULL DEFAULT 'api';",
"ALTER TABLE verification_receipts ADD COLUMN invalidated_at TIMESTAMP;",
"ALTER TABLE verification_receipts ADD COLUMN invalidation_reason TEXT;",
# Migration: autonomous rejection audit context (auth-ciba-increment-b U2, issue #639).
"ALTER TABLE transition_violations ADD COLUMN actor TEXT;",
"ALTER TABLE transition_violations ADD COLUMN reason TEXT;",
"ALTER TABLE transition_violations ADD COLUMN detail TEXT;",
# Migration: classify violation rows (round-4 finding N1). Rows written by the enforce_valid_transition
# trigger keep the default 'ILLEGAL_TRANSITION' and block commit validation; the autonomous audit
# writes 'REJECTED_ATTEMPT' rows, which are kept for history but do not block.
"ALTER TABLE transition_violations ADD COLUMN kind TEXT NOT NULL DEFAULT 'ILLEGAL_TRANSITION';",
# Migration: cryptographic-proof edges (auth-ciba-increment-b, human decision 2026-09-20). valid_transitions gains
# requires_proof; the trigger is rebuilt so APPROVED / VERIFY_EXIT / DONE need a CONSUMED transition_request
# (a verified signature record), not an actor string or a typed word.
"ALTER TABLE valid_transitions ADD COLUMN requires_proof INTEGER NOT NULL DEFAULT 0;",
"DROP TRIGGER IF EXISTS enforce_valid_transition;",
ENFORCE_VALID_TRANSITION_TRIGGER_SQL,
]
# Rejections of a commit that must leave a transition_violations audit row: the database trigger's
# invariant violation plus Gate 1 signature / request / snapshot failures (bad signature, replay, expiry,
# changed content). Kept as a tuple so the two commit-path wrappers agree.
_AUDITED_REJECTIONS = (PersistenceInvariantViolation, SigningError, TransitionRequestError, SnapshotError)
def _expire_pending_requests(conn: sqlite3.Connection, task_id: str) -> None:
"""A committed transition changes the task's occupancy, so any still-PENDING
transition_request for it is stale: expire it (defense in depth; consume_with_signature
also re-checks the live occupancy inside the commit transaction)."""
conn.execute(
"UPDATE transition_request SET status = 'EXPIRED' WHERE task_id = ? AND status = 'PENDING'",
(task_id,),
)
def _split_schema_sql_statements(sql: str) -> List[str]:
"""issue-552: splits SCHEMA_SQL into individual statements via sqlite3.complete_statement(),
which correctly keeps the two CREATE TRIGGER ... BEGIN ... END; blocks intact despite their
embedded semicolons. Filters out all PRAGMA statements wherever they occur (in practice, the
3 leading ones — foreign_keys, journal_mode, busy_timeout) — these must not run as individual
conn.execute() calls inside
_rebuild_schema_transactional()'s transaction: journal_mode is a documented no-op once a
transaction is open, and foreign_keys must stay OFF for the transaction's full duration
(both are already set correctly on the connection before that method runs)."""
statements: List[str] = []
buffer = ""
for line in sql.splitlines(keepends=True):
buffer += line
if sqlite3.complete_statement(buffer):
stmt = buffer.strip()
if stmt and not stmt.upper().startswith("PRAGMA"):
statements.append(stmt)
buffer = ""
leftover = buffer.strip()
if leftover and not leftover.upper().startswith("PRAGMA"):
statements.append(leftover)
return statements
class SqlitePersistenceAdapter(PersistencePort):
"""SQLite-backed implementation of PersistencePort — connection management, schema
migration, and every task/transition/receipt/review/verifier/log/worktree CRUD
operation ControlPlane needs. Revised after external post-implementation review found
the original version only covered connection/migration, leaving CRUD SQL embedded in
ControlPlane — this version closes that gap: ControlPlane never calls sqlite3 directly."""
def __init__(self, db_path: Optional[Path], fs_adapter: FilesystemPort,
clock_adapter: Optional[ClockPort] = None,
crypto_adapter: Optional[CryptoPort] = None):
self.db_path = db_path if db_path is not None else self._discover_shared_db_path()
self.db_path.parent.mkdir(parents=True, exist_ok=True)
self._fs = fs_adapter
self._clock = clock_adapter if clock_adapter is not None else ClockAdapter()
self._crypto = crypto_adapter if crypto_adapter is not None else CryptoAdapter()
def _discover_shared_db_path(self) -> Path:
"""Resolves context/control_plane.db anchored at the repo root shared across
ALL git worktrees of the same repo — via `git rev-parse --git-common-dir`,
which (unlike a manual walk-up for the nearest `.git`) returns the same
physical .git directory whether invoked from the main checkout or any
worktree, so they all read/write one control plane instead of each worktree
getting its own disconnected DB."""
curr = Path(__file__).resolve().parent
for p in [curr] + list(curr.parents):
if p.name == ".agents":
return p.parent / "context" / "control_plane.db"
try:
result = subprocess.run(
["git", "rev-parse", "--git-common-dir"],
cwd=str(curr), capture_output=True, text=True, timeout=5
)
if result.returncode == 0:
common_dir = Path(result.stdout.strip())
if not common_dir.is_absolute():
common_dir = (curr / common_dir).resolve()
return common_dir.parent / "context" / "control_plane.db"
except (subprocess.SubprocessError, OSError):
pass
for p in [curr] + list(curr.parents):
if (p / "context").exists() and not (p / "skills").exists():
return p / "context" / "control_plane.db"
return Path.cwd() / "context" / "control_plane.db"
def get_connection(self) -> sqlite3.Connection:
"""Returns a configured sqlite3 connection with WAL mode and foreign keys."""
conn = sqlite3.connect(str(self.db_path), timeout=10.0)
conn.row_factory = sqlite3.Row
conn.execute("PRAGMA foreign_keys = ON;")
conn.execute("PRAGMA busy_timeout = 5000;")
return conn
def _check_no_orphaned_migration_tables(self, conn: sqlite3.Connection) -> None:
"""issue-552: raises RuntimeError if any `_<table>_migrating` orphan table exists —
evidence of a previously-interrupted `_rebuild_schema_transactional()` run (from before
this issue's atomicity fix, or from a process killed/crashed mid-rebuild). Called as the
literal first operation in ensure_schema(), before any DDL touches the connection, so a
corrupted DB fails loudly and immediately with an actionable message instead of the
cryptic `FOREIGN KEY constraint failed` a retried rebuild attempt previously surfaced."""
orphans = [
table for table in ALL_REBUILD_TABLES
if conn.execute(
"SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=?",
(f"_{table}_migrating",),
).fetchone()[0]
]
if orphans:
orphan_names = ", ".join(f"_{t}_migrating" for t in orphans)
raise RuntimeError(
f"control_plane.db has orphaned migration tables from an interrupted schema "
f"rebuild: {orphan_names}. Do not call ensure_schema() again until this is "
f"resolved manually — see {REBUILD_RECOVERY_DOC} for the recovery procedure."
)
def ensure_schema(self) -> None:
"""Initializes SQLite tables and WAL mode. Self-heals FK-corrupted or legacy schemas."""
conn = self.get_connection()
try:
self._check_no_orphaned_migration_tables(conn)
# Record once, inside the database itself, whether it is a real-work or simulation database
stamp_database_identity(conn, self.db_path)
conn.commit()
if self._schema_is_current(conn):
return # read-only fast path: no DDL, no YAML parse, no write lock
conn.execute("PRAGMA journal_mode = WAL;")
conn.executescript(SCHEMA_SQL)
# Apply idempotent migrations for existing databases
for migration in SCHEMA_MIGRATIONS:
try:
conn.execute(migration)
conn.commit()
except sqlite3.OperationalError as e:
if "duplicate column" not in str(e).lower():
raise
# Column already exists — expected on a previously-migrated DB, ignore.
if self._schema_needs_rebuild(conn):
self._rebuild_schema_transactional(conn)
else:
conn.execute(
"INSERT INTO schema_version (version) SELECT ? WHERE NOT EXISTS (SELECT 1 FROM schema_version)",
(CURRENT_SCHEMA_VERSION,)
)
conn.commit()
self._sync_valid_transitions(conn)
finally:
conn.close()
def _sync_valid_transitions(self, conn: sqlite3.Connection) -> None:
"""issue-523: resyncs valid_transitions from TransitionRegistry.get_all_edges() plus
LEGAL_INITIAL_STATES (as from_state IS NULL rows) on every ensure_schema() call —
self-maintaining, zero manual migration step per DAG change (spec guardrail table).
Uses parameterized INSERTs, not string-formatted SQL (finding #1).
auth-ciba-poc-transition-mechanics (T1): also populates authorized_actor per edge,
derived from TransitionRegistry/TransitionTemplate.authorized_actor (itself derived
from each edge's approval block, not a hand-maintained parallel field). Initial-state
rows (from_state IS NULL) are not edges with an approval block and default to
'agent_or_human', matching the column's schema default."""
from control_plane.registry import TransitionRegistry
registry = TransitionRegistry.load_default()
edges_with_actor = registry.get_all_edges_with_proof()
conn.execute("BEGIN IMMEDIATE;")
try:
conn.execute("DELETE FROM valid_transitions;")
conn.executemany(
"INSERT INTO valid_transitions (from_state, to_state, authorized_actor, requires_proof) VALUES (?, ?, ?, ?)",
list(edges_with_actor) + [(None, s, "agent_or_human", 0) for s in LEGAL_INITIAL_STATES]
)
conn.execute("""
CREATE TABLE IF NOT EXISTS required_transition_questions (
from_state TEXT NOT NULL,
to_state TEXT NOT NULL,
question_id TEXT NOT NULL,
PRIMARY KEY (from_state, to_state, question_id)
);
""")
conn.execute("DELETE FROM required_transition_questions;")
req_q = []
for (from_s, to_s), tmpl in registry._templates_by_edge.items():
for question_id in (tmpl.stage_question_ids or []):
req_q.append((from_s, to_s, question_id))
for q in tmpl.human_questions:
if q.get("asked_when"):
continue # conditional (review-selection internal runtime/model/effort): enforced by review_selection.py
req_q.append((from_s, to_s, q["question_id"]))
if tmpl.approval.get("required") and tmpl.approval.get("approver_role", "human") == "human":
req_q.append((from_s, to_s, f"approval_{tmpl.transition_id}"))
if req_q:
conn.executemany(
"INSERT INTO required_transition_questions (from_state, to_state, question_id) VALUES (?, ?, ?)",
req_q
)
conn.execute(
"CREATE TABLE IF NOT EXISTS registry_sync_state ("
"id INTEGER PRIMARY KEY CHECK (id = 1), inputs_fingerprint TEXT NOT NULL, tables_digest TEXT NOT NULL);"
)
conn.execute(
"INSERT OR REPLACE INTO registry_sync_state (id, inputs_fingerprint, tables_digest) VALUES (1, ?, ?)",
(self._sync_inputs_fingerprint(), self._derived_state_digest(conn)),
)
conn.execute("COMMIT;")
except Exception:
conn.execute("ROLLBACK;")
raise
@staticmethod
def _sync_inputs_fingerprint() -> str:
"""Everything the schema and registry-derived tables are a pure function of: the schema version,
the DDL and migration text, the legal initial states, the YAML bytes, and the registry code that
interprets them. A change to any input invalidates the fast path and forces a full resync.
Reading and hashing files is cheap; only the YAML *parse* was expensive."""
from control_plane.registry import TransitionRegistry
h = hashlib.sha256()
for part in (str(CURRENT_SCHEMA_VERSION), SCHEMA_SQL, "\n".join(SCHEMA_MIGRATIONS), repr(sorted(LEGAL_INITIAL_STATES)),
TransitionRegistry.default_source_digest()):
h.update(part.encode("utf-8"))
h.update(b"\x00")
h.update((Path(__file__).resolve().parent / "registry.py").read_bytes())
return h.hexdigest()
@staticmethod
def _derived_state_digest(conn: sqlite3.Connection) -> str:
"""Digest of the registry-derived rows plus the names of the enforcement triggers, so drift
(deleted/edited rows, a dropped trigger) still self-heals on the next ensure_schema() exactly as the
old resync-on-every-call did, without paying for a write transaction when nothing drifted."""
h = hashlib.sha256()
for sql in (
"SELECT from_state, to_state, authorized_actor, requires_proof FROM valid_transitions ORDER BY 1, 2, 3, 4",
"SELECT from_state, to_state, question_id FROM required_transition_questions ORDER BY 1, 2, 3",
"SELECT name FROM sqlite_master WHERE type = 'trigger' ORDER BY name",
):
for row in conn.execute(sql).fetchall():
h.update(repr(tuple(row)).encode("utf-8"))
h.update(b"\x00")
return h.hexdigest()
def _schema_is_current(self, conn: sqlite3.Connection) -> bool:
"""True when the database provably matches what a full ensure_schema() would produce: schema
version current, sync inputs unchanged since the last sync, and the derived tables/triggers
undrifted. Strictly read-only; any error (fresh DB, missing sync table) means 'not current'."""
try:
version_row = conn.execute("SELECT version FROM schema_version").fetchone()
if not version_row or version_row[0] != CURRENT_SCHEMA_VERSION:
return False
stored = conn.execute("SELECT inputs_fingerprint, tables_digest FROM registry_sync_state WHERE id = 1").fetchone()
if stored is None or stored[0] != self._sync_inputs_fingerprint():
return False
return stored[1] == self._derived_state_digest(conn)
except sqlite3.OperationalError:
return False
def _schema_needs_rebuild(self, conn: sqlite3.Connection) -> bool:
"""Detects a stale schema_version, a legacy tasks schema, or FK-corrupted/orphaned
migration artifacts. schema_version is the primary migration trigger; the DDL-sniff
and corruption checks below are defensive fallbacks for pre-schema_version databases
and self-healing already-corrupted ones, not the source of truth for version bumps."""
version_row = conn.execute("SELECT version FROM schema_version").fetchone()
if version_row and version_row[0] < CURRENT_SCHEMA_VERSION:
return True
row = conn.execute("SELECT sql FROM sqlite_master WHERE type='table' AND name='tasks'").fetchone()
if row and STATE_WORKTREE_REVIEW not in (row[0] or ""):
return True
orphan = conn.execute(
"SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name='_tasks_old'"
).fetchone()[0]
if orphan:
return True
for table in CHILD_TABLES:
child_row = conn.execute(
"SELECT sql FROM sqlite_master WHERE type='table' AND name=?", (table,)
).fetchone()
if child_row and child_row[0] and ("_tasks_old" in child_row[0] or "_migrating" in child_row[0]):
return True
return False
def _copy_common_columns(self, conn: sqlite3.Connection, source_table: str, dest_table: str):
"""Copies rows between tables via the intersection of their columns."""
source_cols = [r[1] for r in conn.execute(f'PRAGMA table_info("{source_table}");').fetchall()]
dest_cols = [r[1] for r in conn.execute(f'PRAGMA table_info("{dest_table}");').fetchall()]
common_cols = [c for c in source_cols if c in dest_cols]
cols_str = ", ".join(f'"{c}"' for c in common_cols)
conn.execute(f'INSERT INTO "{dest_table}" ({cols_str}) SELECT {cols_str} FROM "{source_table}";')
def _merge_orphaned_tasks_old(self, conn: sqlite3.Connection) -> List[str]:
"""Merges a dangling `_tasks_old` (from a previously-interrupted migration) into the
fresh `tasks` table. Returns any conflicting task_id (present in both with different
values) instead of logging them directly — issue-552 finding #1: the caller must defer
the actual map-debt.md write until after the enclosing transaction's COMMIT succeeds,
since a filesystem append has no rollback and must not survive a rolled-back rebuild."""
merge_cols = [r[1] for r in conn.execute('PRAGMA table_info("_tasks_old_merge");').fetchall()]
target_cols = [r[1] for r in conn.execute('PRAGMA table_info("tasks");').fetchall()]
common_cols = [c for c in merge_cols if c in target_cols]
cols_str = ", ".join(f'"{c}"' for c in common_cols)
existing_ids = {r[0] for r in conn.execute("SELECT task_id FROM tasks").fetchall()}
conflicts = []
for row in conn.execute(f'SELECT {cols_str} FROM "_tasks_old_merge"').fetchall():
row_dict = dict(zip(common_cols, row))
task_id = row_dict["task_id"]
if task_id in existing_ids:
conflicts.append(task_id)
continue
placeholders = ", ".join(["?"] * len(common_cols))
conn.execute(f'INSERT INTO tasks ({cols_str}) VALUES ({placeholders})', row)
return conflicts
def _log_orphan_merge_conflicts(self, conflicting_task_ids: List[str]):
"""Appends a map-debt entry for task_ids dropped during an orphaned-table merge
(present in both the fresh `tasks` table and a dangling `_tasks_old`)."""
repo_root = _resolve_repo_root()
map_debt_path = repo_root / "references" / "map-debt.md"
if not self._fs.exists(map_debt_path):
return
entry = (
f"\n| DEBT-{self._clock.strftime('%Y%m%d')}-AUTO | Orphaned _tasks_old merge conflict "
f"discarded rows for task_ids: {', '.join(conflicting_task_ids)} | OPEN | Tier 1 | 1 | "
f"{self._clock.strftime('%Y-%m-%d')} | Self-heal migration in init_db() found these task_ids "
f"in both the fresh tasks table and a dangling _tasks_old, with differing data. "
f"The tasks table's version was kept; _tasks_old's version was discarded. | "
f"Review discarded data manually if needed; _tasks_old is already dropped. |\n"
)
self._fs.append_text(map_debt_path, entry)
def _rebuild_schema_transactional(self, conn: sqlite3.Connection):
"""Rebuilds tasks + all child tables together in one explicit transaction, so a
mid-sequence failure rolls back cleanly instead of leaving a corrupted intermediate
state. Renaming all six tables together (instead of `tasks` alone) prevents SQLite's
FK-auto-repoint behavior from leaving child tables pointing at a stale name.
issue-552: this guarantee was previously false. `conn.executescript(SCHEMA_SQL)`
silently commits any open transaction before running (documented CPython sqlite3
behavior) — everything after that call ran unprotected, and its embedded
`PRAGMA foreign_keys = ON;` re-enabled FK enforcement mid-method, which could then
cascade-delete not-yet-copied child rows when a `_<table>_migrating` table was dropped
later in the same copy loop (found empirically: DROP TABLE on a renamed parent table,
with FK back on, cascades to a child table whose FK definition auto-repointed to follow
the same rename). Fixed by executing SCHEMA_SQL as individual statements
(_split_schema_sql_statements) inside the one real BEGIN IMMEDIATE/COMMIT transaction,
with all 3 leading PRAGMAs filtered out so `foreign_keys` stays OFF for the method's
entire duration."""
conn.execute("PRAGMA foreign_keys = OFF;")
conn.execute("BEGIN IMMEDIATE;")
orphan_merge_conflicts: List[str] = []
try:
orphan_exists = conn.execute(
"SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name='_tasks_old'"
).fetchone()[0]
if orphan_exists:
conn.execute('ALTER TABLE "_tasks_old" RENAME TO "_tasks_old_merge";')
for table in ALL_REBUILD_TABLES:
exists = conn.execute(
"SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=?", (table,)
).fetchone()[0]
if exists:
conn.execute(f'ALTER TABLE "{table}" RENAME TO "_{table}_migrating";')
for statement in _split_schema_sql_statements(SCHEMA_SQL):
conn.execute(statement)
# issue-523: ALTER TABLE RENAME re-points existing triggers on `tasks` to follow
# the rename (to `_tasks_migrating`) rather than dropping them — so both
# enforcement triggers are now silently bound to the migrating table, not the
# fresh `tasks` just created by SCHEMA_SQL above. Left alone, this causes two
# distinct failures found empirically: (a) enforce_valid_initial_state would fire
# on every bulk row-copy INSERT below, wrongly DELETING every already-progressed
# task; (b) enforce_valid_transition silently vanishes entirely once
# `_tasks_migrating` is dropped at the end of the copy loop, since SQLite drops a
# table's triggers along with it — leaving UPDATE-side enforcement permanently
# disabled after every rebuild. Drop both explicitly here, recreate both together
# once real rows are back in place under the correct table.
conn.execute("DROP TRIGGER IF EXISTS enforce_valid_initial_state;")
conn.execute("DROP TRIGGER IF EXISTS enforce_valid_transition;")
for table in ALL_REBUILD_TABLES:
migrating_name = f"_{table}_migrating"
migrating_exists = conn.execute(
"SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=?", (migrating_name,)
).fetchone()[0]
if migrating_exists:
self._copy_common_columns(conn, migrating_name, table)
conn.execute(f'DROP TABLE "{migrating_name}";')
if orphan_exists:
orphan_merge_conflicts = self._merge_orphaned_tasks_old(conn)
conn.execute('DROP TABLE "_tasks_old_merge";')
# Recreate the trigger from the canonical schema (SCHEMA_SQL) rather than a second,
# independently-maintained inline copy -- the two previously drifted from being
# hand-edited separately, and the inline copy's result was discarded immediately by
# the very next DROP TRIGGER anyway, making it dead code.
recovery_trigger = next(
statement for statement in _split_schema_sql_statements(SCHEMA_SQL)
if "CREATE TRIGGER IF NOT EXISTS enforce_valid_transition" in statement
)
conn.execute(recovery_trigger)
conn.execute("""
CREATE TRIGGER IF NOT EXISTS enforce_valid_initial_state
AFTER INSERT ON tasks
WHEN NOT EXISTS (
SELECT 1 FROM valid_transitions WHERE from_state IS NULL AND to_state = NEW.state
)
BEGIN
INSERT INTO transition_violations (task_id, attempted_from_state, attempted_to_state)
VALUES (NEW.task_id, NULL, NEW.state);
DELETE FROM tasks WHERE task_id = NEW.task_id;
END;
""")
conn.execute("DELETE FROM schema_version;")
conn.execute("INSERT INTO schema_version (version) VALUES (?);", (CURRENT_SCHEMA_VERSION,))
conn.execute("COMMIT;")
except Exception:
conn.execute("ROLLBACK;")
raise
finally:
conn.execute("PRAGMA foreign_keys = ON;")
# issue-552 finding #1: only log map-debt conflicts after COMMIT has actually
# succeeded (control only reaches here on the non-exception path above) — this write
# is a plain filesystem append, invisible to SQL rollback, so logging it before COMMIT
# let a rolled-back rebuild leave a permanent, misleading map-debt entry for a
# migration that never actually completed.
if orphan_merge_conflicts:
try:
self._log_orphan_merge_conflicts(orphan_merge_conflicts)
except Exception as e:
# issue-552 implementation-review finding: the schema rebuild itself already
# committed successfully at this point — a failure to append the map-debt
# entry (disk full, permissions) must not be reported as a rebuild failure to
# every ensure_schema() caller.
warnings.warn(f"schema rebuild succeeded but map-debt logging failed: {e}")
# --- PersistencePort CRUD implementation (moved verbatim from ControlPlane) ---
def insert_premium_consent(
self, task_id: str, stage: str, round_id: str, model_id: str, actor: str
) -> int:
"""Store human premium consent for one exact stage/round/model scope."""
self.ensure_schema()
conn = self.get_connection()
try:
conn.execute(
"""
INSERT INTO premium_consents (task_id, stage, round_id, model_id, actor, consented_at)
VALUES (?, ?, ?, ?, ?, ?)
ON CONFLICT(task_id, stage, round_id, model_id) DO UPDATE SET
actor = excluded.actor,
consented_at = excluded.consented_at
""",
(task_id, stage, round_id, model_id, actor, self._clock.current_time()),
)
row = conn.execute(
"""
SELECT consent_id FROM premium_consents
WHERE task_id = ? AND stage = ? AND round_id = ? AND model_id = ?
""",
(task_id, stage, round_id, model_id),
).fetchone()
conn.commit()
return row["consent_id"]
except Exception:
conn.rollback()
raise
finally:
conn.close()
def has_premium_consent(self, task_id: str, stage: str, round_id: str, model_id: str) -> bool:
"""Check premium consent without widening the approved stage or round scope."""
self.ensure_schema()
conn = self.get_connection()
try:
return conn.execute(
"""
SELECT 1 FROM premium_consents
WHERE task_id = ? AND stage = ? AND round_id = ? AND model_id = ? AND actor = ?
""",
(task_id, stage, round_id, model_id, ACTOR_HUMAN),
).fetchone() is not None
finally:
conn.close()
def insert_source_assisted_answer_candidate(
self,
task_id: str,
stage: str,
round_id: str,
question_id: str,
answer: str,
source_path: str,
source_authorized: bool,
) -> int:
"""Persist a candidate answer as unconfirmed provenance, never as a user decision."""
self.ensure_schema()
conn = self.get_connection()
try:
cursor = conn.execute(
"""
INSERT INTO source_assisted_answer_candidates (
task_id, stage, round_id, question_id, answer, source_path,
source_authorized, created_at
) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
""",
(
task_id,
stage,
round_id,
question_id,
answer,
source_path,
int(source_authorized),
self._clock.current_time(),
),
)
conn.commit()
return cursor.lastrowid
except Exception:
conn.rollback()
raise
finally:
conn.close()
def confirm_source_assisted_answer_candidate(self, candidate_id: int, actor: str) -> bool:
"""Confirm a pending candidate with explicit human provenance."""
self.ensure_schema()
conn = self.get_connection()
try:
cursor = conn.execute(
"""
UPDATE source_assisted_answer_candidates
SET confirmation_status = ?, confirmed_by = ?, confirmed_at = ?
WHERE candidate_id = ? AND confirmation_status = ?
""",
(CONFIRMATION_STATUS_CONFIRMED, actor, self._clock.current_time(), candidate_id, CONFIRMATION_STATUS_PENDING),
)
conn.commit()
return cursor.rowcount == 1
except Exception:
conn.rollback()
raise
finally:
conn.close()
def upsert_interview_plan_outline(
self, task_id: str, bullets: List[Dict[str, Any]], artifact_path: str
) -> int:
"""Persist one canonical, revisioned interview outline for a task."""
self.ensure_schema()
conn = self.get_connection()
try:
now = self._clock.current_time()
encoded = json.dumps(bullets, ensure_ascii=False, sort_keys=True)
with conn:
row = conn.execute(
"SELECT revision FROM interview_plan_outlines WHERE task_id = ?",
(task_id,),
).fetchone()
revision = int(row[0]) + 1 if row else 1
conn.execute(
"""
INSERT INTO interview_plan_outlines (
task_id, outline_json, artifact_path, revision, created_at, updated_at
) VALUES (?, ?, ?, ?, ?, ?)
ON CONFLICT(task_id) DO UPDATE SET
outline_json = excluded.outline_json,
artifact_path = excluded.artifact_path,
revision = excluded.revision,
updated_at = excluded.updated_at
""",
(task_id, encoded, artifact_path, revision, now, now),
)
return revision
finally:
conn.close()
def get_interview_plan_outline(self, task_id: str) -> Optional[Dict[str, Any]]:
"""Retrieve the canonical interview outline and decoded bullet list."""
self.ensure_schema()
conn = self.get_connection()
try:
row = conn.execute(
"SELECT task_id, outline_json, artifact_path, revision, created_at, updated_at "
"FROM interview_plan_outlines WHERE task_id = ?",
(task_id,),
).fetchone()
if row is None:
return None
result = dict(row)
result["bullets"] = json.loads(result.pop("outline_json"))
return result
finally:
conn.close()
def has_unconfirmed_source_assisted_answer_candidates(
self, task_id: str, stage: str, round_id: Optional[str]
) -> bool:
"""Check the requested stage/round scope for pending source candidates."""
self.ensure_schema()
conn = self.get_connection()
try:
if round_id is None:
query = """
SELECT 1 FROM source_assisted_answer_candidates
WHERE task_id = ? AND stage = ? AND confirmation_status = ?
"""
params = (task_id, stage, CONFIRMATION_STATUS_PENDING)
else:
query = """
SELECT 1 FROM source_assisted_answer_candidates
WHERE task_id = ? AND stage = ? AND round_id = ? AND confirmation_status = ?
"""
params = (task_id, stage, round_id, CONFIRMATION_STATUS_PENDING)
return conn.execute(query, params).fetchone() is not None
finally:
conn.close()
def get_task(self, task_id: str) -> Optional[Dict[str, Any]]:
"""Retrieves a task dictionary by task_id."""
self.ensure_schema()
conn = self.get_connection()
try:
row = conn.execute("SELECT * FROM tasks WHERE task_id = ?", (task_id,)).fetchone()
return dict(row) if row else None
finally:
conn.close()
def create_delegation_plan(self, task_id: str, contract: Dict[str, Any]) -> int:
"""Persist one validated delegation boundary."""
self.ensure_schema()
conn = self.get_connection()
try:
now = time.time()
with conn:
cursor = conn.execute(
"""
INSERT INTO delegation_contracts (
task_id, objective, scope_json, authority_json, tool_limits_json,
budget_json, artifacts_json, verifier_json, escalation_json,
fallback_candidates_json, backend, model_id, cost_tier,
capability_class, status, created_at, updated_at
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
task_id, contract["objective"], json.dumps(contract["scope"]),
json.dumps(contract["authority"]), json.dumps(contract["tool_limits"]),
json.dumps(contract["budget"]), json.dumps(contract["artifacts"]),
json.dumps(contract["verifier"]), json.dumps(contract["escalation"]),
json.dumps(contract["fallback_candidates"]), contract["backend"],
contract["model_id"], contract["cost_tier"], contract["capability_class"],
contract.get("status", "PENDING_APPROVAL"), now, now,
),
)
return int(cursor.lastrowid)
finally:
conn.close()
def get_delegation_plan(self, contract_id: int) -> Optional[Dict[str, Any]]:
"""Retrieve one delegation contract with structured JSON fields decoded."""
self.ensure_schema()
conn = self.get_connection()
try:
row = conn.execute("SELECT * FROM delegation_contracts WHERE contract_id = ?", (contract_id,)).fetchone()
if not row:
return None
result = dict(row)
for field in ("scope", "authority", "tool_limits", "budget", "artifacts", "verifier", "escalation", "fallback_candidates"):
result[field] = json.loads(result.pop(f"{field}_json"))
return result
finally:
conn.close()
def approve_delegation_plan(self, contract_id: int, actor: str) -> None:
"""Record an explicit human approval."""
self.ensure_schema()
conn = self.get_connection()
try:
with conn:
latest = conn.execute(
"SELECT backend, model_id, cost_tier, capability_class, write_capable FROM delegation_receipts WHERE contract_id = ? ORDER BY receipt_id DESC LIMIT 1",
(contract_id,),
).fetchone()
if latest:
row = conn.execute("SELECT authority_json FROM delegation_contracts WHERE contract_id = ?", (contract_id,)).fetchone()
authority = json.loads(row[0])
authority["write"] = bool(latest["write_capable"])
conn.execute(
"UPDATE delegation_contracts SET backend = ?, model_id = ?, cost_tier = ?, capability_class = ?, authority_json = ? WHERE contract_id = ? AND status = 'PENDING_APPROVAL'",
(latest["backend"], latest["model_id"], latest["cost_tier"], latest["capability_class"], json.dumps(authority), contract_id),
)
cursor = conn.execute(
"UPDATE delegation_contracts SET status = 'APPROVED', approved_by = ?, updated_at = ? WHERE contract_id = ? AND status = 'PENDING_APPROVAL'",
(actor, time.time(), contract_id),
)
if cursor.rowcount != 1:
raise ValueError(f"Delegation contract {contract_id} is not pending approval")
finally:
conn.close()
def count_delegation_receipts(self, contract_id: int) -> int:
self.ensure_schema()
conn = self.get_connection()
try:
return conn.execute("SELECT COUNT(*) FROM delegation_receipts WHERE contract_id = ?", (contract_id,)).fetchone()[0]
finally:
conn.close()
def insert_delegation_receipt(self, contract_id: int, receipt: Dict[str, Any]) -> int:
self.ensure_schema()
conn = self.get_connection()
try:
with conn:
cursor = conn.execute(
"""
INSERT INTO delegation_receipts (
contract_id, task_id, backend, model_id, cost_tier,
capability_class, write_capable, written_paths_json, backend_available, created_at
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
contract_id, receipt["task_id"], receipt["backend"], receipt["model_id"],
receipt["cost_tier"], receipt["capability_class"], int(receipt.get("write_capable", False)),
json.dumps(receipt.get("written_paths", [])), int(receipt.get("backend_available", True)), time.time(),
),
)
return int(cursor.lastrowid)
finally:
conn.close()
def insert_delegation_verifier_receipt(self, contract_id: int, command: str, exit_code: int) -> None:
self.ensure_schema()
conn = self.get_connection()
try:
with conn:
conn.execute(
"INSERT INTO delegation_verifier_receipts (contract_id, command, exit_code, created_at) VALUES (?, ?, ?, ?)",
(contract_id, command, exit_code, time.time()),
)
finally:
conn.close()
def mark_delegation_status(self, contract_id: int, status: str) -> None:
self.ensure_schema()
conn = self.get_connection()
try:
with conn:
conn.execute("UPDATE delegation_contracts SET status = ?, updated_at = ? WHERE contract_id = ?", (status, time.time(), contract_id))
finally:
conn.close()
def has_delegation_verifier_receipt(self, contract_id: int) -> bool:
self.ensure_schema()
conn = self.get_connection()
try:
return conn.execute(
"SELECT COUNT(*) FROM delegation_verifier_receipts WHERE contract_id = ? AND exit_code = 0",
(contract_id,),
).fetchone()[0] > 0
finally:
conn.close()
def insert_task(self, task_id: str, title: str, task_type: str, runtime_tool: str,
spec_path: Optional[str], model_tier: Optional[str], model_id: Optional[str]) -> None:
"""Inserts a new task row in INTAKE state and its creation transition, atomically."""
self.ensure_schema()
conn = self.get_connection()
try:
with conn:
conn.execute(
"""
INSERT INTO tasks (task_id, title, state, task_type, runtime_tool, spec_path, model_tier, model_id)
VALUES (?, ?, ?, ?, ?, ?, ?, ?)
""",
(task_id, title, STATE_INTAKE, task_type, runtime_tool, spec_path, model_tier, model_id)
)
conn.execute(
"""
INSERT INTO task_transitions (task_id, from_state, to_state, actor, reason)
VALUES (?, ?, ?, ?, ?)
""",
(task_id, "NONE", STATE_INTAKE, ACTOR_SYSTEM, "Task created")
)
finally:
conn.close()
def read_current_state(self, task_id: str) -> Optional[str]:
"""Reads a task's current state value directly, for use immediately before a guarded
write. Calls ensure_schema() first (issue-524, post-round-2-review correction: this
method previously could hit "no such table: tasks" against a fresh DB — every public
PersistencePort operation now self-heals the schema before querying, closing that gap)."""
self.ensure_schema()
conn = self.get_connection()
try:
row = conn.execute("SELECT state FROM tasks WHERE task_id = ?", (task_id,)).fetchone()
return row[0] if row else None
finally:
conn.close()
def apply_transition(self, task_id: str, from_state: str, to_state: str, actor: str, reason: str) -> bool:
"""Atomically updates task state (guarded by expected from_state) and records the
transition row. Returns False if the guard predicate did not match (concurrent write) —
the caller (ControlPlane.transition()) raises ConcurrentModificationError in that case."""
self.ensure_schema()
conn = self.get_connection()
try:
with conn:
cursor = conn.execute(
"UPDATE tasks SET state = ?, updated_at = CURRENT_TIMESTAMP WHERE task_id = ? AND state = ?",
(to_state, task_id, from_state)
)
if cursor.rowcount == 0:
return False
post_state = conn.execute("SELECT state FROM tasks WHERE task_id = ?", (task_id,)).fetchone()
if not post_state or post_state[0] != to_state:
return False
conn.execute(
"INSERT INTO task_transitions (task_id, from_state, to_state, actor, reason) VALUES (?, ?, ?, ?, ?)",
(task_id, from_state, to_state, actor, reason)
)
# Invalidate stale discretionary skip receipts on leaving occupancy
conn.execute(
"DELETE FROM verification_receipts WHERE task_id = ? AND gate_name IN (?, ?)",
(task_id, GATE_MULTI_AGENT_REVIEW_SKIPPED, GATE_MULTI_AGENT_CODE_REVIEW_SKIPPED)
)
# Invalidate any lingering unconsumed decisions upon leaving occupancy
conn.execute(
"UPDATE transition_decisions SET consumed_at = CURRENT_TIMESTAMP WHERE task_id = ? AND consumed_at IS NULL",
(task_id,)
)
_expire_pending_requests(conn, task_id)
return True
finally:
conn.close()
def count_asymmetric_persistence(self, task_id: str, details_like: Optional[str] = None,
destination_like_any: Optional[List[str]] = None) -> int:
"""Counts asymmetric_persistence_log rows for task_id, filtered per details_like
(single LIKE pattern on `details`) or destination_like_any (OR'd LIKE patterns on
`destination`) — at most one filter kind is expected per call."""
self.ensure_schema()
conn = self.get_connection()
try:
if details_like is not None:
return conn.execute(
"SELECT COUNT(*) FROM asymmetric_persistence_log WHERE task_id = ? AND details LIKE ?",
(task_id, details_like)
).fetchone()[0]
if destination_like_any is not None:
clause = " OR ".join(["destination LIKE ?"] * len(destination_like_any))
return conn.execute(
f"SELECT COUNT(*) FROM asymmetric_persistence_log WHERE task_id = ? AND ({clause})",
(task_id, *destination_like_any)
).fetchone()[0]
return conn.execute(
"SELECT COUNT(*) FROM asymmetric_persistence_log WHERE task_id = ?", (task_id,)
).fetchone()[0]
finally:
conn.close()
def count_receipts(self, task_id: str, gate_name: str, exit_code: Optional[int] = None) -> int:
"""Counts verification_receipts rows for task_id matching gate_name (and exit_code if given)."""
self.ensure_schema()
conn = self.get_connection()
try:
if exit_code is None:
return conn.execute(
"SELECT COUNT(*) FROM verification_receipts WHERE task_id = ? AND gate_name = ? AND invalidated_at IS NULL",
(task_id, gate_name)
).fetchone()[0]
return conn.execute(
"SELECT COUNT(*) FROM verification_receipts WHERE task_id = ? AND gate_name = ? AND exit_code = ? AND invalidated_at IS NULL",
(task_id, gate_name, exit_code)
).fetchone()[0]
finally:
conn.close()
def count_locked_verifiers(self, task_id: str) -> int:
"""Counts locked_verifier_baselines rows for task_id."""
self.ensure_schema()
conn = self.get_connection()
try:
return conn.execute(
"SELECT COUNT(*) FROM locked_verifier_baselines WHERE task_id = ?", (task_id,)
).fetchone()[0]
finally:
conn.close()
def get_locked_verifiers(self, task_id: str) -> List[Dict[str, Any]]:
"""Returns locked_verifier_baselines rows (file_path, expected_sha256) for task_id."""
self.ensure_schema()
conn = self.get_connection()
try:
rows = conn.execute(
"SELECT file_path, expected_sha256 FROM locked_verifier_baselines WHERE task_id = ?",
(task_id,)
).fetchall()
return [dict(r) for r in rows]
finally:
conn.close()
def has_passing_critic_review(self, task_id: str) -> bool:
"""Returns whether any critic_reviews row for task_id has verdict='PASS'."""
self.ensure_schema()
conn = self.get_connection()
try:
return conn.execute(
"SELECT COUNT(*) FROM critic_reviews WHERE task_id = ? AND verdict = 'PASS'",
(task_id,)
).fetchone()[0] > 0
finally:
conn.close()
def has_receipt(self, task_id: str, gate_name: str) -> bool:
"""Returns whether any verification_receipts row exists for task_id with the given gate_name."""
self.ensure_schema()
conn = self.get_connection()
try:
return conn.execute(
"SELECT COUNT(*) FROM verification_receipts WHERE task_id = ? AND gate_name = ? AND invalidated_at IS NULL",
(task_id, gate_name)
).fetchone()[0] > 0
finally:
conn.close()
def insert_verification_receipt(self, task_id: str, gate_name: str, command_executed: str,
exit_code: int, receipt_token: str,
actor: Optional[str] = None, provenance: str = "api") -> None:
"""Inserts a verification_receipts row and its append-only 'created' audit row (same transaction)."""
self.ensure_schema()
conn = self.get_connection()
try:
with conn:
cursor = conn.execute(
"""
INSERT INTO verification_receipts (task_id, gate_name, command_executed, exit_code, receipt_token, actor, provenance)
VALUES (?, ?, ?, ?, ?, ?, ?)
""",
(task_id, gate_name, command_executed, exit_code, receipt_token, actor, provenance)
)
conn.execute(
"INSERT INTO receipt_audit (receipt_id, task_id, gate_name, event, actor, provenance) VALUES (?, ?, ?, 'created', ?, ?)",
(cursor.lastrowid, task_id, gate_name, actor or "system", provenance)
)
finally:
conn.close()
def pending_human_questions(self, task_id: str, from_state: str, to_state: str) -> List[str]:
"""Required question ids of the edge that still lack an unconsumed, non-empty human decision
(the database trigger's own test; used for actionable rejections and readiness guidance)."""
self.ensure_schema()
conn = self.get_connection()
try:
return [r[0] for r in conn.execute(
"SELECT rq.question_id FROM required_transition_questions rq WHERE rq.from_state = ? AND rq.to_state = ? "
"AND NOT EXISTS (SELECT 1 FROM transition_decisions td WHERE td.task_id = ? AND td.from_state = rq.from_state "
"AND td.to_state = rq.to_state AND td.question_id = rq.question_id AND td.actor = ? "
"AND td.answer IS NOT NULL AND trim(td.answer) != '' AND td.consumed_at IS NULL)",
(from_state, to_state, task_id, ACTOR_HUMAN))]
finally:
conn.close()
def review_selection_gaps(self, registry: Any, task_id: str, from_state: str, to_state: str) -> List[str]:
"""Conditional review-selection question ids the recorded method requires but that lack a human decision."""
from control_plane.review_selection import review_selection_gaps
self.ensure_schema()
conn = self.get_connection()
try:
return review_selection_gaps(conn, registry, task_id, from_state, to_state)
finally:
conn.close()
def invalidate_receipt(self, receipt_id: int, actor: str, reason: str) -> None:
"""Marks a receipt invalid (it stops satisfying gates) and appends the 'invalidated' audit row."""
self.ensure_schema()
conn = self.get_connection()
try:
with conn:
row = conn.execute(
"SELECT task_id, gate_name FROM verification_receipts WHERE receipt_id = ? AND invalidated_at IS NULL", (receipt_id,)
).fetchone()
if row is None:
raise ValueError(f"receipt {receipt_id} does not exist or is already invalidated")
conn.execute(
"UPDATE verification_receipts SET invalidated_at = CURRENT_TIMESTAMP, invalidation_reason = ? WHERE receipt_id = ?",
(reason, receipt_id)
)
conn.execute(
"INSERT INTO receipt_audit (receipt_id, task_id, gate_name, event, actor, provenance, reason) VALUES (?, ?, ?, 'invalidated', ?, 'human-interactive', ?)",
(receipt_id, row[0], row[1], actor, reason)
)
finally:
conn.close()
def insert_critic_review(self, task_id: str, iteration: int, model: str, verdict: str, findings: str) -> None:
"""Inserts a critic_reviews row."""
self.ensure_schema()
conn = self.get_connection()
try:
with conn:
conn.execute(
"""
INSERT INTO critic_reviews (task_id, iteration, model_used, verdict, critique_findings)
VALUES (?, ?, ?, ?, ?)
""",
(task_id, iteration, model, verdict, findings)
)
finally:
conn.close()
def insert_locked_verifier(self, task_id: str, file_path: str, expected_sha256: str) -> None:
"""Inserts a locked_verifier_baselines row."""
self.ensure_schema()
conn = self.get_connection()
try:
with conn:
conn.execute(
"INSERT INTO locked_verifier_baselines (task_id, file_path, expected_sha256) VALUES (?, ?, ?)",
(task_id, file_path, expected_sha256)
)
finally:
conn.close()
def insert_asymmetric_persistence(self, task_id: str, destination: str, status: str, details: str) -> None:
"""Inserts an asymmetric_persistence_log row."""
self.ensure_schema()
conn = self.get_connection()
try:
with conn:
conn.execute(
"""
INSERT INTO asymmetric_persistence_log (task_id, destination, status, details)
VALUES (?, ?, ?, ?)
""",
(task_id, destination, status, details)
)
finally:
conn.close()
def get_latest_asymmetric_persistence(
self, task_id: str, destination: Optional[str] = None
) -> Optional[Dict[str, Any]]:
"""Retrieves the latest asymmetric_persistence_log row for a task_id and optional destination."""
self.ensure_schema()
conn = self.get_connection()
try:
cursor = conn.cursor()
if destination:
cursor.execute(
"""
SELECT log_id, task_id, destination, status, details, timestamp
FROM asymmetric_persistence_log
WHERE task_id = ? AND destination = ?
ORDER BY log_id DESC LIMIT 1
""",
(task_id, destination),
)
else:
cursor.execute(
"""
SELECT log_id, task_id, destination, status, details, timestamp
FROM asymmetric_persistence_log
WHERE task_id = ?
ORDER BY log_id DESC LIMIT 1
""",
(task_id,),
)
row = cursor.fetchone()
if not row:
return None
return {
"log_id": row[0],
"task_id": row[1],
"destination": row[2],
"status": row[3],
"details": row[4],
"timestamp": row[5],
}
finally:
conn.close()
def get_guidance_block_reason(self, task_id: str) -> Optional[str]:
"""Returns the task's guidance_block_reason (None if not blocked)."""
self.ensure_schema()
conn = self.get_connection()
try:
row = conn.execute("SELECT guidance_block_reason FROM tasks WHERE task_id = ?", (task_id,)).fetchone()
return row["guidance_block_reason"] if row else None
finally:
conn.close()
def set_guidance_block(self, task_id: str, reason: str) -> None:
"""Sets guidance_block_reason, refusing all further transitions for this task
until explicitly cleared -- triggered when a human answers 'no' (or gives no
answer) to the mandatory per-transition guidance-compliance confirmation."""
self.ensure_schema()
conn = self.get_connection()
try:
with conn:
conn.execute(
"UPDATE tasks SET guidance_block_reason = ?, updated_at = CURRENT_TIMESTAMP WHERE task_id = ?",
(reason, task_id)
)
finally:
conn.close()
def clear_guidance_block(self, task_id: str) -> None:
"""Clears guidance_block_reason -- requires an explicit, separate human-confirmed
CLI action (clear-guidance-block); never cleared automatically by a later transition
attempt."""
self.ensure_schema()
conn = self.get_connection()
try:
with conn:
conn.execute(
"UPDATE tasks SET guidance_block_reason = NULL, updated_at = CURRENT_TIMESTAMP WHERE task_id = ?",
(task_id,)
)
finally:
conn.close()
def get_verification_receipts(self, task_id: str) -> List[Dict[str, Any]]:
"""Returns all verification_receipts rows for task_id."""
self.ensure_schema()
conn = self.get_connection()
try:
rows = conn.execute("SELECT * FROM verification_receipts WHERE task_id = ?", (task_id,)).fetchall()
return [dict(r) for r in rows]
finally:
conn.close()
def save_retrospective(self, task_id: str, entry: Dict[str, Any], follow_ups: List[Dict[str, Any]]) -> None:
"""Upserts one retrospective draft/completion and replaces its follow-up rows."""
self.ensure_schema()
conn = self.get_connection()
try:
with conn:
now = float(entry.get("updated_at", time.time()))
existing = conn.execute(
"SELECT retrospective_id, created_at FROM retrospective_entries WHERE task_id = ?",
(task_id,),
).fetchone()
created_at = existing["created_at"] if existing else float(entry.get("created_at", now))
if existing:
retrospective_id = existing["retrospective_id"]
conn.execute(
"""
UPDATE retrospective_entries
SET decision = ?, completion_mode = ?, actor = ?, outcome = ?, strengths = ?,
friction = ?, learning = ?, improvement = ?, follow_up = ?, skip_reason = ?,
updated_at = ?
WHERE retrospective_id = ?
""",
(
entry["decision"], entry["completion_mode"], entry["actor"],
entry.get("outcome", ""), entry.get("strengths", ""), entry.get("friction", ""),
entry.get("learning", ""), entry.get("improvement", ""), entry.get("follow_up", ""),
entry.get("skip_reason", ""), now, retrospective_id,
),
)
conn.execute(
"DELETE FROM retrospective_follow_ups WHERE retrospective_id = ?",
(retrospective_id,),
)
else:
cursor = conn.execute(
"""
INSERT INTO retrospective_entries
(task_id, decision, completion_mode, actor, outcome, strengths, friction,
learning, improvement, follow_up, skip_reason, created_at, updated_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
task_id, entry["decision"], entry["completion_mode"], entry["actor"],
entry.get("outcome", ""), entry.get("strengths", ""), entry.get("friction", ""),
entry.get("learning", ""), entry.get("improvement", ""), entry.get("follow_up", ""),
entry.get("skip_reason", ""), created_at, now,
),
)
retrospective_id = cursor.lastrowid
for follow_up in follow_ups:
conn.execute(
"""
INSERT INTO retrospective_follow_ups
(retrospective_id, kind, description, status, duplicate_checked, issue_url,
issue_number, created_at, updated_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
retrospective_id, follow_up["kind"], follow_up["description"],
follow_up.get("status", "proposed"), int(bool(follow_up.get("duplicate_checked", False))),
follow_up.get("issue_url"), follow_up.get("issue_number"), now, now,
),
)
finally:
conn.close()
def _proof_required_edges(self) -> frozenset:
"""Edges declaring requires_cryptographic_proof in the YAML registry (cached per adapter)."""
if getattr(self, "_proof_edges_cache", None) is None:
from control_plane.registry import TransitionRegistry
self._proof_edges_cache = TransitionRegistry.load_default().proof_required_edges()
return self._proof_edges_cache
def _preverify_proof_outside_write_lock(self, request: TransitionCommitRequest):
"""For proof-required edges, runs the slow external verification (live snapshot hashing, the
`ssh-keygen -Y verify` subprocess) on a short-lived read connection BEFORE the commit takes its
`BEGIN IMMEDIATE`, so the write lock is never held across a subprocess. Returns None when the edge
takes no proof or none was supplied (the commit transaction then raises the precise refusal).
The commit transaction re-checks the request row and the challenge before consuming."""
edge = (request.expected_from_state, request.to_state)
proof = request.proof
if edge not in self._proof_required_edges() or proof is None or proof.kind != "sshsig":
return None
conn = self.get_connection()
try:
return preverify_signature(
conn, task_id=request.task_id, from_state=edge[0], to_state=edge[1],
occupancy_id=request.source_occupancy_transition_id, proof=proof,
now=self._clock.current_time(),
)
finally:
conn.close()
@staticmethod
def _stored_snapshot(conn: sqlite3.Connection, request_id: int):
"""The content snapshot stored on a transition_request row (already verified against the signature)."""
from control_plane.snapshot import snapshot_from_json
row = conn.execute("SELECT content_snapshot FROM transition_request WHERE request_id = ?", (request_id,)).fetchone()
return snapshot_from_json(row[0]) if row and row[0] else ()
def get_retrospective_summary(self, task_id: str) -> Optional[Dict[str, Any]]:
"""The recorded retrospective as {decision: 'complete'|'skip', digest}, or None. The digest is a SHA-256 over
every content field and follow-up (not timestamps), so a human signature binds exactly what was recorded."""
self.ensure_schema()
conn = self.get_connection()
try:
row = conn.execute(
"SELECT retrospective_id, decision, completion_mode, actor, outcome, strengths, friction, learning, improvement, "
"follow_up, skip_reason FROM retrospective_entries WHERE task_id = ?", (task_id,),
).fetchone()
if row is None:
return None
follow_ups = [
[r["kind"], r["description"], r["status"], r["duplicate_checked"], r["issue_url"], r["issue_number"]]
for r in conn.execute(
"SELECT kind, description, status, duplicate_checked, issue_url, issue_number FROM retrospective_follow_ups "
"WHERE retrospective_id = ? ORDER BY follow_up_id", (row["retrospective_id"],))
]
body = {k: row[k] for k in row.keys() if k != "retrospective_id"}
digest = hashlib.sha256(json.dumps([body, follow_ups], sort_keys=True, separators=(",", ":")).encode("utf-8")).hexdigest()
return {"decision": "skip" if row["decision"] == RETROSPECTIVE_DECISION_SKIP else "complete", "digest": digest}
finally:
conn.close()
def has_complete_retrospective(self, task_id: str) -> bool:
"""Returns true for a completed survey or a reasoned skip with no open issue candidates."""
self.ensure_schema()
conn = self.get_connection()
try:
row = conn.execute(
"SELECT retrospective_id, decision, completion_mode, skip_reason FROM retrospective_entries WHERE task_id = ?",
(task_id,),
).fetchone()
if not row:
return False
if row["decision"] == RETROSPECTIVE_DECISION_SKIP:
complete = row["completion_mode"] == RETROSPECTIVE_COMPLETION_MODE_SKIPPED and bool(row["skip_reason"].strip())
else:
complete = row["decision"] == RETROSPECTIVE_DECISION_OPT_IN and row["completion_mode"] == RETROSPECTIVE_COMPLETION_MODE_COMPLETED
if not complete:
return False
open_issue = conn.execute(
"""
SELECT 1 FROM retrospective_follow_ups
WHERE retrospective_id = ?
AND kind = ?
AND (
status IN (?, ?)
OR (status = ? AND (duplicate_checked = 0 OR issue_url IS NULL OR trim(issue_url) = ''))
)
LIMIT 1
""",
(
row["retrospective_id"], FOLLOW_UP_KIND_ISSUE,
FOLLOW_UP_STATUS_PROPOSED, FOLLOW_UP_STATUS_CONFIRMED,
FOLLOW_UP_STATUS_CREATED,
),
).fetchone()
return open_issue is None
finally:
conn.close()
def update_worktree_fields(self, task_id: str, worktree_path: str, worktree_branch: str, worktree_state: str) -> None:
"""Updates a task's worktree_path/worktree_branch/worktree_state columns."""
self.ensure_schema()
conn = self.get_connection()
try:
with conn:
conn.execute(
"""
UPDATE tasks
SET worktree_path = ?, worktree_branch = ?, worktree_state = ?, updated_at = CURRENT_TIMESTAMP
WHERE task_id = ?
""",
(worktree_path, worktree_branch, worktree_state, task_id)
)
finally:
conn.close()
def record_done_closeout_decision(
self, task_id: str, source_occupancy_transition_id: int, question_id: str,
answer: str, actor: str, recorded_at: float,
) -> int:
"""Persist one human decision for the post-DONE Git closeout gate."""
self.ensure_schema()
conn = self.get_connection()
try:
conn.execute("BEGIN IMMEDIATE;")
task = conn.execute(
"SELECT state FROM tasks WHERE task_id = ?", (task_id,)
).fetchone()
if task is None:
raise ValueError(f"Task not found: {task_id}")
if task["state"] != STATE_DONE:
raise PersistenceInvariantViolation(
f"DONE closeout decisions require task '{task_id}' to be in DONE; "
f"current state is '{task['state']}'."
)
latest = conn.execute(
"SELECT transition_id, to_state FROM task_transitions "
"WHERE task_id = ? ORDER BY transition_id DESC LIMIT 1",
(task_id,),
).fetchone()
if latest is None or latest["transition_id"] != source_occupancy_transition_id or latest["to_state"] != STATE_DONE:
raise PersistenceInvariantViolation(
f"DONE closeout decision for '{task_id}' is stale; expected current DONE "
f"occupancy {latest['transition_id'] if latest else None}."
)
cursor = conn.execute(
"INSERT INTO done_closeout_decisions "
"(task_id, source_occupancy_transition_id, question_id, answer, actor, recorded_at) "
"VALUES (?, ?, ?, ?, ?, ?)",
(task_id, source_occupancy_transition_id, question_id, answer, actor, recorded_at),
)
conn.commit()
return int(cursor.lastrowid)
except Exception:
conn.rollback()
raise
finally:
conn.close()
def get_done_closeout_decisions(self, task_id: str) -> List[Dict[str, Any]]:
"""Return post-DONE Git closeout decisions in recording order."""
self.ensure_schema()
conn = self.get_connection()
try:
rows = conn.execute(
"SELECT * FROM done_closeout_decisions WHERE task_id = ? "
"ORDER BY closeout_decision_id", (task_id,)
).fetchall()
return [dict(row) for row in rows]
finally:
conn.close()
def get_last_transition(
self,
task_id: str,
from_state: Optional[str] = None,
to_state: Optional[str] = None,
) -> Optional[TransitionRecord]:
"""Returns the latest TransitionRecord for task_id matching optional from_state/to_state filters."""
self.ensure_schema()
conn = self.get_connection()
try:
query = "SELECT transition_id, task_id, from_state, to_state, actor, reason, timestamp FROM task_transitions WHERE task_id = ?"
params: List[Any] = [task_id]
if from_state is not None:
query += " AND from_state = ?"
params.append(from_state)
if to_state is not None:
query += " AND to_state = ?"
params.append(to_state)
query += " ORDER BY transition_id DESC LIMIT 1"
row = conn.execute(query, params).fetchone()
if not row:
return None
return TransitionRecord(
transition_id=row["transition_id"],
task_id=row["task_id"],
from_state=row["from_state"],
to_state=row["to_state"],
actor=row["actor"],
reason=row["reason"],
timestamp=str(row["timestamp"]),
)
finally:
conn.close()
def get_unconsumed_transition_answers(
self, task_id: str, from_state: str, to_state: str
) -> Dict[str, str]:
"""Returns recorded answers available to a deterministic transition policy check."""
self.ensure_schema()
conn = self.get_connection()
try:
rows = conn.execute(
"""
SELECT question_id, answer
FROM transition_decisions
WHERE task_id = ? AND from_state = ? AND to_state = ?
AND answer IS NOT NULL AND trim(answer) != ''
AND consumed_at IS NULL
ORDER BY decision_id
""",
(task_id, from_state, to_state),
).fetchall()
return {row["question_id"]: row["answer"] for row in rows}
finally:
conn.close()
def _write_violation_autonomously(self, task_id: str, from_state: Optional[str], to_state: str,
actor: Optional[str], reason: Optional[str], detail: str) -> None:
"""Write a rejection into transition_violations on a SEPARATE connection and transaction, after
the aborted transaction has rolled back (the trigger's own row is rolled back with it)."""
conn = self.get_connection()
try:
with conn:
conn.execute(
"INSERT INTO transition_violations (task_id, attempted_from_state, attempted_to_state, actor, reason, detail, kind) "
"VALUES (?, ?, ?, ?, ?, ?, 'REJECTED_ATTEMPT')",
(task_id, from_state, to_state, actor, reason, detail[:1000]),
)
finally:
conn.close()
def apply_transition_with_receipts(self, request: TransitionCommitRequest) -> TransitionRecord:
"""Commit path with an autonomous rejection audit (see _apply_transition_with_receipts)."""
try:
return self._apply_transition_with_receipts(request)
except _AUDITED_REJECTIONS as exc:
try:
self._write_violation_autonomously(
request.task_id, request.expected_from_state, request.to_state, request.actor, request.reason, str(exc)
)
except Exception:
pass # the audit must never mask the original rejection
raise
def _apply_transition_with_receipts(
self,
request: TransitionCommitRequest,
) -> TransitionRecord:
"""Atomically revalidates authoritative persistable facts in SQLite and applies transition.
Enforces transactional invariants and structural consistency only:
1. Task exists and current state == request.expected_from_state.
2. Latest transition_id == request.source_occupancy_transition_id.
3. Edge (expected_from_state -> to_state) is legal per ALLOWED_TRANSITIONS.
4. Staged decisions structurally match (task_id, source_occupancy_transition_id, expected_from_state, to_state).
5. No duplicate question_ids exist across staged decisions.
6. Valid decision_type in ('ANSWER', 'APPROVAL', 'REJECTION', 'SKIP', 'CONFIRMATION').
7. Atomically updates task state, inserts task_transitions row, inserts transition_decisions
bound to the new transition_id, and inserts verification_receipts.
"""
self.ensure_schema()
preverified = self._preverify_proof_outside_write_lock(request)
conn = self.get_connection()
try:
conn.execute("BEGIN IMMEDIATE;")
# 1. Task exists and state check
task_row = conn.execute("SELECT state FROM tasks WHERE task_id = ?", (request.task_id,)).fetchone()
if not task_row:
raise ValueError(f"Task '{request.task_id}' not found in tasks table.")
current_state = task_row["state"]
if current_state != request.expected_from_state:
raise ValueError(
f"Structural state mismatch: task state is '{current_state}', "
f"expected '{request.expected_from_state}'."
)
# 2. Source occupancy transition check
last_trans_row = conn.execute(
"SELECT transition_id FROM task_transitions WHERE task_id = ? ORDER BY transition_id DESC LIMIT 1",
(request.task_id,)
).fetchone()
latest_trans_id = last_trans_row["transition_id"] if last_trans_row else None
if latest_trans_id != request.source_occupancy_transition_id:
raise ValueError(
f"Stale occupancy transition ID: latest is {latest_trans_id}, "
f"request provided {request.source_occupancy_transition_id}."
)
# A reset is the audited recovery boundary for state drift. Start a fresh
# transition ledger so failed attempts from the prior run cannot poison
# commit/push hooks that validate the complete task history. The reset
# transition itself is inserted below as the new ledger root.
if request.to_state == STATE_INTAKE:
prior_transition_ids = [
row["transition_id"] for row in conn.execute(
"SELECT transition_id FROM task_transitions WHERE task_id = ?",
(request.task_id,),
).fetchall()
]
if prior_transition_ids:
placeholders = ",".join("?" for _ in prior_transition_ids)
conn.execute(
f"DELETE FROM transition_decisions WHERE bound_transition_id IN ({placeholders})",
prior_transition_ids,
)
conn.execute("DELETE FROM task_transitions WHERE task_id = ?", (request.task_id,))
conn.execute("DELETE FROM verification_receipts WHERE task_id = ?", (request.task_id,))
conn.execute("DELETE FROM critic_reviews WHERE task_id = ?", (request.task_id,))
# 3. Legal DAG edge check
allowed_next = ALLOWED_TRANSITIONS.get(request.expected_from_state, [])
if request.to_state not in allowed_next:
raise ValueError(
f"Illegal transition edge: '{request.expected_from_state}' -> '{request.to_state}'. "
f"Allowed: {allowed_next}."
)
# 3b. Cryptographic-proof edges (APPROVED, VERIFY_EXIT, DONE; requires_cryptographic_proof in the
# YAML): the commit needs a verified OpenSSH signature over a content-bound transition_request,
# verified and CONSUMED inside this transaction. There are no human decision rows for these edges:
# the consumed request is the authority, and the trigger requires it. Nothing the caller stages
# (answers, receipts of intent, actor strings) can substitute.
staged = list(request.staged_decisions)
edge = (request.expected_from_state, request.to_state)
proof_audit = None
if edge in self._proof_required_edges():
proof = request.proof
if proof is None or proof.kind != "sshsig":
raise PersistenceInvariantViolation(
f"Edge {edge[0]} -> {edge[1]} requires a verified OpenSSH signature (requires_cryptographic_proof); "
"a prompt, typed word, flag or actor string cannot authorize it."
)
if staged:
raise PersistenceInvariantViolation(
f"Edge {edge[0]} -> {edge[1]} takes no caller-staged decisions; the verified signature is the authority."
)
signed_at = self._clock.current_time()
verified = consume_with_signature(
conn, task_id=request.task_id, from_state=edge[0], to_state=edge[1],
occupancy_id=latest_trans_id, proof=proof, now=signed_at,
preverified=preverified,
)
# One approver per pipeline, by key: real-work databases accept only human keys,
# a simulation database (approver_policy.SIMULATION_DB_NAME) only the agent key
enforce_pipeline_approver(
conn, request.task_id, verified.fingerprint, verified.principal, proof.allowed_signers,
self.db_path, proof.request_id,
)
if preverified is not None:
# Keep the exact signed challenge so the push guard can re-verify it against the human anchor
record_gate_evidence(
conn, proof.request_id, request.task_id, edge[0], edge[1], bytes(preverified.challenge),
bytes(proof.signature), verified.fingerprint, verified.principal, pipeline_context(self.db_path),
)
proof_audit = (
f"proof=sshsig;edge={edge[0]}->{edge[1]};request={proof.request_id};"
f"principal={verified.principal};key={verified.fingerprint}"
)
elif request.proof is not None:
raise PersistenceInvariantViolation(
f"An authorization proof was supplied for {edge[0]} -> {edge[1]}, which does not take one."
)
# 4. Structural validation of staged decisions
valid_types = set(DECISION_TYPES)
seen_questions = set()
for d in staged:
if d.task_id != request.task_id:
raise ValueError(f"Structural mismatch: decision task_id '{d.task_id}' != '{request.task_id}'.")
if d.source_occupancy_transition_id != request.source_occupancy_transition_id:
raise ValueError(f"Structural mismatch: decision occupancy ID '{d.source_occupancy_transition_id}' != '{request.source_occupancy_transition_id}'.")
if d.from_state != request.expected_from_state or d.to_state != request.to_state:
raise ValueError(f"Structural mismatch: decision edge ({d.from_state} -> {d.to_state}) != ({request.expected_from_state} -> {request.to_state}).")
if d.decision_type not in valid_types:
raise ValueError(f"Invalid decision_type '{d.decision_type}'. Must be one of {valid_types}.")
if d.question_id in seen_questions:
raise ValueError(f"Duplicate question_id '{d.question_id}' in staged decisions.")
seen_questions.add(d.question_id)
# 5. Insert task_transitions row
cursor = conn.execute(
"INSERT INTO task_transitions (task_id, from_state, to_state, actor, reason) VALUES (?, ?, ?, ?, ?)",
(request.task_id, request.expected_from_state, request.to_state, request.actor, request.reason)
)
new_trans_id = cursor.lastrowid
# 6. Insert staged decisions bound to new_trans_id
for d in staged:
conn.execute(
"""
INSERT INTO transition_decisions (
task_id, source_occupancy_transition_id, from_state, to_state,
question_id, answer, decision_type, actor, recorded_at, bound_transition_id
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
d.task_id, d.source_occupancy_transition_id, d.from_state, d.to_state,
d.question_id, d.answer, d.decision_type, d.actor, d.recorded_at, new_trans_id
)
)
# 7. Apply state change (fires enforce_valid_transition trigger checking transition_decisions)
conn.execute(
"UPDATE tasks SET state = ?, updated_at = CURRENT_TIMESTAMP WHERE task_id = ?",
(request.to_state, request.task_id)
)
# Verify that database trigger did not revert state
post_row = conn.execute("SELECT state FROM tasks WHERE task_id = ?", (request.task_id,)).fetchone()
if not post_row or post_row["state"] != request.to_state:
raise PersistenceInvariantViolation(
f"Transition from '{request.expected_from_state}' to '{request.to_state}' for task '{request.task_id}' "
"rejected by database trigger (violation logged in transition_violations)."
)
# Bind previously recorded occupancy answers to the transition that consumes them.
now = self._clock.current_time()
conn.execute(
"""
UPDATE transition_decisions
SET bound_transition_id = ?
WHERE task_id = ?
AND source_occupancy_transition_id = ?
AND from_state = ?
AND to_state = ?
AND consumed_at IS NULL
AND bound_transition_id IS NULL
""",
(
new_trans_id, request.task_id,
request.source_occupancy_transition_id,
request.expected_from_state, request.to_state,
),
)
# Mark all staged decisions bound to new_trans_id consumed upon state change commit
conn.execute(
"UPDATE transition_decisions SET consumed_at = ? WHERE bound_transition_id = ?",
(now, new_trans_id)
)
# Invalidate any lingering unconsumed decisions for this task
conn.execute(
"UPDATE transition_decisions SET consumed_at = ? WHERE task_id = ? AND consumed_at IS NULL",
(now, request.task_id)
)
# Clear prior discretionary review skip receipts so stale skips don't persist.
# NOTE (Ordering Dependency): Gate policy evaluation runs upstream before commit,
# so any skip receipt relevant to the immediate transition being committed has already
# been evaluated. Staged receipts inserted in Step 8 immediately restore valid skips
# for the new transition if applicable.
conn.execute(
"DELETE FROM verification_receipts WHERE task_id = ? AND gate_name IN (?, ?)",
(request.task_id, GATE_MULTI_AGENT_REVIEW_SKIPPED, GATE_MULTI_AGENT_CODE_REVIEW_SKIPPED)
)
# 8. Insert staged receipts
for r in request.staged_receipts:
conn.execute(
"""
INSERT INTO verification_receipts (task_id, gate_name, command_executed, exit_code, receipt_token)
VALUES (?, ?, ?, ?, ?)
""",
(request.task_id, r["gate_name"], r["command_executed"], r["exit_code"], r["receipt_token"])
)
if proof_audit is not None:
audit_token = "EVO-INTEGRITY-{}-{}".format(
request.task_id, self._crypto.sha256_hex(f"{request.task_id}:{proof_audit}:{new_trans_id}")[:12]
)
conn.execute(
"INSERT INTO verification_receipts (task_id, gate_name, command_executed, exit_code, receipt_token) VALUES (?, ?, ?, ?, ?)",
(request.task_id, "human_gate_proof", proof_audit, 0, audit_token),
)
if edge == ("AWAITING_APPROVAL", "APPROVED"):
# The verified Gate 1 signature IS the human approval: record the receipt APPROVED -> IN_WORKTREE
# checks in the same transaction, so the human never has to approve twice.
approval = f"approved-by:{verified.principal};key={verified.fingerprint};request={proof.request_id}"
approval_token = "EVO-INTEGRITY-{}-{}".format(
request.task_id, self._crypto.sha256_hex(f"{request.task_id}:{approval}:{new_trans_id}")[:12]
)
conn.execute(
"INSERT INTO verification_receipts (task_id, gate_name, command_executed, exit_code, receipt_token) VALUES (?, ?, ?, ?, ?)",
(request.task_id, "human_approval", approval, 0, approval_token),
)
_expire_pending_requests(conn, request.task_id)
row = conn.execute(
"SELECT transition_id, task_id, from_state, to_state, actor, reason, timestamp FROM task_transitions WHERE transition_id = ?",
(new_trans_id,)
).fetchone()
conn.commit()
return TransitionRecord(
transition_id=row["transition_id"],
task_id=row["task_id"],
from_state=row["from_state"],
to_state=row["to_state"],
actor=row["actor"],
reason=row["reason"],
timestamp=str(row["timestamp"]),
)
except Exception:
conn.rollback()
raise
finally:
conn.close()
def record_recovery_approval(
self,
task_id: str,
expected_source_state: str,
destination_state: str,
source_occupancy_transition_id: int,
approver: str,
decision: str,
reason: str,
actor: str,
) -> str:
"""Issues and persists an unconsumed recovery approval decision record bound to the
current source occupancy ID.
actor is required (no default) and is recorded verbatim -- it is NOT assumed to be
'human' regardless of caller. Prior to 2026-09-18 this method hardcoded actor='human'
unconditionally, which combined with the trigger's recovery bypass to let any caller
(agent or human) forge a fully-trusted human recovery approval for any destination,
including states with real human-authorization requirements. Callers asserting a false
actor value are making a false claim in their own audit trail, not exploiting a code
gap -- the enforce_valid_transition trigger's recovery bypass only honors a row whose
actor column is literally 'human', so a caller must now knowingly lie in a column it
directly controls, rather than the code lying on its behalf by default.
destination_state may never be one of RECOVERY_FORBIDDEN_DESTINATIONS -- states
with a real human-authorization requirement on their only normal inbound edges
(VERIFY_EXIT, APPROVED) -- regardless of actor. Recovery into these states must go
through their normal gated edges; see RECOVERY_FORBIDDEN_DESTINATIONS's own comment
for the live exploit this closes."""
if destination_state in RECOVERY_FORBIDDEN_DESTINATIONS:
raise ValueError(
f"Recovery into '{destination_state}' is not permitted -- this state has a real "
"human-authorization requirement on its normal inbound edge(s) that the recovery "
"path would bypass entirely. Route through the normal gated edge instead."
)
self.ensure_schema()
conn = self.get_connection()
try:
with conn:
task_row = conn.execute("SELECT state FROM tasks WHERE task_id = ?", (task_id,)).fetchone()
if not task_row or task_row["state"] != expected_source_state:
raise ValueError(f"Task state is '{task_row['state'] if task_row else None}', expected '{expected_source_state}'.")
last_trans_row = conn.execute(
"SELECT transition_id FROM task_transitions WHERE task_id = ? ORDER BY transition_id DESC LIMIT 1",
(task_id,)
).fetchone()
if not last_trans_row or last_trans_row["transition_id"] != source_occupancy_transition_id:
raise ValueError(f"Stale occupancy ID {source_occupancy_transition_id}.")
recorded_at = self._clock.current_time()
existing_count = conn.execute(
"SELECT COUNT(*) FROM transition_decisions WHERE task_id = ? AND source_occupancy_transition_id = ?",
(task_id, source_occupancy_transition_id)
).fetchone()[0]
token_material = f"RECOVERY-{task_id}-{source_occupancy_transition_id}-{destination_state}-{recorded_at}-{existing_count + 1}"
token = self._crypto.sha256_hex(token_material)
# Look up static question IDs required for this recovery edge. DONE never reaches this point:
# recovery into DONE is refused above (every inbound edge to DONE is a cryptographic gate).
required_qids = [
r[0] for r in conn.execute(
"SELECT question_id FROM required_transition_questions WHERE from_state = ? AND to_state = ?",
(expected_source_state, destination_state)
).fetchall()
]
if not required_qids:
required_qids = [f"recovery_approval_{expected_source_state.lower()}_to_{destination_state.lower()}"]
for qid in required_qids:
conn.execute(
"""
INSERT INTO transition_decisions (
task_id, source_occupancy_transition_id, from_state, to_state,
question_id, answer, decision_type, actor, recorded_at
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
task_id, source_occupancy_transition_id, expected_source_state, destination_state,
qid, token, decision, actor, recorded_at
)
)
return token
finally:
conn.close()
def apply_recovery_transition(self, *args: Any, **kwargs: Any) -> Any:
"""Recovery commit path with the same autonomous rejection audit as apply_transition_with_receipts."""
try:
return self._apply_recovery_transition(*args, **kwargs)
except _AUDITED_REJECTIONS as exc:
try:
bound = inspect.signature(self._apply_recovery_transition).bind(*args, **kwargs).arguments
self._write_violation_autonomously(
bound["task_id"], bound.get("expected_source_state"), bound["destination_state"],
bound.get("actor"), bound.get("reason"), str(exc),
)
except Exception:
pass # the audit must never mask the original rejection
raise
def _apply_recovery_transition(
self,
task_id: str,
expected_source_state: str,
destination_state: str,
source_occupancy_transition_id: int,
approval_receipt_token: str,
actor: str,
reason: str,
) -> TransitionRecord:
"""Atomically executes recovery transition using a verified, unconsumed approval record."""
self.ensure_schema()
conn = self.get_connection()
try:
conn.execute("BEGIN IMMEDIATE;")
# 1. State check
task_row = conn.execute("SELECT state FROM tasks WHERE task_id = ?", (task_id,)).fetchone()
if not task_row or task_row["state"] != expected_source_state:
raise ValueError(f"State mismatch: task is '{task_row['state'] if task_row else None}', expected '{expected_source_state}'.")
# 2. Occupancy check
last_trans_row = conn.execute(
"SELECT transition_id FROM task_transitions WHERE task_id = ? ORDER BY transition_id DESC LIMIT 1",
(task_id,)
).fetchone()
if not last_trans_row or last_trans_row["transition_id"] != source_occupancy_transition_id:
raise ValueError(f"Stale occupancy ID: latest is {last_trans_row['transition_id'] if last_trans_row else None}, expected {source_occupancy_transition_id}.")
# 3. Verify unconsumed approval record matching token & current occupancy directly at SQL level
decision_rows = conn.execute(
"""
SELECT decision_id FROM transition_decisions
WHERE task_id = ? AND source_occupancy_transition_id = ?
AND from_state = ? AND to_state = ?
AND answer = ? AND decision_type = ?
AND consumed_at IS NULL
""",
(task_id, source_occupancy_transition_id, expected_source_state, destination_state, approval_receipt_token, DECISION_TYPE_APPROVAL)
).fetchall()
if not decision_rows:
# Check if it was already consumed to provide a distinct, clear error
consumed_row = conn.execute(
"""
SELECT decision_id FROM transition_decisions
WHERE task_id = ? AND source_occupancy_transition_id = ?
AND from_state = ? AND to_state = ?
AND answer = ? AND decision_type = ?
AND consumed_at IS NOT NULL
""",
(task_id, source_occupancy_transition_id, expected_source_state, destination_state, approval_receipt_token, DECISION_TYPE_APPROVAL)
).fetchone()
if consumed_row:
raise ValueError(f"Recovery approval token {approval_receipt_token} has already been consumed.")
raise ValueError(f"No matching recovery approval record found for token {approval_receipt_token} in current occupancy.")
# 4. Apply state change (database trigger validates unconsumed human decisions)
conn.execute(
"UPDATE tasks SET state = ?, updated_at = CURRENT_TIMESTAMP WHERE task_id = ?",
(destination_state, task_id)
)
# Verify that database trigger did not revert state
post_row = conn.execute("SELECT state FROM tasks WHERE task_id = ?", (task_id,)).fetchone()
if not post_row or post_row["state"] != destination_state:
raise PersistenceInvariantViolation(
f"Recovery transition from '{expected_source_state}' to '{destination_state}' for task '{task_id}' "
"rejected by database trigger (violation logged in transition_violations)."
)
# 5. Insert task_transitions row
cursor = conn.execute(
"INSERT INTO task_transitions (task_id, from_state, to_state, actor, reason) VALUES (?, ?, ?, ?, ?)",
(task_id, expected_source_state, destination_state, actor, reason)
)
new_trans_id = cursor.lastrowid
# 6. Mark approval consumed & bind to new transition
now = self._clock.current_time()
conn.execute(
"""
UPDATE transition_decisions
SET consumed_at = ?, bound_transition_id = ?
WHERE task_id = ? AND source_occupancy_transition_id = ?
AND answer = ? AND decision_type = ?
""",
(now, new_trans_id, task_id, source_occupancy_transition_id, approval_receipt_token, DECISION_TYPE_APPROVAL)
)
# Invalidate any remaining unconsumed decisions for this task
conn.execute(
"UPDATE transition_decisions SET consumed_at = ? WHERE task_id = ? AND consumed_at IS NULL",
(now, task_id)
)
# 7. Record verification receipt
receipt_token = self._crypto.sha256_hex(
f"RECOVERY-RECEIPT-{task_id}-{new_trans_id}-{approval_receipt_token}-{now}"
)
conn.execute(
"""
INSERT INTO verification_receipts (task_id, gate_name, command_executed, exit_code, receipt_token)
VALUES (?, 'recovery_approval', ?, 0, ?)
""",
(task_id, f"apply_recovery_transition({expected_source_state}->{destination_state})", receipt_token)
)
# 8. Clear prior discretionary review skip receipts
conn.execute(
"DELETE FROM verification_receipts WHERE task_id = ? AND gate_name IN (?, ?)",
(task_id, GATE_MULTI_AGENT_REVIEW_SKIPPED, GATE_MULTI_AGENT_CODE_REVIEW_SKIPPED)
)
_expire_pending_requests(conn, task_id)
row = conn.execute(
"SELECT transition_id, task_id, from_state, to_state, actor, reason, timestamp FROM task_transitions WHERE transition_id = ?",
(new_trans_id,)
).fetchone()
conn.commit()
return TransitionRecord(
transition_id=row["transition_id"],
task_id=row["task_id"],
from_state=row["from_state"],
to_state=row["to_state"],
actor=row["actor"],
reason=row["reason"],
timestamp=row["timestamp"]
)
except Exception:
conn.execute("ROLLBACK;")
raise
finally:
conn.close()
def record_decision(self, decision: TransitionDecision) -> int:
"""Records an occupancy-bound TransitionDecision. Rejects duplicates within same occupancy."""
self.ensure_schema()
conn = self.get_connection()
try:
conn.execute("BEGIN IMMEDIATE;")
existing = conn.execute(
"""
SELECT COUNT(*) FROM transition_decisions
WHERE task_id = ? AND source_occupancy_transition_id = ? AND question_id = ?
""",
(decision.task_id, decision.source_occupancy_transition_id, decision.question_id),
).fetchone()[0]
if existing > 0:
raise ValueError(
f"Duplicate decision for question '{decision.question_id}' already recorded "
f"in occupancy {decision.source_occupancy_transition_id} for task '{decision.task_id}'."
)
cursor = conn.execute(
"""
INSERT INTO transition_decisions (
task_id, source_occupancy_transition_id, from_state, to_state,
question_id, answer, decision_type, actor, recorded_at
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
decision.task_id,
decision.source_occupancy_transition_id,
decision.from_state,
decision.to_state,
decision.question_id,
decision.answer,
decision.decision_type,
decision.actor,
decision.recorded_at,
),
)
decision_id = cursor.lastrowid
conn.commit()
return decision_id
except Exception:
conn.rollback()
raise
finally:
conn.close()
def record_interview_answer(
self,
decision: TransitionDecision,
bullets: List[Dict[str, Any]],
artifact_path: str,
) -> InterviewAnswerRecord:
"""Atomically persist an interview decision and its outline projection."""
self.ensure_schema()
conn = self.get_connection()
try:
conn.execute("BEGIN IMMEDIATE;")
task_row = conn.execute(
"SELECT state FROM tasks WHERE task_id = ?", (decision.task_id,)
).fetchone()
if not task_row:
raise ValueError(f"Task '{decision.task_id}' not found in tasks table.")
if task_row["state"] != decision.from_state:
raise ValueError(
f"Interview answer requires current state '{decision.from_state}', "
f"observed '{task_row['state']}'."
)
latest = conn.execute(
"SELECT transition_id, to_state, task_id FROM task_transitions "
"WHERE task_id = ? ORDER BY transition_id DESC LIMIT 1",
(decision.task_id,),
).fetchone()
if (
not latest
or latest["transition_id"] != decision.source_occupancy_transition_id
or latest["task_id"] != decision.task_id
or latest["to_state"] != decision.from_state
):
raise ValueError(
"Interview answer occupancy is stale: "
f"observed {latest['transition_id'] if latest else None}, "
f"provided {decision.source_occupancy_transition_id}."
)
duplicate = conn.execute(
"SELECT 1 FROM transition_decisions "
"WHERE task_id = ? AND source_occupancy_transition_id = ? AND question_id = ?",
(decision.task_id, decision.source_occupancy_transition_id, decision.question_id),
).fetchone()
if duplicate:
raise ValueError(
f"Duplicate decision for question '{decision.question_id}' already recorded "
f"in occupancy {decision.source_occupancy_transition_id} for task '{decision.task_id}'."
)
cursor = conn.execute(
"""
INSERT INTO transition_decisions (
task_id, source_occupancy_transition_id, from_state, to_state,
question_id, answer, decision_type, actor, recorded_at
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
decision.task_id, decision.source_occupancy_transition_id,
decision.from_state, decision.to_state, decision.question_id,
decision.answer, decision.decision_type, decision.actor,
decision.recorded_at,
),
)
decision_id = int(cursor.lastrowid)
encoded = json.dumps(bullets, ensure_ascii=False, sort_keys=True)
row = conn.execute(
"SELECT revision FROM interview_plan_outlines WHERE task_id = ?",
(decision.task_id,),
).fetchone()
revision = int(row["revision"]) + 1 if row else 1
now = self._clock.current_time()
conn.execute(
"""
INSERT INTO interview_plan_outlines (
task_id, outline_json, artifact_path, revision, created_at, updated_at
) VALUES (?, ?, ?, ?, ?, ?)
ON CONFLICT(task_id) DO UPDATE SET
outline_json = excluded.outline_json,
artifact_path = excluded.artifact_path,
revision = excluded.revision,
updated_at = excluded.updated_at
""",
(decision.task_id, encoded, artifact_path, revision, now, now),
)
conn.commit()
return InterviewAnswerRecord(decision_id=decision_id, outline_revision=revision)
except Exception:
conn.rollback()
raise
finally:
conn.close()
def get_task_by_worktree_branch(self, branch: str) -> Optional[Dict[str, Any]]:
"""Returns task dict matching worktree_branch, or None."""
self.ensure_schema()
conn = self.get_connection()
try:
row = conn.execute(
"SELECT task_id, state FROM tasks WHERE worktree_branch = ? ORDER BY created_at DESC LIMIT 1",
(branch,)
).fetchone()
if row:
return {"task_id": row["task_id"], "state": row["state"]}
return None
finally:
conn.close()
def validate_task_pipeline_history(self, task_id: str, task_state: str) -> Optional[str]:
"""Validates transition history and violations for pipeline commit check. Returns error string or None."""
self.ensure_schema()
conn = self.get_connection()
try:
# 1. Check transition_violations
viol = conn.execute(
"SELECT violation_id, attempted_from_state, attempted_to_state FROM transition_violations "
"WHERE task_id = ? AND kind = 'ILLEGAL_TRANSITION'",
(task_id,)
).fetchone()
if viol:
return f"Illegal transition violation recorded in control plane ({viol['attempted_from_state']} -> {viol['attempted_to_state']})"
# 2. Check task_transitions against valid_transitions
transitions = conn.execute(
"SELECT from_state, to_state FROM task_transitions WHERE task_id = ? ORDER BY transition_id ASC",
(task_id,)
).fetchall()
if not transitions:
return f"No transition history recorded for task '{task_id}'"
for t in transitions:
f_st, t_st = t["from_state"], t["to_state"]
if f_st == "NONE" and t_st == STATE_INTAKE:
continue
match = conn.execute(
"SELECT 1 FROM valid_transitions WHERE from_state = ? AND to_state = ?",
(f_st, t_st)
).fetchone()
if not match:
return f"Transition '{f_st}' -> '{t_st}' is not in valid_transitions table"
# 3. Check transition chain continuity
first_f, first_t = transitions[0]["from_state"], transitions[0]["to_state"]
if not (
(first_f == "NONE" and first_t == STATE_INTAKE)
or first_f == STATE_INTAKE
or (first_t == STATE_INTAKE and first_f in ALLOWED_TRANSITIONS)
):
return f"Transition history does not begin at INTAKE (started at {first_f} -> {first_t})"
curr_chain_state = first_t
for t in transitions[1:]:
if t["from_state"] != curr_chain_state:
return f"Broken transition chain: expected from_state '{curr_chain_state}', found '{t['from_state']}'"
curr_chain_state = t["to_state"]
if curr_chain_state != task_state:
return f"Current task state '{task_state}' does not match final transition state '{curr_chain_state}'"
return None
finally:
conn.close()
class CryptoAdapter(CryptoPort):
"""Real hashlib-backed implementation of CryptoPort, extracted verbatim from
agent_control.py's former module-level _sha256_file() and record_verification_receipt()'s
inline token-hashing logic (issue-524 Step 6)."""
def sha256_file(self, path: Path) -> str:
"""Computes the SHA256 hex digest of the file at `path`, streaming in 64KB chunks."""
h = hashlib.sha256()
with open(path, "rb") as f:
while chunk := f.read(65536):
h.update(chunk)
return h.hexdigest()
def sha256_hex(self, raw: str) -> str:
"""Computes the SHA256 hex digest of the given string."""
return hashlib.sha256(raw.encode("utf-8")).hexdigest()
class ModelCatalogAdapter(ModelCatalogPort):
"""Real filesystem/JSON-backed implementation of ModelCatalogPort. Step 7 moved only the
file-read methods (load_catalog/load_cheapest); after external post-implementation review
(round 2) found ControlPlane still owned tool-alias resolution, tier-selection strategy,
and fallback logic, this revision moves resolve_recommended_model() and its two former
ControlPlane helpers (_resolve_tool_catalog/_pick_tier_model) here in full — verbatim
behavior, just relocated. Any parse/read error is swallowed and treated as "unavailable"
(returns None from the file-read methods), matching the original bare
`except Exception: pass` behavior exactly."""
def resolve_recommended_model(self, runtime_tool: str, tier: str = "low") -> Dict[str, str]:
"""Resolve a catalog-backed recommendation and fail closed on catalog drift."""
tier = tier.lower()
if tier not in COST_TIERS:
raise ValueError(f"Unsupported capability tier: {tier}")
repo_root = _resolve_repo_root()
cli_refs = repo_root.joinpath(*CLI_AGENT_CATALOG_DIR)
tool_key, catalog_file = self._resolve_tool_catalog(runtime_tool, cli_refs)
cheapest_file = cli_refs / "cheapest_models.json"
cheapest_model = self.load_cheapest(cheapest_file, tool_key)
cat_data = self.load_catalog(catalog_file)
if cat_data is None:
raise ValueError(f"Model catalog is unavailable: {catalog_file}")
selected_model = self._pick_tier_model(cat_data, tier, cheapest_model)
return {
"runtime_tool": runtime_tool,
"tier": tier,
"model_id": selected_model,
}
def _resolve_tool_catalog(self, runtime_tool: str, cli_refs: Path):
"""Resolves tool alias and catalog file path via the shared TOOL_CATALOG_ALIASES
mapping (control_plane/constants.py). Falls back to "copilot" for any
unrecognized tool_key."""
tool_key = runtime_tool.lower()
cli_id, catalog_filename = TOOL_CATALOG_ALIASES.get(tool_key, ("copilot", "copilot-models.json"))
return cli_id, cli_refs / catalog_filename
def _pick_tier_model(self, cat_data: Dict[str, Any], tier: str, cheapest_model: Optional[str]) -> Optional[str]:
"""Pick an available model from the versioned capability tier, preferring strategy hints."""
meta = cat_data.get("_meta", {})
runtime = cat_data.get("runtime", {})
tiers = cat_data.get("capability_tiers", {})
if meta.get("schema_version") != 2 or not isinstance(runtime, dict) or not isinstance(tiers, dict):
raise ValueError("Model catalog does not satisfy schema version 2 capability contract")
models = {
model.get("cli_id"): model
for model in cat_data.get("models", [])
if isinstance(model, dict) and model.get("cli_id")
}
candidate_ids = tiers.get(tier)
if not isinstance(candidate_ids, list):
raise ValueError(f"Model catalog has no capability tier: {tier}")
def available(model_id: str) -> bool:
model = models.get(model_id, {})
return model.get("available") is not False and str(model.get("status", "")).lower() not in DISALLOWED_MODEL_STATUSES
candidates = [model_id for model_id in candidate_ids if available(model_id)]
if not candidates:
raise ValueError(f"No compatible model is available for tier '{tier}'")
strategy = cat_data.get("strategy", {})
preferred = cheapest_model if tier == COST_TIER_LOW else None
if preferred not in candidates:
preferred = next(
(strategy.get(key) for key in STRATEGY_FALLBACK_KEYS if strategy.get(key) in candidates),
None,
)
if preferred:
return preferred
def cost_key(model_id: str):
pricing = models[model_id].get("pricing_usd_per_1m") or {}
return (float(pricing.get("input", float("inf"))), float(pricing.get("output", float("inf"))), model_id)
return min(candidates, key=cost_key)
def load_catalog(self, catalog_path: Path) -> Optional[Dict[str, Any]]:
"""Loads and returns a parsed model-catalog JSON file, or None if missing/unparsable."""
if not catalog_path.exists():
return None
try:
return json.loads(catalog_path.read_text(encoding="utf-8"))
except Exception:
return None
def load_cheapest(self, cheapest_path: Path, tool_key: str) -> Optional[str]:
"""Loads cheapest_models.json and returns the cheapest model id for `tool_key`, or None."""
if not cheapest_path.exists():
return None
try:
c_data = json.loads(cheapest_path.read_text(encoding="utf-8"))
return c_data.get(tool_key, {}).get("model")
except Exception:
return None
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |