rein-aharness/SCOPE.md

SCOPE

Capability snapshot: 2026-09-04. INTENT.md states the destination and boundaries; this file records what the repository currently implements and has evidence for.

One-liner

rein-aharness is the Claude-Code-CLI-oriented rein that claims scheduled Activity Core work, routes versioned execution profiles through Glas, and retains a legacy set of local task executors for unattended repository work.

Implemented capability

Intake and lifecycle

• The primary production intake is the Activity Core ops_run REST queue. The worker filters and claims rows, heartbeats their lease, and completes or fails them with normalized result data.
• A queued harness_profile_ref is authoritative. The worker carries its allowlisted attribution refs into a Glas ExecutionRequest, uses governed actor agt, retains bounded execution evidence, and never falls back to a legacy approach after profile refusal or failure. A separately typed queued repository grant is parsed strictly and cannot cross a profile-absent route.
• Profile-absent rows use the coexistence registry in approaches.py. Dispatch requires an explicit, non-expired AGENT_HARNESS_LEGACY_APPROACHES_UNTIL date; unmatched or disabled routes fail visibly. JSON task files remain available for local development, and issue-core polling remains as a legacy compatibility path.
• The production claim loop is a single-concurrency user systemd service on railiance01. Claim failures use the configured poll interval and active runs receive lease heartbeats.

Execution paths

• Generic local TaskSpec runs resolve instance policy, optionally load a kaizen-agentic persona bundle, invoke Claude Code in the target checkout, impose a wall-clock timeout and named Claude tool allow-list, and require a new Git HEAD before reporting success.
• Local task files may carry an explicit v1 repository_grant. These runs validate commit ancestry/count, changed paths, clean post-state, protected Git metadata, and remote refs under the repository transaction before success.
• Optional Claude stream JSON is reduced to tool/hook audit events and can be reported to State Hub.
• Versioned profiled rows delegate profile, rein, model, tool, sandbox, and teardown decisions to Glas/sand-boxer. rein-aharness owns the queue adapter, repository transaction/acceptance, external metrics, and durable terminal-close delivery—not the meta-framework or sandbox implementation.
• Legacy structured executors produce Freedom Intelligence daily research briefs, Binky daily/weekly briefs, deterministic mailbox scans, and mailbox triage. The LLM-backed structured paths use the llm-connect HTTP service; mailbox credential acquisition is a bounded OpenBao/AppRole pre-step.
• A deterministic smoke path can clone a controlled sandbox repository, commit SMOKE.md, optionally push it, and report evidence without invoking Claude.

Declarative policy and reporting

• .kaizen/schedule.yml parsing and validation cover cadence, enabled state, blueprint name, green/blue lane, named tool profile, token budget, and harness-major pin. Strict validation requires the runtime fields for enabled instances.
• The local profile registry contains green-commit-only and blue-mail-triage. Unknown profiles fail closed. Both restrict the Claude session to repository read/edit operations and selected local Git commands; lane itself is metadata and consistency validation, not an OS security boundary.
• Grant-absent compatibility runs can append repository-local kaizen metrics. Granted runs instead require private, durable external metrics with a projection descriptor so accepted checkouts remain clean. State Hub progress/tool/token events and task closing remain best-effort.
• Profiled terminal closes are written to a private outbox before delivery. Pending close-only work replays before another claim; exact Activity Core repeats reconcile, permanent machine-distinct conflicts quarantine, and operator status/replay commands expose unresolved evidence.
• llm-connect HTTP errors retain only bounded, allowlisted provider diagnosis.

Packaging and deployment

• The Python package and CLI are version 0.1.0; Glas and sand-boxer are optional sibling runtime dependencies.
• The host deployment includes a user-service claim loop and helpers for resolving in-cluster Activity Core, llm-connect, and State Hub services.
• A container image and hardened Kubernetes manifests exist. The Kubernetes Deployment currently runs sleep infinity; it validates packaging and image availability but is not the production claim worker.

Current evidence and limits

• The historical 2026-07-26 proof exercised a real Claude CLI session and commit through the then-current coarse Glas rein contract. The deterministic Railiance smoke also proved clone, commit, optional push, and Hub reporting.
• The current profiled queue adapter is deployed at c633291. Production run ededc939-266f-473c-8386-ffd3f027f5f0 proved profile/ref preservation, governed actor mapping, resolution, normalized failure, and sandbox teardown. It failed closed at session_start before Claude dispatch or commit because executable bwrap reachability, mounted rein runtime, and model egress remain with upstream residual GLAS-IN-0002.
• Direct legacy agent sessions rely on Claude Code's own tool mediation and the host checkout. They are not an OS-level sandbox and do not prove that no push/network activity occurred after the run. Unattended mutation now takes a process-safe repository lock (ADR-002 / T02).
• Explicitly granted local task files and profiled Activity Core rows have full repository acceptance and clean external metrics. Source compatibility is pinned to Activity Core b63131e / schema migration 0010; production must deploy that schema/API contract before a granted definition is enabled.
• The worker is sequential and repository mapping is host configuration. There is no multi-worker repository lease, per-tenant process isolation, generic credential broker, or tenant onboarding API.
• Freedom Intelligence and Binky approach matching, output formats, event names, mailbox paths, and one default push behavior are tenant-specific compatibility code. They are implemented capability, but conflict with the intended generic-runtime boundary and should not be the pattern for new tenants.

Explicit boundaries

• Scheduling and activity definitions belong to Activity Core.
• Blueprint authoring and improvement loops belong to kaizen-agentic.
• Profile routing and rein selection belong to Glas.
• Sandbox lifecycle and isolation belong to sand-boxer.
• Provider abstraction belongs to llm-connect.
• Durable work history and decisions belong to State Hub; agent memory remains in the consuming repository. Granted-run metrics remain external until a separately granted kaizen projection commits them to the instance.

Orientation

• Purpose and target boundaries: INTENT.md
• Intent-versus-capability assessment: history/2026-08-23-intent-scope-gap-assessment.md
• Runtime architecture: docs/architecture.md
• Production claim loop: docs/ops-run-claim-loop.md
• Deployment: deploy/README.md
• Completed work records: workplans/

Owner runtime reuse update — 2026-10-19

The repository includes the credential-free owner_rehearsal.rehearse API and owner renewal support tracked in HARNESS-WP-0008. Reuse these existing paths for installation verification and bounded attempts; do not introduce a parallel launcher. Custodian's October 17 native-runtime-install-r3 execution receipt proves installed artifact f59959b6… passes offline rein/Glas/Claude startup, unchanged full digest and process cleanup. Revision 2's earlier failed rehearsal is preserved. This has zero model calls and no credential/configuration reads. Remaining spend-memo lifecycle, owner renewal/pin updates, fresh native approvals and bounded successful model/tool acceptance remain in HARNESS-WP-0008-T07. Actual Custodian interactive isolation remains a separate consumer obligation.

Staged work-record generation — 2026-10-19

The repository explicitly opts into the shared staged work-record generator via .generated-work-records.json and its dedicated .generated-work-records.mk. make generated-work-records uses the existing State Hub renderer through the Custodian adapter, stages only WORK-RECORDS.md, and refuses unreconciled unstaged index edits. make generated-work-records-check checks without writes. The shared commit hook retains its generated-only guard and repository-specific scanner routing; meaningful source commits regenerate the index before any configured scan. Generation performs no Hub calls, commits, pushes, credential access or live changes. Source inventories and other generated artifacts retain their owners.

Local orientation brief policy — 2026-10-19

.custodian-brief.md is a local, ignored State Hub orientation snapshot. Its existing bytes remain available for offline session startup; refreshing it does not require a Git commit. Authored workplans and the generated WORK-RECORDS index retain their existing source and staged-generation contracts. No runtime or credential change follows from this repository hygiene policy.