Terms and command entrypoints¶
Use this appendix with an actual problem; the source course is not a prerequisite. Current installed --help owns command arguments. This page gives entrypoints and judgment conditions, not a complete CLI reference or automatic mutation permission.
Read before deciding to change state¶
Identify the exact existing registry, runtime root, Goal and Todo. Do not guess from display names or substitute teaching labels T1/M1 for real IDs. These commands do not request completion, acquisition or settlement. Set four variables first; absence stops the commands:
: "${REGISTRY:?Set the existing registry path}"
: "${RUNTIME:?Set the existing runtime root}"
: "${GOAL:?Set the exact goal id}"
: "${TODO:?Set the exact todo id}"
loopx --registry "$REGISTRY" --runtime-root "$RUNTIME" --format json \
todo list --goal-id "$GOAL" --todo-id "$TODO"
loopx --registry "$REGISTRY" --runtime-root "$RUNTIME" --format json \
task-lease inspect --goal-id "$GOAL" --todo-id "$TODO"
Reads can start the managed runtime; separate responses are not one atomic snapshot. Check identity, source, time and available revision in each. Report missing information instead of inventing approved, open or zero. To determine what happened to an actual operation, consult its own receipt too.
Relevant quota should-run --codex-app paths can create heartbeat receipts. refresh-state writes back; acquisition, renewal, settlement and scheduler ACK have execution conditions. They are not the two observational commands above and do not belong in an unbounded diagnostic retry loop.
Route symptoms to an owner¶
Find the first relationship lacking evidence rather than clearing the Goal. This is a reading route, not a new automatic repair machine.
| Symptom | Facts to obtain first | Rule and operating entrypoint | Completion or stopping condition |
|---|---|---|---|
| Page and Todo disagree | Same object's source, mode, revision/time and projection | State, projection repair | Restore the source and reread; display does not take over authority |
| HTTP succeeded; execution is unclear | Original request, operation receipt and current source | Workspace pause case | Confirm that operation; disagreement alone does not prove cause |
| Earlier acquire succeeded; writes now fail | Current owner/key/version, mode and Todo state | Authority | Obtain legal current proof, or stop if work ended |
| External request timed out | Original operation identity and provider readback | Recovery | Act on supported committed/absent results; retain unknown responsibility |
| Writeback exists; records remain incomplete | Original settlement state and outstanding action | Settlement | Complete missing records without repeating artifact or debit |
| Independent work appears during an original-Turn wait | Original binding, blocked writeback and later candidates | Wait closeout | Follow the installed contract to close out before new selection |
| Quiet Monitor or repeated replan | Due state, target, current lane, selectable work and Host | Observation | Explain actual waiting or restore its execution surface |
| Old CI is green; current code changed | Actual artifact revision, affected requirements and evidence | Changed evidence | Support current conclusions without erasing history |
| Green branches cannot be delivered together | Artifacts, recipient-adopted revisions and integration checks | Handoff and integration | Close integration and acceptance responsibility |
| Artifact generated; recipient did not receive it | Target, route, send/delivery readback and authority | First delivery | Complete required return or identify remaining responsibility |
Public feedback should retain minimal reproducible versions, error codes and public-safe references, not live registries, credentials, raw transcripts or private run records. When evidence is insufficient, name the unknown conclusion, missing readback and confirming owner. Destructive test injection is not a live recovery procedure.
Requirement one: state outlives context¶
| Term | Distinction to preserve |
|---|---|
| Goal / Acceptance | Objective identity and observable acceptance, not one Todo's status |
| Source / Projection | Owning facts and rebuildable views; legacy Markdown's role depends on mode |
| Evidence / Receipt | Support for a conclusion versus an accepted-operation record; both need correct binding |
| Kernel | Generic transition owner, not the owner of every external system's reality |
See state. Information in a prompt alone does not prove durable lifecycle writeback. Persisted chat also does not automatically become current authority.
Requirement two: identify interrupted work¶
A Todo identifies work; the frontier supplies candidates under current constraints; Turn/operation identity binds execution and recovery. Historical receipts differ from new execution eligibility. Artifact revision, provider revision and lease version/epoch cannot substitute for one another; see revision bases.
Requirement three: current executor and scope¶
Agent identity denotes a lane, not a Host. Vision describes an applicable per-Agent route. Claim expresses assignment; leases participate in proof on applicable writers and modes; Gates cover named decisions; Hosts supply execution and waking. These do not imply one executor for the whole system or an OS sandbox. See work graphs.
Requirement four: bounded, observable consumption¶
Quota participates in admission and internal accounting. Monitors retain targets and observations. Scheduler/backoff arranges timing; Hosts or integrated event channels perform waking. Replan changes the route, not just an interval. No-spend is not free actual resources. See observation ownership.
Words outside the four requirements¶
Capability describes a caller outcome contract; Provider supplies implementation or external access; Extension manages independent package installation, activation and versions. Installed, doctor-ready, Goal-configured and currently authorized are different facts. See placement and lifecycle.
Core command quick index¶
| Need | Entrypoint | Boundary |
|---|---|---|
| Inspect installation and prerequisites | loopx --version, loopx doctor |
Does not prove a delivery succeeded |
| Inspect connection and status | loopx registry, loopx status, loopx history |
Verify actual registry/Goal; display may be bounded |
| Read an exact Todo | loopx todo list --goal-id <goal-id> --todo-id <todo-id> |
Absence from a display is not absence of work |
| Compact a work list | loopx todo list --goal-id <goal-id> --thin --format json |
Bounded display is not the whole candidate set |
| Inspect a lease | loopx task-lease inspect |
Observation does not acquire new proof |
| Read Agent evidence | loopx history --goal-id <goal-id> --agent-id <agent-id> --limit 30 |
Separate history from current facts |
| Request admission | loopx quota should-run |
Read the full contract; relevant Host paths can record receipts |
| Inspect a managed Turn journal | loopx turn inspect-journal |
Preserve original Turn key; diagnosis does not recover |
| Discover configuration and capabilities | loopx capability list/show, loopx configure-goal |
Separate reads without setting flags from execution |
| List independent packages | loopx extension list --format json |
Visibility is not current run eligibility |
The todo list --thin option added in v0.5.4 is an explicit bounded projection without changing default selection, ordering, quota, or lifecycle semantics. Use exact reads for details instead of changing display limits to bypass business checks.
Project onboarding and actual delivery¶
loopx connect --dry-run
loopx start-goal --guided --project . \
--goal-id <goal-id> --agent-id <agent-id> \
--goal-text "<goal text>" --host-surface codex-app
These are preview entrypoints. Confirm actual connection writes and subsequent packet actions separately. Select codex-cli-tui for that actual Host, not an invented one. Omitted identities may lead to selection gates; an existing lane is not implicit takeover. Follow onboarding and first delivery.
Scheduler convergence entry¶
When a packet requires Host apply, apply its current recommendation and read the result before executing the bound ACK:
This is a command shape, not copy-ready arguments. Use full ack_hint.cli_args. Do not fabricate success after failure or unknown outcome; use the applicable failure_hint.cli_args. A Host already confirmed to match the desired cadence may only need ACK, not a redundant update. See budget and observation.
Safe updates and rollback¶
Confirm installation owner, target release and plan before authorizing apply. Ordinary users should not default to --ref main. Updating the CLI does not establish that every Host, Provider and existing Goal migrated. Recheck skills, state, Host readback and enabled Extension readiness for the surfaces actually used.
For backup, preview before execution:
Backups are private recovery material and may contain sensitive runtime state; do not commit them. Before loopx update --rollback previous, inspect current help and verify that the installation supports that recovery. Reverting the program does not necessarily revert independent packages, written state formats or external effects. Those retain their own owners; see recovery and compensation.
Extension lifecycle¶
init → install package → install preview → install --execute → doctor/readback
→ run valid input → disable/enable → upgrade/rollback → reread
Do not reinstall an already installed Extension. Use an isolated state file and one Python environment for the complete scaffold and lifecycle exercise. rollback_available=false differs from a valid target whose doctor fails. Retaining old activation metadata does not guarantee the old entrypoint remains executable.
Protocol index¶
| Topic | Primary entrypoint |
|---|---|
| Goal, identity and Host activation | Goal command |
| Source/projection and long-running work | Long-horizon state |
| Agent-scoped history | Evidence ledger |
| Retired Todo event API | Retired event source |
| Active-state read model | Structured projection |
| Work graphs, Gates and peers | Task graph, Decision scope, Peer runtime |
| Vision and route changes | Vision/replan |
| Explicit managed turns | LoopX Turn, Turn envelope |
| Host, Session and writeback | Host integration, Session projection, Controlled writeback |
| Concurrent write bases | Local write correctness |
Protocol pages have versions and implementation status. Accepted RFCs, experimental contracts and shipped behavior are not interchangeable. Advanced source comparisons use fixed commits; verify that your checkout contains the implementation before running it. Enter Course exercises and the contribution path when preparing a rule change.