Feature/production worker runtime

.agent/AGENTS.md

@@ -0,0 +1,120 @@
+# OneShot Agent Policy
+
+This policy applies to code, documentation, infrastructure, data, and agent
+work in this repository.
+
+## Instruction order
+
+1. Follow system and user instructions.
+2. Follow root `AGENTS.md` and this policy.
+3. Follow the task-specific documents and repo skills routed by root
+   `AGENTS.md`.
+4. Follow the narrowest applicable repository configuration.
+
+Surface conflicts. Never silently weaken an invariant, review gate, or security
+boundary.
+
+## Tool neutrality
+
+- Codex, Claude, Antigravity, Cursor, or another capable agent may implement
+  work, but all tools follow the same canonical repository policy.
+- Tool adapters remain short pointers to root `AGENTS.md`; personal prompts,
+  permissions, models, and machine-specific commands stay in ignored files.
+- Gate A and Gate B use separate fresh, read-only FreePi processes. Each verdict
+  records the reviewer tool, platform-reported model (or `not exposed by
+  platform`), and immutable Git identities required by
+  `.agent/IMPLEMENTATION_LOOP.md`.
+
+## Product boundary
+
+OneShot's core promise is: `One job. Many retries. One settlement.`
+
+- OneShot owns authoritative Business Intent, Attempt, and Settlement state and
+  prevents duplicate committed settlements.
+- Privy provides corporate wallet access and scoped authorization, policy, and
+  spending permissions.
+- Arc is the USDC settlement rail.
+- Direct Privy and Arc evidence resolves known transaction identities. The Graph
+  is the selected v1 hashless candidate-discovery layer after its C01 evidence
+  gate; it is never the duplicate-payment lock or settlement authority.
+
+Read `.agent/PROJECT_CONTEXT.md`, `.agent/SECURITY_INVARIANTS.md`, and
+`.agent/SPONSOR_REQUIREMENTS.md` before changing these boundaries.
+
+## Non-negotiable invariants
+
+- `1 business intent -> at most 1 committed settlement`.
+- Keep one stable `business_intent_id` across retries, restarts, parallel
+  attempts, workers, and agent instances.
+- Treat `UNKNOWN` settlement state as a reconciliation requirement. Never
+  blindly repay.
+- Make state durable and transitions atomic and concurrency-safe.
+- Represent money as integer atomic units or `bigint`, never JavaScript
+  floating point.
+- External-index absence or delay is not proof that payment did not happen.
+- Normal execution must not bypass Privy policy or OneShot controls.
+- Use testnet only unless the user explicitly authorizes another network.
+- Never log, expose, persist, commit, or send secrets, private keys, seed
+  phrases, tokens, wallet credentials, or sensitive runtime configuration.
+
+## Before changing files
+
+- Inspect the current branch, status, task acceptance criteria, relevant code,
+  existing diff, and any merge/rebase state.
+- Preserve unrelated user work and keep it out of commits.
+- Record material assumptions and active context in `.agent/context/`.
+- Use current primary documentation for version-sensitive integrations.
+- Do not create or materially revise the product implementation `plan.md` until
+  required skills and integration research are ready.
+
+## Implementation quality
+
+- Keep one branch and PR focused on one milestone or tightly related change.
+- Preserve clear ownership among interface, orchestration, domain state, and
+  external adapters.
+- Validate untrusted input at boundaries.
+- Do not weaken compiler, lint, type, test, or security settings to get a pass.
+- Add tests for behavior changes and regression fixes. Payment-related changes
+  select applicable cases from `.agent/TEST_MATRIX.md`.
+- Do not leave dead code, unexplained suppressions, placeholder credentials, or
+  hidden follow-up work.
+- Update documentation when behavior, contracts, or architecture change.
+
+## Repository skills
+
+- `oneshot-idempotency`: mandatory for intent, retry, worker, payment,
+  reconciliation, or settlement work.
+- `oneshot-failure-injection`: mandatory for external-effect failure
+  boundaries.
+- `sponsor-qualification`: mandatory before sponsor, demo, or release claims.
+
+Personal workflow and review skills may supplement these rules. They never
+replace OneShot policy or FreePi Gate A/B.
+
+## Git and review policy
+
+- Never implement directly on `main` or `develop`.
+- Branch from current `develop`; target `develop` from short-lived
+  `feature/*`, `fix/*`, or `milestone/*` branches unless the user explicitly
+  names another short-lived branch.
+- Never direct-push or force-push protected branches or rewrite shared history
+  without explicit user authorization.
+- Follow `.agent/IMPLEMENTATION_LOOP.md` for local checks, staged-tree identity,
+  both independent FreePi reviews, CI, PR readiness, and invalidation rules.
+- Only explicit `VERDICT: PASS` passes a gate. Missing, ambiguous, truncated,
+  stale, unauthenticated, or failed review output fails closed.
+- Agents never merge a PR. A human reviews and explicitly authorizes the merge.
+
+## Context retention
+
+Follow `.agent/context/README.md`. Update the active record at milestone
+boundaries, before handoff/session end, and before deliberate context reset or
+compaction when possible. Never store secrets there.
+
+## Agent-complete
+
+Handoff only after intended scope is complete, local checks pass, the diff is
+cleanly scoped, and current gate state is recorded. A change is ready for human
+review only after Gate A, required CI, and Gate B pass for the exact applicable
+tree/head. Report branch, commit, PR, checks, gate evidence, and remaining
+risks. Never merge.

.agent/IMPLEMENTATION_LOOP.md

@@ -0,0 +1,144 @@
+# OneShot Implementation Loop
+
+This is the required path from a focused change to human review. `develop` is
+the base. Gate A binds to one immutable candidate tree before the first push;
+Gate B binds to the exact draft-PR head SHA and the same tree after required CI.
+
+## 1. Scope and branch
+
+1. Start from current `develop`.
+2. Create one short-lived `feature/*`, `fix/*`, or `milestone/*` branch unless
+   the user explicitly names another short-lived branch.
+3. Record goal, acceptance criteria, assumptions, non-goals, and branch state in
+   `.agent/context/`.
+4. Never implement directly on `develop` or `main`.
+
+## 2. Implement and validate
+
+1. Make the smallest coherent change.
+2. Use applicable repo skills and `.agent/TEST_MATRIX.md`.
+3. Run local format, lint, type, test, build, and focused failure-injection
+   checks that exist for affected components.
+4. Inspect tracked, staged, unstaged, ignored, and intended untracked changes
+   for scope, generated files, secrets, and unrelated work. Never open or send
+   ignored secret files to a reviewer.
+5. Stage every intended file and only intended files. Gate A reviews a single
+   candidate tree, not a partially staged workspace.
+6. Record concise command/result evidence in the active context. Keep full logs
+   only for failures that require diagnosis.
+
+Do not bypass failures with force flags, skipped checks, broad ignores, lower
+thresholds, or disabled hooks.
+
+## 3. Capture immutable Gate A evidence
+
+Refresh the base and record exact identities:
+
+```bash
+git fetch origin develop
+git rev-parse origin/develop
+git write-tree
+git status --short
+git diff --cached --check
+git diff --cached <recorded-base-sha>
+```
+
+- `recorded-base-sha` is the printed full SHA, not a moving ref.
+- `git write-tree` is the candidate tree SHA.
+- For an already-created but unpushed merge commit, use
+  `git rev-parse "HEAD^{tree}"` and `git diff <recorded-base-sha> HEAD`; the
+  commit must have no additional workspace changes.
+- Confirm no intended change is absent from the candidate and no unrelated file
+  is present.
+
+## 4. FreePi Gate A: pre-push review
+
+1. From the repository root, start exactly one fresh process:
+
+   ```bash
+   npx free-pi-cli
+   ```
+
+2. In one message, tell the new session to read
+   `.agent/review-prompts/freepi-prepush-review.md`; provide only the task
+   acceptance criteria, recorded base SHA, candidate tree SHA, and whether the
+   tree is staged or the exact unpushed `HEAD` tree.
+3. Let the reviewer inspect the candidate diff and routed repository documents
+   with its tools. Do not paste duplicate policy, complete file bodies, repeated
+   terminal output, or secrets into the prompt.
+4. Accept only an explicit `VERDICT: PASS` containing the required reviewer,
+   model, base, target, and tree identities.
+
+Each attempt uses a new `npx free-pi-cli` process. Never resume or reuse a
+reviewer context. Any candidate-tree change invalidates Gate A and requires
+local checks plus a new process. Missing evidence, ambiguity, truncation,
+authentication/tool failure, or any verdict other than explicit PASS fails
+closed.
+
+## 5. Commit, push, and draft PR
+
+Only after Gate A passes for the candidate tree:
+
+1. If the tree is staged, commit it without changing content. If Gate A reviewed
+   an existing unpushed commit, do not amend it.
+2. Confirm `git rev-parse "HEAD^{tree}"` equals the reviewed candidate tree.
+3. Push the short-lived branch without force.
+4. Create a draft PR targeting `develop`, never `main` for feature work.
+5. Fill `.github/PULL_REQUEST_TEMPLATE.md`, including Gate A evidence.
+
+## 6. Required CI
+
+Wait for every required check on the exact draft-PR head SHA. Pending, skipped,
+missing, or failing required checks are not green.
+
+If a fix changes content, rerun local validation and fresh Gate A, commit, push,
+and wait for CI again.
+
+## 7. FreePi Gate B: exact PR review
+
+1. Capture PR URL/number, base, head branch, exact full head SHA, head tree SHA,
+   full diff, required check results, and Gate A candidate tree.
+2. Start a second fresh process from the repository root:
+
+   ```bash
+   npx free-pi-cli
+   ```
+
+3. In one message, tell it to read
+   `.agent/review-prompts/freepi-pr-review.md` and provide only the captured
+   identities, PR URL, concise CI summary, acceptance criteria, and Gate A
+   verdict. Let the reviewer obtain the diff and public evidence with tools.
+4. Accept only explicit `VERDICT: PASS` bound to the exact current PR head SHA
+   whose tree equals the Gate A candidate tree.
+
+Any content change after Gate B invalidates both tree equality and Gate B.
+Return to local validation, fresh Gate A, commit/push, green CI, then fresh Gate
+B.
+
+## 8. Human review and merge
+
+After Gate A, required CI, and Gate B pass for the current tree/head:
+
+1. Record both verdicts and evidence in the PR and context file.
+2. Mark the draft ready for human review.
+3. Report branch, SHA, tree SHA, PR URL, checks, gates, and residual risks.
+4. Stop. Agents never merge; only a human may authorize and perform the merge.
+
+## Review token discipline
+
+- Canonical policy is linked, not copied into tool adapters or review prompts.
+- Send each reviewer one compact instruction message. The reviewer reads only
+  documents routed by root `AGENTS.md` and files relevant to the diff.
+- Reference immutable Git identities and concise check results instead of
+  pasting whole diffs, policy files, or successful logs into chat.
+- Reviewers inspect silently and return one structured verdict. They do not
+  narrate file reads, repeat the task, or restate unchanged policy.
+- Never reduce scope, skip evidence, or hide failures to save tokens. Token
+  discipline removes duplication, not review coverage.
+
+## Privacy boundary
+
+FreePi may review the candidate diff, tests, public documentation, and
+non-sensitive check evidence only. Never provide `.env*`, ignored files,
+private keys, seed phrases, access tokens, API secrets, wallet credentials, or
+sensitive runtime configuration. If safe review is impossible, fail the gate.

.agent/PROJECT_CONTEXT.md

@@ -0,0 +1,87 @@
+# OneShot Project Context
+
+## Product statement
+
+`One job. Many retries. One settlement.`
+
+OneShot executes an approved business obligation safely despite retries,
+crashes, lost responses, parallel workers, or multiple agent instances.
+
+The core cardinality is:
+
+`1 intent / N attempts / <=1 committed settlement`
+
+This document defines ownership and vocabulary. It is not a product
+implementation plan.
+
+## Primary production vertical
+
+The first user is a company that lets an autonomous agent purchase a paid API
+operation or digital result in USDC. The company approves one business
+obligation; retries, restarts, queue redelivery, parallel workers, and multiple
+agent instances must all converge on the same Business Intent and at most one
+committed settlement.
+
+The initial product exposes an agent API, execution worker, reconciliation
+service, operator console, and audit/recovery timeline. Invoice payment,
+procurement, subscriptions, and other agent-commerce workflows are later
+verticals over the same durable intent contract.
+
+## System ownership
+
+- OneShot is authoritative for business-intent execution state, attempt state,
+  settlement state, and permission to create another external settlement.
+- Privy is the corporate wallet and scoped authorization boundary. OneShot must
+  use its policies and spending permissions on the normal execution path.
+- Arc is the real USDC settlement rail used by the demo.
+- Direct Privy lookup and Arc RPC receipt/log evidence resolve known transaction
+  identities after ambiguous outcomes.
+- The Graph is the selected v1 candidate-discovery layer when the transaction
+  hash is missing. C01 must prove live hashless discovery and AI-track value;
+  Graph results remain non-authoritative and can never authorize another payment.
+
+When an external submission may have happened but the result is uncertain,
+OneShot records `UNKNOWN` and reconciles. Missing external-index data never converts `UNKNOWN` into permission to submit again.
+
+## Glossary
+
+### Business Intent
+
+The durable identity of one approved business obligation. Its
+`business_intent_id` remains stable across retries, process restarts, queue
+redelivery, parallel workers, and multiple agents. Payload differences do not
+create a second settlement right when the identifier is the same.
+
+### Attempt
+
+One execution try for a Business Intent. Attempts are expendable and may fail or
+repeat. Any number of Attempts can belong to one Business Intent.
+
+### Settlement
+
+The committed external USDC payment for a Business Intent. A Business Intent may
+have zero or one committed Settlement, never more than one.
+
+### Reconciliation
+
+The process that resolves an ambiguous external effect using durable local
+state, provider identifiers and receipts, Graph-discovered candidates, and Arc proof.
+Reconciliation precedes any decision to retry payment when settlement state is
+`UNKNOWN`.
+
+### Recovery View
+
+A derived, non-authoritative view assembled from durable OneShot records, live
+Graph candidate discovery, and Arc verification. It helps operators and agents explain
+and recover work but does not grant permission to create a Settlement.
+
+## Decision test
+
+Any design affecting retries or payments must answer:
+
+1. What stable Business Intent does this Attempt belong to?
+2. Which durable atomic transition grants the right to submit an external
+   Settlement?
+3. How is an ambiguous submission reconciled without a blind retry?
+4. How do parallel workers converge on at most one committed Settlement?
+5. Which evidence is authoritative, and which evidence is only a Recovery View?