RFC: TRACK REMOTE GOAL ENGINE
=============================
Status: DRAFT / FOR DISCUSSION
Scope:  Infrastructure first. Runtime selected separately.

1. PURPOSE
----------
Run one goal at a time through an agent on a separate machine.
Use Track as the durable record of what was requested, what happened,
and what evidence supports the result.

The first milestone is a working, observable execution loop.
The 250M training campaign is a later workload, not the first test.

2. SYSTEM BOUNDARY
------------------

  YOU                         TRACK                    REMOTE MACHINE
  ---                         -----                    --------------
  Define goal -------------> Goal + completion criteria
  Review progress <--------- Status history <--------- Runtime adapter
  Answer a blocker --------> User response ----------> Agent
  Request stop ------------> Stop flag --------------> Supervisor
                             ^                        |
                             |  claim / heartbeat /   |
                             +------ progress --------+

  Track owns:                 Remote engine owns:
  - durable goal state        - local workspace
  - one active slot/account   - chosen agent/runtime
  - progress history          - execution and tools
  - scoped credentials        - process supervision
  - links to Track runs       - reporting evidence

The remote engine initiates outbound HTTPS requests. Track does not
SSH into the machine or execute the goal text inside its web server.
An engine credential is scoped to the owner's goal protocol.

3. WHAT A GOAL MUST SAY
----------------------
- Outcome: what should be different when the work is finished?
- Completion criteria: which checks demonstrate that outcome?
- Resources: repositories, workspace, data and available tools.
- Constraints: allowed actions, budgets and required approvals.
- Evidence: files, commits, test results or Track run IDs to report.

Example first goal:
  Inspect a fixture repository, run its existing tests, and report
  the command, result and relevant file paths. Do not deploy, start
  training or allocate paid resources.

The prototype stores these fields together as objective text.
Structured fields and enforcement of budgets are future decisions.
A sentence in a goal is not a technical permissions boundary.

4. GOAL LIFECYCLE
----------------

  submit
    |
    v
  QUEUED ---- claim ----> RUNNING ---- result ----> COMPLETED
    |                       |  |
    |                       |  +---- error ------> FAILED
    |                       |
    |                 needs input / lease expires
    |                       |
    |                       v
    |                    BLOCKED
    |                       |
    |                   answer + resume
    |                       |
    |                       +--------------------> QUEUED
    |
    +---- stop ----------------------------------> CANCELLED

  RUNNING -- stop --> STOPPING -- exit ack ------> CANCELLED
                                -- lease expiry -> CANCELLED
  BLOCKED -- stop ------------------------------> CANCELLED

QUEUED, RUNNING, BLOCKED and STOPPING occupy the active slot.
COMPLETED, FAILED and CANCELLED release it.

A blocked goal stays active because the original task is unresolved.
The user supplies context and resumes it, or cancels it before
starting another. A failed goal ends; another attempt is a new goal.

5. REMOTE EXECUTION LOOP
-----------------------

  +---------------------------------------------------------+
  | Poll Track for a queued goal                            |
  +---------------------------+-----------------------------+
                              |
                         claimed lease
                              |
                              v
  +---------------------------------------------------------+
  | Pass goal + recent context to runtime adapter            |
  | Run inside the operator's configured workspace           |
  +---------------------------+-----------------------------+
                              |
                 +------------+------------+
                 |                         |
                 v                         v
         Send public status         Send heartbeat;
         and evidence               check stop flag
                 |                         |
                 +------------+------------+
                              |
                              v
  +---------------------------------------------------------+
  | Result: continue / completed / blocked                   |
  | Invalid result or process failure: failed                |
  +---------------------------------------------------------+

The adapter is runtime-neutral. Codex or another runtime can be
connected later without changing Track's goal API.

Only explicit public status messages are published. Raw tool output,
credentials and private reasoning are not the status feed.
Completion is an engine-reported result, not independent proof:
the user must be able to inspect its evidence.

6. PROTOTYPE API CONTRACT
------------------------
  Owner session:
    POST /api/goals                  submit objective
    GET  /api/goals                  active goal + history
    GET  /api/goals/{id}?after=N     read incremental events
    POST /api/goals/{id}/control     stop / resume + response
    POST /api/goal-engine/connect    issue scoped credential

  Remote engine credential:
    POST /api/goal-engine/claim          obtain goal + lease
    POST /api/goal-engine/{id}/progress  heartbeat / result

Progress includes a lease, unique event ID, state, public message
and optional owned Track run IDs. Retries reuse the event ID.
Each goal also has its own private Track run for its history.

7. DISCONNECTS, RETRIES AND STOP
------------------------------
Prototype defaults: 90-second lease, 10-second worker heartbeat,
5-second claim polling and 3-second status-page refresh.

- An atomic claim prevents two workers claiming the same goal.
- The lease fences updates from an old assignment after resume.
- Repeated event IDs do not duplicate recorded progress.
- An expired running lease blocks the goal for manual review.
- Work is not automatically replayed after a disconnect.
- The supervisor stops its child if it cannot maintain contact.
- Stop targets the managed agent process group only.

External effects are NOT exactly-once. A training job can start just
before a connection fails. Before resuming, reconcile external jobs
and saved artifacts instead of assuming that nothing happened.

Lease expiry releases a stopping goal's slot; it does not prove
that a disconnected process or external GPU job has stopped.
Those jobs retain their own stop and recovery controls.

8. FIRST END-TO-END ACCEPTANCE CHECK
-----------------------------------
[ ] Choose a remote machine, runtime and restricted workspace.
[ ] Connect its adapter using a scoped engine credential.
[ ] Submit the bounded fixture goal from section 3.
[ ] See the claim and real progress messages in Track.
[ ] Report test evidence and complete the goal.
[ ] Verify a second worker cannot claim the active goal.
[ ] Trigger a blocker; answer and resume with preserved context.
[ ] Request stop and observe the process exit acknowledgement.
[ ] Disconnect the worker; verify expiry blocks automatic replay.
[ ] Restart and reconcile without duplicating external actions.

9. CURRENT IMPLEMENTATION VS. DECISIONS STILL OPEN
-------------------------------------------------
Implemented prototype:
  Goal persistence, private Track run linkage, scoped API, leases,
  status history, stop/resume controls, and a generic supervisor.
  API and subprocess-fixture tests cover the main transitions.

Not yet connected:
  An actual agent runtime on the user's separate machine.
  The acceptance check above remains to be performed there.

Decisions needed before real autonomous work:
  - Which runtime and remote host should execute the goal?
  - Which tools, credentials and actions may it use?
  - What approvals and resource limits must be enforced?
  - How should external training jobs be reconciled and stopped?
  - What evidence is sufficient to accept completion?

This page replaces the premature goal-entry UI with the RFC.
The existing status prototype and backend remain available for
review. Reading this RFC does not submit or execute a goal.
