End-to-end supervised local workflow#

This guide describes the implementation checkpoint, including retained v0.4.1 and v0.5 interfaces. The README overview is the canonical system diagram. The diagrams below each explain a different view; arrows describe requests, observations or record updates, not grants of authority.

Legend throughout: [A] active and exercised in the qualified project; [D] implemented/configured but disabled; [O] optional or conditional; [U] untested or blocked. Dashed edges denote conditional paths. A component can be implemented and automatically tested while its human interaction remains untested.

Requests, policy and context#

Codex receives the user request, decomposes it, decides which bounded work is suitable locally, and independently accepts the result. LAB supplies durable orchestration, policy, budgets, evidence and review state. The local model proposes text or actions; it cannot grant permissions or make acceptance decisions.

The controller must be independent of the short-lived MCP process. A request persisted through MCP survives closure of the submitting client. The qualified runtime uses a frozen, non-editable package and its own data directory; changing this source checkout does not upgrade a running controller.

A selective Contract records the objective, requirement reference, acceptance criteria, non-goals, repository/base revision, permitted/context/protected files, allowed read/edit/test operations, exact test argv, selected skills/role, dependencies, risk, requested lane, provider/model/identity and limits. The supervisor chooses the scope. Context is supplied explicitly or selected from the declared snapshot; LAB does not give the model unrestricted repository or personal-directory access.

Skills and project profiles are versioned data with hashes and instructions. Catalog checks enforce required reviews, model/context constraints and operation restrictions. Task content, repository text and local output remain untrusted. The protected acceptance inputs are distinct from editable task files.

For exact companion jobs, explicit --model takes precedence over the persistent selector, which takes precedence over the configured project default. Configured roles can otherwise select routed execution; an explicit model selects exact execution. Retained workflow allowlists/budgets are not rewritten by the selector. For selective contracts, the backend/model pair resolves its own qualified profile. A different backend needs its own model and identity; overrides cannot borrow Qwen27's acceptance. See configuration, profiles and role mapping.

Admission verifies identity, profile/settings, skill constraints, qualification, sandbox and host resources. A missing/mismatched model or insufficient headroom returns a failure/reason, not a smaller model, CPU fallback or silent cloud call. Output, attempts and repairs remain bounded; larger tasks are split.

Python decisions in the selective path#

Task lanes and inference providers are separate dimensions#

Ollama can serve both local lanes because model inference and tool execution are different responsibilities. In advisory work the result is text for Codex to evaluate and act upon, including repository explanations, documentation drafts, code review and implementation suggestions. In implementation OpenHands supplies the iterative tool loop: read permitted files, propose/apply permitted edits, invoke approved tests and consume their results. The provider supplies model responses; it neither grants permissions nor independently verifies completion.

Strata's adapter supports text and tool-response transport, but its next intended qualification is Strata inference behind OpenHands. It remains disabled until that exact configuration passes. An advisory success cannot qualify implementation, nor does an implementation failure prevent a separately admitted advisory job. The code does not automatically reroute failed implementation into advisory; Codex may submit a separately bounded advisory contract.

Implementation evidence is inspected only when the effective requested lane is local_implementation. A missing or malformed OpenHands proof cannot disable an otherwise admitted advisory contract, including an explicit advisory override. The lane-independence regression verifies both cases while the corresponding implementation request remains refused.

Sources: lane schema and route, prepare and lane dispatch in execute, ChatProvider, SDK runner and tool registration. These are implemented paths; dated live scope remains in the qualification reports.

Routing diagram#

flowchart TD
    C["Codex: scope, risk, acceptance and requested lane"] --> V["OmniLAB prepare: contract, profile and lane gates"]
    V -->|"direct requested or local gates fail"| D["codex_direct: reasons returned to Codex"]
    V -->|"advisory admitted"| A["local_advisory: direct provider call"]
    V -->|"implementation separately admitted"| I["local_implementation: OpenHands SDK"]
    A --> E["Saved advisory text and evidence"]
    I --> P["Candidate plus protected verification"]
    D --> R["Codex: plan, review and final acceptance"]
    E --> R
    P --> R

flowchart TD
    C["Codex: scope, risk, acceptance and requested lane"] --> V["OmniLAB prepare: contract, profile and lane gates"]
    V -->|"direct requested or local gates fail"| D["codex_direct: reasons returned to Codex"]
    V -->|"advisory admitted"| A["local_advisory: direct provider call"]
    V -->|"implementation separately admitted"| I["local_implementation: OpenHands SDK"]
    A --> E["Saved advisory text and evidence"]
    I --> P["Candidate plus protected verification"]
    D --> R["Codex: plan, review and final acceptance"]
    E --> R
    P --> R

Source: task_contract.route, selective.prepare/execute. Validation: contract tests, flow tests. No provider or framework can accept its own output; Codex's final authority is enforced through trusted review and integration checks, not a model confidence score.

Inference transport diagram#

flowchart TD
    subgraph Box["Restricted implementation sandbox: network none"]
      H["OpenHands SDK"] <--> R["Container loopback Relay"]
      R <--> M["Request / response mailbox"]
    end
    M <-->|"fixed Docker transport; validated requests"| W["Trusted OmniLAB worker"]
    W <-->|"host loopback"| O["Ollama"]
    W -.->|"experimental alternative; separately gated"| S["Strata"]
    A["Advisory execution in OmniLAB"] <-->|"direct host call"| O

flowchart TD
    subgraph Box["Restricted implementation sandbox: network none"]
      H["OpenHands SDK"] <--> R["Container loopback Relay"]
      R <--> M["Request / response mailbox"]
    end
    M <-->|"fixed Docker transport; validated requests"| W["Trusted OmniLAB worker"]
    W <-->|"host loopback"| O["Ollama"]
    W -.->|"experimental alternative; separately gated"| S["Strata"]
    A["Advisory execution in OmniLAB"] <-->|"direct host call"| O

Source: runner Relay, DockerSandbox.read/respond, transport.py, implementation mailbox validation, ChatProvider. Validation: sandbox tests, provider tests. The relay is inside the networkless container. No container-to-host endpoint, host networking or expanded host mount is introduced for Strata.

Advisory handoff diagram#

sequenceDiagram
    participant C as Codex
    participant L as OmniLAB
    participant O as Ollama / Qwen
    C->>L: Bounded question, declared source and acceptance
    L->>L: Check identity, context, policy and resources
    L->>O: Advisory messages, no model-directed task tools
    O-->>L: Proposed explanation, documentation or implementation advice
    L-->>C: Saved answer, usage and evidence
    C->>C: Check source, decide edits, test and review
    C->>L: Trusted review outcome

sequenceDiagram
    participant C as Codex
    participant L as OmniLAB
    participant O as Ollama / Qwen
    C->>L: Bounded question, declared source and acceptance
    L->>L: Check identity, context, policy and resources
    L->>O: Advisory messages, no model-directed task tools
    O-->>L: Proposed explanation, documentation or implementation advice
    L-->>C: Saved answer, usage and evidence
    C->>C: Check source, decide edits, test and review
    C->>L: Trusted review outcome

Source: execute advisory branch, retained Ollama advisory bridge, TaskStore.review. Validation: flow tests. Writing documentation or changing code following an advisory answer is a Codex action; the advisory model has not executed an implementation task.

Verification diagram#

flowchart TD
    H["OpenHands candidate"] --> B["OmniLAB checks permitted changes and protected baseline/candidate tests"]
    B --> R["Codex independently reviews diff, evidence and acceptance coverage"]
    R -->|"accept exact candidate hash"| G["Trusted integration checks base, dependencies and candidate hashes"]
    R -->|"reject, correct or escalate"| X["Retain failed evidence; no integration"]
    G --> T["Run union of checks on assembled feature"]
    T -->|"pass"| I["Apply verified bytes; explicit finalization"]
    T -->|"fail"| X

flowchart TD
    H["OpenHands candidate"] --> B["OmniLAB checks permitted changes and protected baseline/candidate tests"]
    B --> R["Codex independently reviews diff, evidence and acceptance coverage"]
    R -->|"accept exact candidate hash"| G["Trusted integration checks base, dependencies and candidate hashes"]
    R -->|"reject, correct or escalate"| X["Retain failed evidence; no integration"]
    G --> T["Run union of checks on assembled feature"]
    T -->|"pass"| I["Apply verified bytes; explicit finalization"]
    T -->|"fail"| X

Source: make_candidate/verify, review_guard, integrate. Validation: integration tests, bounded tests. The implementation sequence below expands the same path into tool invocations.

Python decision walkthrough#

This walkthrough is source-checked against the development candidate. It is not an autonomous planner. The supervisor creates the nodes and supplies risk, ambiguity, coherent_scope, reversible, category and approval. LAB does not infer those labels from task prose or ask another AI to classify them.

Profile overrides may narrow output, steps, retries, repair/attempt, test, memory/CPU and snapshot ceilings. Context must equal the qualified profile and the safety margin cannot decrease. This is not a general rule that every numeric field is narrowed: inference_deadline_seconds is a separate optional schema field. The generic TaskLimits defaults are 20 steps, 1,024 output tokens, 65,536 output bytes, 16,384 context, zero safety tokens, unspecified self-repair, two attempts, one transport retry, unspecified inference/attempt deadlines, 120-second tests, 2,048 MiB, two CPUs and 16,000,000 snapshot bytes. The personal qualified profiles override these; do not confuse generic defaults with deployment settings. Profile tests cover precedence and ceilings.

Implementation adds requirements beyond advisory: low risk, coherent reversible scope, explicit read/edit/test operations, editable paths, protected acceptance files, checks covering every criterion, enabled implementation, an available restricted sandbox, exact tool/context qualification, and either a qualified backend/identity/category/context tuple, exact scoped contract approval, or an explicit category pilot. A scoped approval does not bypass capability or resource gates. A local request with orchestration=workflow returns to the existing workflow interface. auto does not decompose a selective contract.

These short excerpts are literal decision points, not complete functions:

# task_contract.route: labels come from the supervisor
lane = contract.override_lane or contract.requested_lane
if not contract.supervisor_approved:
    reasons.append('Supervisor contract approval required')

# local_profile.resolve_contract: preserve the qualified context allocation
if limits.get('context_tokens') != approved.get('context_tokens'):
    raise ValueError('Context change requires separate qualification')

# task_store.eligible: finished inference alone cannot unblock a child
if not result or result['review_status'] != 'accepted' or result['accepted_hash'] != result['candidate_hash']:
    return False

memory_admission in selective_resources.py requires a supervisor-verified combined memory plan for implementation; its total includes OS/apps, LAB, runtime, context/cache, sandbox and retained headroom. The separately configured HostGuard also observes whole-host RAM/GPU pressure for local execution. Token fit does not prove RAM fit. The Strata session gate is an additional qualification observer, not an automatic global scheduler or authority to close another app.

Advisory execution builds messages from declared context files and dependency evidence. Qualified native Ollama and Strata use ChatProvider; retained non-native Ollama advisory takes ollama_advisory.run through Bridge. Implementation uses the host mailbox, not direct container network access. correction creates a linked bounded attempt only after trusted review; it cannot expand scope/acceptance and it retains the prior failed cost.

See contracts, flows, bounded execution, provider tests, exact accounting and integration. Retained adaptive selection separately scores caller hints and bounded path signals, resolves existing workflow definitions and checks budgets. It makes no AI classification call. The seven legacy analysis tools, companion exact/routed jobs and selective contracts do not all use that scorer.

Instructional feature example: preserve duplicate readings#

Not a measured run. A user asks: “Add a daily export that retains every sensor reading, including duplicate timestamps, and explain unavailable readings.” Codex keeps product/API decisions and export design itself, then creates three bounded nodes. No autonomous LAB planner created this split.

All nodes need the actual absolute disposable repository, its same 40-character base_revision, an objective, requirement_ref, non-goals (no schema/network/UI changes), an exact qualified backend/model identity, and explicit supervisor_approved=true, risk=low, ambiguity=false, coherent_scope=true, reversible=true. Set orchestration=direct; do not set an override. For the owner's Qwen27 profile, retain 65,536 context, 1,536 output and its other qualified limits. These instructional labels require independent supervisor judgment.

prepare may return local or direct with reasons; it cannot approve missing qualifications. Submission validates/persists the entire graph. The worker waits for the explanation's exact-hash acceptance before claiming the fix, and for the fix's acceptance before review. original_files overlays accepted implementation dependencies into the declared base snapshot; unrelated files remain inaccessible. The fix must preserve its protected check file and produce real candidate bytes, baseline/candidate results, identity, usage and resource evidence. Codex checks duplicate ordering, null handling and regressions independently. Only its trusted hash-bound decision permits dependency-ordered integration and combined checks. The final reviewer model's opinion cannot accept the feature. A rejected or uncertain attempt stays in history and consumes its budget.

Bounded implementation sequence#

sequenceDiagram
    participant C as Codex
    participant L as LAB host
    participant H as OpenHands
    participant P as Selected qualified provider
    participant T as Task tools
    participant V as Verifier
    C->>L: Contract, context and protected checks
    L->>L: Persist, claim, verify identity/limits
    L->>H: Seed declared files in owned container
    loop Bounded model/tool turns
        H->>H: SDK POST to loopback Relay
        H-->>L: request.json read by trusted Docker transport
        L->>L: Persist inference intent, check limits
        L->>P: Host loopback inference request
        P-->>L: Text/tool calls, usage, runtime identity
        L->>L: Validate response, persist receipt
        L-->>H: response.json via trusted Docker transport
        H->>T: Contract-permitted action
        T-->>H: Bounded observation or rejection
    end
    L->>H: Freeze and collect candidate/evidence
    L->>V: Protected baseline/candidate checks
    V-->>L: Check receipts and candidate hash
    L-->>C: Evidence handoff, awaiting review
    alt Independently accepted
        C->>L: Hash-bound review and integration
        C->>L: Final validation and run finalization
    else Local correction within remaining budget
        C->>L: Linked correction job, retain original attempt
    else Failed, blocked or Codex repair
        C->>L: Record rejection/escalation and repair evidence
    end

sequenceDiagram
    participant C as Codex
    participant L as LAB host
    participant H as OpenHands
    participant P as Selected qualified provider
    participant T as Task tools
    participant V as Verifier
    C->>L: Contract, context and protected checks
    L->>L: Persist, claim, verify identity/limits
    L->>H: Seed declared files in owned container
    loop Bounded model/tool turns
        H->>H: SDK POST to loopback Relay
        H-->>L: request.json read by trusted Docker transport
        L->>L: Persist inference intent, check limits
        L->>P: Host loopback inference request
        P-->>L: Text/tool calls, usage, runtime identity
        L->>L: Validate response, persist receipt
        L-->>H: response.json via trusted Docker transport
        H->>T: Contract-permitted action
        T-->>H: Bounded observation or rejection
    end
    L->>H: Freeze and collect candidate/evidence
    L->>V: Protected baseline/candidate checks
    V-->>L: Check receipts and candidate hash
    L-->>C: Evidence handoff, awaiting review
    alt Independently accepted
        C->>L: Hash-bound review and integration
        C->>L: Final validation and run finalization
    else Local correction within remaining budget
        C->>L: Linked correction job, retain original attempt
    else Failed, blocked or Codex repair
        C->>L: Record rejection/escalation and repair evidence
    end

The sequence shows the successful route after admission. Exceptions, malformed calls, truncated output, resource pressure and timeouts retain failure/partial evidence. An intent without a matching receipt is uncertain and must not be blindly replayed. Per-request receipts count failed/retried requests too. A local correction creates a linked job with retained scope and bounded attempts. Codex repairs need independent checks and an explicit outcome; they do not become “accepted without repair.”

Advisory work takes the direct LAB/provider branch and returns text for review. The codex_direct lane hands work back without OpenHands or inference. Strata would replace the inference provider only after separate qualification; it is never a stage between OpenHands and Ollama.

Job lifecycle#

flowchart TD
    A["Submitted request"] --> G{"Valid scope, graph and run?"}
    G -->|"no"| B["Reject before job creation; reason"]
    G -->|"yes; persist effective route"| Q["jobs.state: queued"]
    Q -->|"worker claim"| R["jobs.state: running"]
    Q -->|"cancel"| X["jobs.state: cancelled"]
    R -->|"execution returns"| S["jobs.state: succeeded"]
    R -->|"error / deadline / resource stop"| F["jobs.state: failed"]
    R -->|"confirmed cancellation"| X
    R -->|"lost worker / unresolved restart"| I["jobs.state: interrupted"]
    S --> E["events.state: pending"]
    F --> E
    X --> E
    I --> E
    E -->|"trusted local decision"| V["events.state: reviewed"]
    E -.->|"optional managed callback"| D["events.state: dispatching"]
    D -->|"delivered"| AD["events.state: awaiting_decision"]
    AD -->|"trusted decision"| V
    D -.->|"retryable failure"| RT["events.state: retry"]
    RT -.->|"retry"| D
    D -.->|"blocked / unknown"| U["blocked / uncertain"]
    U -.->|"not delivered"| E
    U -.->|"delivered"| AD
    V --> N["runs.state: validating"]
    N -->|"accepted jobs, checks, integration"| C["runs.state: completed"]
    N -->|"unsuccessful finalization"| Z["runs.state: blocked"]
    N -->|"whole-run cancellation"| Y["runs.state: cancelled"]

flowchart TD
    A["Submitted request"] --> G{"Valid scope, graph and run?"}
    G -->|"no"| B["Reject before job creation; reason"]
    G -->|"yes; persist effective route"| Q["jobs.state: queued"]
    Q -->|"worker claim"| R["jobs.state: running"]
    Q -->|"cancel"| X["jobs.state: cancelled"]
    R -->|"execution returns"| S["jobs.state: succeeded"]
    R -->|"error / deadline / resource stop"| F["jobs.state: failed"]
    R -->|"confirmed cancellation"| X
    R -->|"lost worker / unresolved restart"| I["jobs.state: interrupted"]
    S --> E["events.state: pending"]
    F --> E
    X --> E
    I --> E
    E -->|"trusted local decision"| V["events.state: reviewed"]
    E -.->|"optional managed callback"| D["events.state: dispatching"]
    D -->|"delivered"| AD["events.state: awaiting_decision"]
    AD -->|"trusted decision"| V
    D -.->|"retryable failure"| RT["events.state: retry"]
    RT -.->|"retry"| D
    D -.->|"blocked / unknown"| U["blocked / uncertain"]
    U -.->|"not delivered"| E
    U -.->|"delivered"| AD
    V --> N["runs.state: validating"]
    N -->|"accepted jobs, checks, integration"| C["runs.state: completed"]
    N -->|"unsuccessful finalization"| Z["runs.state: blocked"]
    N -->|"whole-run cancellation"| Y["runs.state: cancelled"]

This diagram uses stored values, with table prefixes to distinguish records. Selective policy/capability refusals can persist a codex_direct job that returns its reasons without inference; invalid scope/graph/run raises before submission. CLI/MCP contract_requests validates the graph before prepare, and durable submission checks it again against existing nodes. Resource/identity checks recur at dispatch; a previously local route can fail there. The finalization arrows summarize guards; unresolved events/jobs prevent finalization instead of automatically advancing. Callback reconciliation may return to pending or awaiting_decision depending on recorded delivery. A job's succeeded means execution returned, not that its patch passed checks or Codex accepted it. Review is a separate record, not an invented job state.

Pause prevents new claims; it does not cancel active work. The worker serializes jobs and checks dependencies, reservations and admission again. The SQLite reservation coordinates this configured store, not every possible LAB deployment on a machine. Competing resident models are checked separately.

Restart recovery reconciles durable results and owned processes. Legacy workflow receipts can complete delivery without another inference; an unfinished native advisory becomes interrupted with uncertainty retained. An implementation recovery inspects the owned executor and collects recoverable evidence rather than blindly starting another agent. Only demonstrably owned processes can be stopped.

There is no persisted expired companion job state. Selective attempt/inference deadlines fail bounded execution. Retained workflow leases expire to handed_off with an interrupted reason, retain charged budgets and reject late ownership. Ollama's 120-second keep-alive controls model residency, not job acceptance or reservation expiry. Uncertain inference cancellation requires trusted reconciliation; see recovery and operations.

Trust boundaries and data movement#

flowchart TD
    C["[A] Codex supervisor<br/>Cloud services"]
        CFG["Private config<br/>Immutable LAB runtime"]
        L["[A] Trusted host LAB<br/>Fixed Docker transport"]
        E["Evidence and independent<br/>verification receipts"]
        CFG -->|"policy and pins"| L
        L -->|"candidate and checks"| E
    subgraph Box["Restricted container"]
        H["[A] OpenHands SDK<br/>Container-local Relay"]
        T["[A] Editor and exact test argv"]
        W["Declared writable files"]
        P["Protected tests and baselines"]
        H <-->|"tool requests / observations"| T
        T -->|"permitted writes"| W
        P -->|"read only"| T
    end
    O["[A] Host Ollama / Qwen27"]
    S["[D/U] Alternative Strata<br/>Disabled and unqualified"]
    C <-->|"bounded contract / review evidence"| L
    L <-->|"files and JSON mailbox<br/>fixed Docker transport"| H
    L <-->|"host loopback HTTP<br/>model messages / response"| O
    L -.->|"requires separate qualification"| S

flowchart TD
    C["[A] Codex supervisor<br/>Cloud services"]
        CFG["Private config<br/>Immutable LAB runtime"]
        L["[A] Trusted host LAB<br/>Fixed Docker transport"]
        E["Evidence and independent<br/>verification receipts"]
        CFG -->|"policy and pins"| L
        L -->|"candidate and checks"| E
    subgraph Box["Restricted container"]
        H["[A] OpenHands SDK<br/>Container-local Relay"]
        T["[A] Editor and exact test argv"]
        W["Declared writable files"]
        P["Protected tests and baselines"]
        H <-->|"tool requests / observations"| T
        T -->|"permitted writes"| W
        P -->|"read only"| T
    end
    O["[A] Host Ollama / Qwen27"]
    S["[D/U] Alternative Strata<br/>Disabled and unqualified"]
    C <-->|"bounded contract / review evidence"| L
    L <-->|"files and JSON mailbox<br/>fixed Docker transport"| H
    L <-->|"host loopback HTTP<br/>model messages / response"| O
    L -.->|"requires separate qualification"| S

The SDK posts to http://127.0.0.1:8765/v1/chat/completions inside the container. Its Relay writes /exchange/request.json and waits for the matching response.json. The trusted host worker reads/responds using fixed Docker transport operations, then makes the host-loopback Ollama request. There is no container network route to host Ollama and no shared host-directory mount.

This is the corrected, source-checked integration of Qwen27's documentation draft: the mailbox is not a network proxy exposed to task tools. OpenHands manages the tool loop, the model proposes actions, and LAB enforces the surrounding contract and collection limits. The diagram includes the tool observations omitted by the local draft. Codex independently reviews candidate bytes and acceptance; publishing credentials and acceptance authority never enter the worker context.

The accepted container is nonroot (UID 10001), read-only except bounded tmpfs, networkless, capability-dropped, and has no Docker socket, host shell, personal directories, SSH keys, browser profiles or Codex authentication. Protected tests and original baselines are not writable. Independent verification uses separate baseline/candidate sandboxes before trusted integration. Task tools have no outbound network; the complete Codex-supervised workflow is not offline.

Where information lives#

Paths below are source-defined layouts relative to configuration, not public copies of private machine paths. config.load_config selects explicit --config, then LAB_CONFIG, then current-directory config.toml. Relative paths resolve against that TOML. The default data directory is under LOCALAPPDATA/LocalAgentBridge; the qualified deployment uses a private dedicated directory instead.

Acceptance inputs and original checkouts are retained independently. Source/Git snapshots exclude uncommitted changes unless the trusted supervisor explicitly freezes and reviews those bytes. Evidence bundles, runtime DBs, logs, private configuration and model assets are excluded from the public source allowlist.

Accounting and observability#

flowchart TD
    P["[A] Local provider response or durable receipt"] --> U[("Usage rows<br/>companion/usage/usage.sqlite3")]
    C["[A/O] Codex session or supported telemetry events"] --> I["Explicit metadata import / existing collector"]
    I --> D["Cumulative deltas; duplicate protection<br/>one coverage stream per session/model"]
    D --> U
    B["[A] Trusted usage-bind CLI<br/>whole session or whole turn/job"] --> V["Validate identity and reject conflicts"]
    V --> T[("usage_bindings")]
    U --> R["[A] Separate accounting report utility"]
    T --> R
    R --> K["Implementation / evaluation / operating / unattributed<br/>null-aware input, cached subset, output, other fields"]
    K --> S["[U] B minus H only with complete matched coverage<br/>Operating savings NOT ESTABLISHED"]
    P --> J[("Job result and contract evidence")]
    J --> O["[A/U] Dock status, elapsed time, available local usage<br/>human interaction untested"]
    C -.->|"optional managed callback review_usage"| J

flowchart TD
    P["[A] Local provider response or durable receipt"] --> U[("Usage rows<br/>companion/usage/usage.sqlite3")]
    C["[A/O] Codex session or supported telemetry events"] --> I["Explicit metadata import / existing collector"]
    I --> D["Cumulative deltas; duplicate protection<br/>one coverage stream per session/model"]
    D --> U
    B["[A] Trusted usage-bind CLI<br/>whole session or whole turn/job"] --> V["Validate identity and reject conflicts"]
    V --> T[("usage_bindings")]
    U --> R["[A] Separate accounting report utility"]
    T --> R
    R --> K["Implementation / evaluation / operating / unattributed<br/>null-aware input, cached subset, output, other fields"]
    K --> S["[U] B minus H only with complete matched coverage<br/>Operating savings NOT ESTABLISHED"]
    P --> J[("Job result and contract evidence")]
    J --> O["[A/U] Dock status, elapsed time, available local usage<br/>human interaction untested"]
    C -.->|"optional managed callback review_usage"| J

The close-out added whole-unit attribution to the existing accounting store; it did not replace the active controller or automatically instrument every cloud phase. contract-usage-bind associates a cloud session/turn or local run/job with an accounting run/task and category. Conflicting/overlapping bindings fail; repeating an identical binding is idempotent. No fractional turn allocation exists.

Reports separate implementation/setup investment, evaluation overhead, normal operating tasks and unattributed usage. Shared controller/reporting work must remain visible as a whole labeled unit or unattributed coverage. Retrying, repairing, failing and falling back do not erase the preceding costs. Source/session/turn/request IDs and the report cutoff identify coverage.

Cloud input includes cached input; output includes reasoning where reported. Cached-input, cache-write and reasoning counters stay separate, never added again to input/output totals. Missing counters are unknown, not zero. Duplicate cumulative events add no tokens. Overlapping rollout/telemetry streams are selected, not summed. Local input/output are actual provider measurements; serialized-byte context bounds are admission estimates, context capacity is a limit, and maximum output is an allowance.

The dock reads companion job/results and evidence, including available local usage and optional callback review_usage. It does not query attribution category totals or show live measured savings. Presentation labels distinguish observed, estimated and unavailable metrics; a derived display label such as “verifying” is not an extra persisted job state.

Operating savings require equivalent independently accepted work: complete Codex-only cloud usage B, and complete hybrid cloud usage H including planning, dispatch, review, every local retry, cloud repair and fallback. Net avoided cloud tokens are B − H; percentage is 100 × (B − H) / B for B > 0. Negative values stay negative. Report identical starting snapshots, requirements, acceptance, Codex model/settings and cache conditions, with no solution leakage between runs.

The retained generation-only baseline and shared hybrid supervisor turns do not isolate complete matched B/H. Whole-unit bindings fix association, not missing historical coverage. Savings remain not established; no new comparison was run for documentation publication. A future isolated comparison supports its sample only. Local tokens are not cloud tokens saved, and token reductions do not imply a lower subscription bill. Accounting methodology preserves historical totals as dated windows, not current lifetime usage.

Worked example from accepted evidence#

During the 2026-10-10 close-out, the supervisor requested a short operator paragraph about complete usage attribution, retries, unknown counters and valid savings claims. Context was a bounded source-backed excerpt from usage_report.py plus the frozen accounting facts; the task did not expose the repository or publishing credentials. This was local_advisory through the existing controller and qualified Ollama/Qwen27 profile, not an OpenHands implementation task.

LAB persisted the task, exact identity/profile, admission, provider receipt and candidate hash. The model returned a 106-word paragraph in one inference attempt: 291 input / 130 output tokens; cached input unavailable. Codex independently compared each assertion against the implementation and acceptance criteria, accepted it without repair, integrated it unchanged in close-out attribution, recorded review coverage and finalized the run.

The sanitized opening is: “Operators attribute usage by binding complete sessions, turns, or jobs to specific tasks and categories.” The rest remains at the linked canonical location. This is actual accepted documentation work, not a hypothetical tool run or evidence of net savings. The contribution ledger also records the separate, corrected transport draft used for this guide. Private job/run receipts remain private; public text records compact outcome and usage, not raw prompts, runtime databases or machine paths.

Qualified personal profile#

This is the 2026-10-10 qualification example for this project checkout. It is not a mandatory public default, a newly run comparison, or authorization for other repositories. The active configuration and explicit overrides are preserved. Qualification evidence and operations retain the detailed history.

Runtime binding checks the installed version, digest, quantization and template, then actual loaded context, runner identity/flags and positive GPU allocation. Unsupported settings or mismatch fail safely before returning tool calls. The context limit is capacity, not evidence that each prompt consumed 65,536 tokens.

Admission requires 6 GiB host RAM available. The guard stops below 2 GiB immediately, below 3 GiB for 15 seconds, above 11,776 MiB GPU allocation or on unavailable GPU diagnostics. One inference workload is admitted; switching providers cannot leave unadmitted competing models resident. The sandbox retains 2 GiB/no-swap, two CPUs, 128 PIDs, bounded tmpfs and collection. Each task allows eight inference requests, two error-recovery cycles, two supervisor-authorized attempts, zero transport retries, 15-second test commands, 16 KiB outputs and a 30-minute attempt ceiling. These are ceilings, not claims of actual usage.

Current Strata protocol/selection changes and current upstream inspection are recorded in the upgrade report. The final patched 0.1.43 runtime with engine-only mapped-page release passed fresh A/B. Idle memory remained below admission; a competing runtime later triggered the whole-GPU guard. OpenHands/Strata and live safety checks remain unqualified. The next-session readiness plan adds model-free loading-runner checks and distinguishes memory from context-admission blockers; no further inference is authorized. The following 2026-10-10 inventory remains historical.

That historical inventory had an implemented adapter but no qualified runnable installation or compatible loaded weights in the bounded inventory. The inspected upstream commit fb58e0dbc8399662c0e47c76578c6e878b14f6cf targets Flash-Next variants; it does not qualify dense Qwen27. The standard engine 0.1.41 CUDA 13 driver requirement is unmet by recorded driver 560.94, and the CUDA 12 alternative remains unqualified. No proposed model payload was downloaded. The disabled http://127.0.0.1:8080 example is not an available service. See Strata blockers and licenses; none blocks the accepted Ollama/OpenHands path.

Operation, rollback and validation#

The canonical operator guide contains start, stop, status, inventory, dock and cancellation commands, private installation record locations, ownership safeguards and rollback. Use the frozen runtime's Python and the absolute private project-config path. CLI --help is safe to inspect; do not restart or replace the active controller just to read this guide.

For a generic bounded advisory, after creating a run, the supported shape is:

python -m localagentbridge --config LOCAL.toml companion create
python -m localagentbridge --config LOCAL.toml companion submit --run RUN_ID --request task.json --model EXACT_TAG
python -m localagentbridge --config LOCAL.toml companion status --run RUN_ID

RUN_ID and EXACT_TAG are placeholders; use the actual creation result and installed identity. See task example. Implementation uses contract commands and contract example, with separate trusted review, protected verification and explicit integration. A locally successful candidate is not permission to publish.

Rollback pauses admission, resolves/cancels owned work, shuts down the owned controller and restores the saved prior configuration/selector, retaining models, DBs, accepted patches and history. The private rollback helper refuses unresolved work and archives the current configuration. The earlier disposable rollback check is evidence; publication does not execute rollback or restart services.

The close-out's clean source validation recorded 591 passed / 1 skipped. Its 180 extracted-wheel checks overlap that suite and are not added to it. Those are historical close-out results. The historical 2026-10-12 Strata adapter pass changed runtime source and recorded: 614 passed / 1 skipped. See the current implementation report for package, diagram and publication checks.

The manual ledger has exactly 11 human rows, none fully accepted (the owner confirmed launch and some selections only): package/launch/rollback; model/backend/usage; override persistence; idle → running → awaiting review → completed; keyboard/focus/ DPI; hide/reopen/cancel; retained workflow controls; conditional managed callbacks; OpenHands isolation/tool round trip; stale/forged acceptance and recovery; conditional resources/matched pilot. Automated or earlier live runtime evidence does not mark those human checks passed. Preserve its Test | Tested? | Result | Issue registered | Evidence/notes format.

Source map#

The exact-accounting addition below is default-off and offline-verified only. It runs within the existing admission arrow, so no diagram topology changed. Successful final-patch Strata A/B remains historical; C, live safety checks and general routing remain unqualified. Diagram rendering evidence is reused.

The README's host inference adapter executes inside selective.execute / implementation, not a separate inference service. DockerSandbox.read/respond performs fixed host-side transport; the SDK's Relay uses container loopback only. The trusted review arrow is CLI TaskStore.review, never an MCP/model acceptance tool. CompanionDock.refresh_models separately reads backend metadata; select_default stores the exact future choice, while pause/cancel update control state. The older telemetry widget reads telemetry.Store through dashboard_state.snapshot; it is separate from the job dock.

Each link identifies implementation, not authority for a local agent. Tests are automated unless the linked qualification/ledger explicitly says otherwise.

See architecture for retained MCP/adaptive internals, safety, troubleshooting, manual testing and upgrade.