@uchibeke/gallivant 0.0.0-stage → 0.2.0

package/docs/task-delivery.md

@@ -0,0 +1,476 @@
+# Embed task delivery in another application
+
+The package exposes Gallivant's task/readiness/review decisions and provider
+transports to a trusted host through a scoped operation API or MCP. The host
+supplies authentication and authorization, tenant/region routing, repository
+authority, HTTP transport, durable storage, scheduling and any web/plugin UI.
+Installing the package does not deploy a service or configure those boundaries.
+
+**APort is the reference integration**, not a required host for these exports.
+The examples below use its injected adapters and deployment names; another host
+must enforce the same authorization, ownership, persistence and recovery
+contracts. In the APort integration, APort owns publication and the host
+responsibilities above. Its existing
+`aporthq/agent-passport/aport-task-delivery-mcp` job produced merged
+[PR #414](https://github.com/aporthq/agent-passport/pull/414); reuse that integration.
+The M5/M6 notes below preserve that integration's milestone evidence and gates;
+they do not certify another host or supply a public UI, database or competing
+runner.
+
+## Installed exports
+
+Core `0.2.0`, task schema `1`, execution schema `1`, operation schema `1`.
+The candidate digest comes from the emitted `runtime.json`/`manifest.json`;
+pin the artifact produced from the eventual human-merged commit, not this branch.
+
+| Import | Public API |
+| --- | --- |
+| `@uchibeke/gallivant/tasks` | `createTaskService`, `TASK_VERSION`; same service used by CLI task commands |
+| `@uchibeke/gallivant/capabilities` | `executionCapabilities`, `capabilitiesFor`, setup/runtime requirements |
+| `@uchibeke/gallivant/task-delivery` | `createTaskDelivery` scoped operation dispatcher |
+| `@uchibeke/gallivant/task-delivery/contracts` | `TASK_OPERATIONS`, versions, compatibility handshake, UI resource configuration |
+| `@uchibeke/gallivant/task-delivery/views` | `taskView`, `modelSummary`; saved observations only |
+| `@uchibeke/gallivant/task-delivery/store` | `createDeliveryStore`, `scopeKey`; single-host durable receipt adapter |
+| `@uchibeke/gallivant/task-delivery/mcp` | `registerTaskDelivery`; lazy optional MCP SDK peer `1.32.1` |
+| `@uchibeke/gallivant/execution` | Existing `makeExecution`, cached inspect and coordinator reconciliation |
+| `@uchibeke/gallivant/providers/openai-agents` | Existing managed session transport and setup checks |
+| `@uchibeke/gallivant/providers/codex-cloud` | Existing native CLI transport and setup checks |
+| `@uchibeke/gallivant/runtime/coordinator` | `createCoordinator` fenced bounded wake envelope |
+| `@uchibeke/gallivant/runtime/node` | `createNodeOwnerStore`, `createNodeCoordinator`, requirements |
+| `@uchibeke/gallivant/runtime/state` | Check, migrate, private backup and fresh-namespace rollback |
+| `@uchibeke/gallivant/runtime/node/dependencies` | State/config/log/identity constructors, canonical tick/readiness/controls, bounded log reader and atomic storage helpers for injected Node adapters |
+| `@uchibeke/gallivant/plugin-package` | Single reproducible package builder and public metadata validator |
+
+Imports read no operator configuration, invoke no provider and start no daemon.
+Existing `./lib/*` compatibility imports remain; consumers use the named exports.
+No new CLI daemon is required. Existing registry/run/source files, tracker routes,
+Command Center SSE/history, statuses and controls retain their version-1 shapes.
+
+## Scoped operation adapter
+
+```js
+import { createTaskDelivery } from '@uchibeke/gallivant/task-delivery';
+import { createDeliveryStore } from '@uchibeke/gallivant/task-delivery/store';
+const delivery = createTaskDelivery({
+  manifest: emittedRuntimeManifest, // load this installed artifact's runtime.json
+  authorize: aportAuthorize, // validate OAuth/audience/region/repository on EVERY call
+  contextFor: aportScopedNodeContext,
+  store: createDeliveryStore('/durable/preview/delivery'),
+  schedule: aportEnqueueWake,
+  secretsFor: aportPrivateRedactionValues,
+});
+const task = await delivery.dispatch('prepare', {
+  repositoryId: 'widget', harness: 'openai-agents',
+  text: 'Describe the requested implementation and its constraints.',
+  completion: { target: 'delivery_ready' }, // optional; default shown
+  allowance: { budgetUsd: 1, runtimeMs: 60000 },
+  operationId: 'request-1', expectedRevision: 0,
+}, authenticatedIdentity);
+```
+
+`authorize` must return validated `tenant`, `account`, `environment`, `region`,
+`scopes` (`task-delivery:read` or `task-delivery:write`) and authorized repository
+IDs. Identity comes from APort's authenticated request context, never tool input.
+`contextFor(scope, repositoryId)` supplies `{ctx, repository:{dir,repo,context}}`.
+Each context and durable home must be isolated by all four scope dimensions;
+credential/GitHub/provider resolution must enforce the same scope. Selected
+context IDs map to trusted repository paths. No paths, endpoints or credentials
+are accepted by the public schemas. Do not supply `taskOptions` in production;
+that dependency injection seam is used by deterministic consumer fixtures.
+
+The durable receipt store interface is `read(scope)` and
+`transaction(scope, async (data, save) => result)`; `save` must commit before it
+resolves. It serializes the scope for the entire mutation and retains task
+ownership, exact request fingerprints, intent, acknowledgement and pending wake.
+This release's filesystem adapter supports one host on a durable volume. APort
+can supply another adapter only with equivalent tested transaction/ownership
+semantics. Shared physical storage alone grants no authority.
+Delivery mutations also claim the scoped home's daemon ownership lock before
+saving intent and hold it through task effects, receipt acknowledgement and wake
+scheduling. Backup, migration and coordinator wakes therefore refuse concurrent
+ownership; retry the same operation ID after the owner releases. The scheduler
+must enqueue a future wake, never execute a coordinator inline. Read operations
+do not acquire this owner or create provider pollers.
+The dispatcher requires its own emitted `runtime.json` as `manifest`; it captures
+that identity at construction and checks the exact installed version/digest under
+ownership on every mutation, including receipt replays. Migrate each scoped home
+before enabling requests. After migration to another artifact, retire old request
+handlers; never substitute the namespace's new pin as an old handler's manifest.
+Consumers upgrading from the earlier dispatcher signature must add this manifest
+and initialize the scoped pin. Reads do not validate or replace that pin.
+
+Capability responses expose `repositories[].completion` with `defaultTarget` and
+supported `targets`. The shared prepare schema accepts only
+`completion: { target: 'delivery_ready' | 'integrated' }`; the selected policy is
+persisted through intake and implementation ownership. Task, list, model and
+evidence projections expose `completion` from saved coordinator observations.
+For `delivery_ready`, a qualified saved handoff stops automatic observation and
+fixes. Explicit queued controls reopen the normal workflow. `integrated` and
+legacy runs retain monitoring. Host schedulers use the exported
+`coordinatorEntryActive` predicate instead of treating every `ready-for-human`
+entry as active; the predicate requires matching repository, PR, base, head and
+gate proof. Read `completion.monitoring` for the saved view's monitoring status.
+Use `completion.status`, not a provider success or a terminal PR state, to report
+fulfillment. `awaiting_integration` means the qualified PR is still being watched;
+`blocked` or `unverified` requires attention. Both targets use the GitHub PR
+observation adapter today. The milestone names are portable, but no additional
+artifact, deployment or non-GitHub adapter is advertised. See [task milestones](tasks.md#choose-the-delivery-milestone)
+for evidence, cancellation and legacy behavior. The policy never grants merge
+permission or changes the allowance.
+
+New natural-language publication clauses use the core's versioned exact-source
+ownership contract. `completion.obligations` exposes their pending/fulfilled state
+and matching coordinator evidence. `TASK_DELIVERY_SCOPE` is a before-effects
+clarification refusal, durably acknowledged on the exact operation identity; it
+must not be retried with changed text under that same identity. Ask the owner to
+clarify the complete request and then use a new preparation identity. See
+[natural-language ownership](tasks.md) for supported syntax and limitations.
+
+Literal examples must have matching quote/backtick delimiters in new requests and
+answers. Saved ownership contracts keep their approved spans and historical
+unclosed-literal handling. Malformed mixed backtick runs that previously exposed a
+publication clause can fail validation under the corrected scanner; their records
+are not rewritten. The owner must clarify a new request rather than automatically
+continuing publication from that malformed contract. PR-modified UI/document objects, database transactions, data
+structure operations and product-user consent are implementation requirements;
+unqualified Git directions, owner approval and publication conditions remain
+workflow controls. Only those concrete technical objects are excluded: unrelated
+or coordinated restrictions remain visible. Statement separators end independent
+constraints, while an unfinished colon prefix keeps its scope across blank lines.
+This is a bounded grammar, not a general natural-language authorization model.
+
+All mutations require operationId and expectedRevision; prepare uses revision 0.
+Preparation does not authorize implementation. Start requires `run:true` and the
+current exact readiness decision. Answers bind saved question IDs. Stable keys
+replay saved results; changed payloads conflict. Lost execution acknowledgement
+retains the existing dispatch intent and cannot automatically submit twice.
+Controls call the same queue as CLI/tracker and carry stable request identity.
+The scheduler may retry a pending wake without repeating inference.
+Scoped allowance is pinned into implementation metadata after subtracting
+preparation charges/reservations and elapsed time. Later runs use the saved cap,
+subtract known local charges and completed runtime, and retain the remote
+execution ledger's aggregate reservations. Unknown local cost or duration refuses
+further dispatch. Providers without billing hard caps remain explicitly described
+as such; an authorization limit is not a promise about their billing controls.
+
+Tools are generated from `TASK_OPERATIONS`: capabilities, prepare, answer,
+resume, validate, start, list, inspect, evidence, logs and control. MCP SDK
+registration prefixes each name with `task_`; there is one schema/annotation
+mapping. Preparation, readiness, start and controls are writes with external
+effects. Reads inspect saved state and create no provider poller. MCP registration
+expects APort's per-request `identityFor` and authorized built `readResource`.
+Capabilities return at most 100 authorized repositories, sorted by opaque ID,
+with `truncated` and `nextCursor`. Pass `nextCursor` as `cursor` to continue;
+a null cursor ends the traversal. Every page reauthorizes the account. Repository
+IDs and provider availability, preparation, setup, cost and control fields appear in both
+MCP model content and UI metadata, so a client can construct `prepare` directly.
+The optional cursor extends operation schema version 1 without changing existing
+empty-input calls. Restart discovery to include newly granted IDs before a cursor.
+
+APort owns transport-level OAuth discovery/challenges, origin/audience validation,
+credential rotation, request limits, quota, retention and production authorization.
+
+Full UI views include questions, brief, harness/cost/setup, allowance, progress,
+bounded logs, artifact IDs/hashes, source snapshots, PR URLs and supported controls.
+They remove configured private path prefixes and redact resolved secrets;
+repository-relative artifact paths remain available in authorized UI views.
+Model output includes bounded capability discovery, task/revision/status,
+repository/harness identity, completion, question IDs and text, supported controls,
+blocked-task recovery guidance and the PR link. List pages include question counts;
+inspect and mutation responses include the questions. Raw logs and brief bytes
+stay in UI metadata. Artifact download authorization/storage remains APort's
+job; the public dispatcher exposes stable manifests, not arbitrary file retrieval.
+
+`uiResourceConfiguration` accepts the single registered `ui://` URI, dedicated
+HTTPS origin and exact CSP connect/resource origins. Global sidebar and thread
+panel entrypoints share it. HTML is supplied from the built APort UI (2,000,000 bytes
+maximum, shared by the package builder and runtime reader), served as
+`text/html;profile=mcp-app`. Fixture HTML proves resource
+wiring only. No final UI or host availability is claimed here.
+
+## Runtime and existing Pages deployment
+
+Node 22 is the supported workflow runtime. Inject `ctx.state`, `gh`, `git`,
+`credential`, `identity`, `notify`, `executionFor`, source/brief storage and clock
+using the predecessor context contracts. The runtime calls `makeTick` for all
+review decisions. Durable home stores registry, tasks, briefs, provider intent,
+events and artifacts; neither container disk nor Pages temporary files suffice.
+Bounded entry/chain batches run on each externally scheduled wake. Active chains
+rotate by a persisted name cursor; done, cancelled and stopped history consumes
+no batch slots. Completion or cancellation cannot shift the remaining window.
+`maxChains: 0` explicitly disables chain processing for that coordinator. Entry
+and chain cursors commit only after a successful tick. The canonical tick's chain
+poll deadline is persisted too: pending batches finish their sweep, then chain
+reads wait for `poll_seconds` even across process restarts. Faster wakes continue
+entry/provider reconciliation without advancing the chain cursor. The next wake
+is scheduled before reconciliation, so a crash cannot lose recovery scheduling.
+
+`createNodeOwnerStore({home,durable:true,replicas:1})` uses the existing daemon
+exclusion plus persisted monotonic fence/instance. It cannot expire a live owner;
+the stale-process check recovers after eviction. A UI or repeated callback never
+creates a concurrent owner. Do not share this lock across hosts or advertise it as
+a distributed lease. Injected distributed stores must atomically enforce fencing
+at their write boundaries. The wrapper guards context effects and retains provider
+dispatch ambiguity through the existing execution service.
+
+Before wake-up, migrate/pin the exact runtime artifact. Supply the emitted
+`runtime.json` to `createNodeCoordinator({ctx,store,schedule,manifest})`.
+The coordinator refuses a different active-job digest. Compatible patches keep
+task/provider/brief identities; drain jobs before staging a different artifact.
+No running code is silently upgraded. The public API's pre-1.0 compatibility
+window is `0.2.x`, with operation/task/execution wire schemas all `1`; other
+versions need migration.
+
+The portable contracts/views/wake envelope have no Node dependencies. The complete
+task service and both transport implementations still require Node filesystem,
+child processes, Git/gh and isolated verification. `npm test` bundles the portable
+entries for browsers and checks their shared liveness predicates. The installed
+artifact check (`test:plugin-package`) repeats those bundles and confirms the full
+Node runtime rejects a browser target, separately from actual Node execution. This
+is **not** a tested Workers-native workflow runtime or deployed Pages endpoint.
+The smallest remedy: keep existing Pages OAuth/MCP/UI; connect its authenticated
+runtime binding to one Node 22 coordinator with a durable volume and external
+wake-ups. Evaluate an already supported Node runtime or Cloudflare Container in
+the existing account before provisioning. No mandatory new Worker/VPS is proposed.
+
+Cloud additionally needs the pinned Codex CLI and trusted operator sign-in. Its
+predecessor currently blocks new dispatch until a documented environment-to-repo
+check can be implemented/qualified. Preserve that block; native Cloud HTTP,
+public credential delegation, cancellation and interrupt are not invented.
+Agents API credentials, exact model/environment access and inference/compute
+allowance must be supplied by the authorized account; no subscription entitlement
+is inferred. Both transports remain exported and covered by installed fixtures.
+
+The current registry declares bounded natural-language preparation for
+`openai-agents`: `agents-text-only-v1`, authority `text-only`, environment `none`.
+Its creation request disables tools and delegation; effective session and output
+checks enforce that boundary. Claude and Codex have their own registered local
+preparation boundaries. Codex Cloud, Gemini, OpenCode and Goose expose
+`canPrepare:false` with a remedy; selecting them for preparation cannot silently
+fall back to another provider or gain implementation authority.
+
+Capability responses describe this implementation, not account entitlement or a
+completed live workflow. Installed fixtures cover shared API/Cloud transport,
+recovery and publication; preparation qualification and live account prerequisites
+remain explicit in [preparation](preparation.md), [Agents setup](openai-agents.md)
+and [Cloud availability](codex-cloud.md). The package can be integrated through
+MCP or the scoped operation API, but is not itself a deployed multi-tenant service.
+
+## Build, configure, upgrade and rollback
+
+Build from the same tagged/merged source and explicit core version. Commit or
+remove npm ignore/configuration controls before a public build, including ignored
+controls or directories under the runtime payload. Internal builds record these
+changes and remain development fixtures:
+
+```sh
+npm ci --ignore-scripts
+node bin/package-plugin.mjs --config /private/aport-package.json --validate-public
+npm run package:plugin -- --config /private/aport-package.json --out /private/candidate \
+  --core-version 0.2.0 --source-commit <40-character-merged-commit>
+# For development only, add --internal; keep fixture:true in the config.
+npm install --ignore-scripts --prefix /private/candidate-runtime /private/candidate/uchibeke-gallivant-0.2.0.tgz
+node /private/candidate-runtime/node_modules/@uchibeke/gallivant/bin/task-delivery-state.mjs check \
+  --home /durable/preview --manifest /private/candidate/runtime.json
+node /private/previous-runtime/node_modules/@uchibeke/gallivant/bin/task-delivery-state.mjs backup \
+  --home /durable/preview --manifest /private/previous/runtime.json --out /private/backup
+node /private/candidate-runtime/node_modules/@uchibeke/gallivant/bin/task-delivery-state.mjs migrate \
+  --home /durable/preview --manifest /private/candidate/runtime.json
+# Roll back package AND state into a fresh namespace, then switch the existing binding.
+npm install --ignore-scripts --prefix /private/previous-runtime /private/previous/uchibeke-gallivant-0.2.0.tgz
+node /private/previous-runtime/node_modules/@uchibeke/gallivant/bin/task-delivery-state.mjs rollback \
+  --backup /private/backup --out /durable/restored --manifest /private/previous/runtime.json
+npm run test:plugin-package
+```
+
+Replace the illustrative `/private/...` and `/durable/...` paths with private,
+writable locations on your host. The upgrade example assumes the previous
+package is installed under `/private/previous-runtime`; use that installed
+artifact for backup. First-time setup has no previous namespace to back up.
+Separate installation prefixes keep candidate and rollback versions out of the
+source checkout and avoid depending on a global executable or shell `PATH`.
+
+Stop new intake/wake-ups and the old coordinator before backup/migration. Active
+jobs retain their runtime; incompatible changes fail with this remedy. Backups
+are private, outside public packages, omit operator config/auth, and preserve
+task/run/provider/source identities. Back up with the currently pinned, pre-upgrade
+manifest; a candidate manifest cannot label an older namespace's backup. Restore
+requires both the backup envelope and copied runtime pin to match the selected
+artifact. Unpinned legacy state can be backed up with an explicit compatible
+manifest and must be migrated before enabling its coordinator.
+Verify store consistency before switching bindings. Keep old runtime artifacts
+and credential bindings available for rollback; do not merge/upgrade live jobs.
+
+A qualified `delivery_ready` handoff releases its runtime pin even while its
+retained registry state is `ready-for-human`. Pending controls, live or uncollected
+execution, unresolved intake/receipts and active chains still prevent migration.
+Pending learning delivery audits also retain the pin and keep coordinator wake-ups
+active. They retry separately after handoff without polling the settled provider,
+reopening PR review or launching another agent turn; a successful audit drains
+the saved outbox and releases that remaining work.
+Legacy tasks, `integrated` tasks awaiting merge and unresolved `needs-human` work
+retain their pins; the scheduling pause alone does not make a namespace idle.
+
+Package config supplies publisher `APort`, exact endpoint, `resource` configuration,
+owner-selected support email/product/support/privacy/terms/license URLs and explicit
+asset paths (`assets.ui`, `assets.icon`, `assets.screenshots`). The emitted combined
+skills/MCP ZIP has one HTTPS MCP server, Apache-2.0 license and explicit assets.
+Runtime tarball, recipe, operation schemas and manifest record source commit,
+core/contracts, dependency lock, payload/asset/schema hashes and artifact SHA-256.
+The published runtime carries `npm-shrinkwrap.json`, so the installed builder
+uses the same dependency lock as the source build.
+No credential headers or unrelated tree files enter the plugin. Keep input config,
+private backups, provider logs and reviewer credentials outside the output.
+
+Public packaging also requires `oauth`, `review`, and `publication`. The OAuth
+input deliberately matches APort's currently implemented registered public client:
+`type: "oauth"`, `client: { mode: "provided", clientId: "<registered ID>",
+tokenEndpointAuthMethod: "none" }`, and `baseScopes` copied from the public
+authorization server's actual discovery/tool contract. APort's public scopes are
+`tasks:read`, `tasks:write`, `tasks:check`, and `tasks:control`; they are distinct
+from Gallivant's internal delivery scopes. The builder validates OAuth scope-token
+syntax and preserves the deployment's supplied values without translating them.
+Verify exact agreement with live discovery before connecting. Optional `authorizationUrl` and
+`tokenUrl` override discovery. Register the exact redirect URI displayed by the
+host's MCP management page in APort's `TASK_DELIVERY_CLIENTS`; do not assume the
+GitHub login callback is the host callback. No client secret belongs in this
+public PKCE configuration. DCR/CIMD and confidential clients are not implemented
+by this APort deployment and are not accepted by its packager.
+
+Optional `oauth.defaultScopes` uses the same token validation as `baseScopes`,
+but permits an empty array. Per OpenAI's OAuth configuration reference, `[]`
+suppresses client/server default scopes; omitting it preserves those defaults.
+`baseScopes` remains mandatory and is included in every authorization request.
+Use the explicit empty override when all requested scopes are supplied there;
+verify the actual host authorization request after updating its package.
+
+`review.test_cases` must contain exactly five `positive` and three `negative`
+cases. Every case needs `description` and `prompt`; positive cases also need
+`tools_triggered` (comma-separated actual `task_*` names) and
+`expected_behavior`. Optional `file_attachment_urls` and `expected_output_url`
+must be public HTTPS URLs. `review.demo_recording_url` must identify the actual
+accessible walkthrough; it may include a video query string. Supply
+`publication.release_notes`. The builder emits review beside `interface` under
+`extensions.com.openai`, and auth under the MCP server's
+`extensions.com.openai.auth`. Missing fields stop public preflight. Internal
+fixtures may omit the three inputs; supplied inputs are still validated. A
+correct metadata shape does not prove its cases ran or qualify the release.
+
+Optional `listing: { longDescription, category }` replaces those two directory
+fields through the same builder. Describe the intended users and actual access
+limitations; use an exact category title from the publisher dashboard (for this
+repository workflow, `Developer Tools`). Descriptions allow up to 4000 characters
+and line breaks. Category titles must be one line of at most 80 characters.
+Unknown fields, credentials, blank values and unsupported controls are rejected.
+Identity, publisher, review inputs and release gates cannot be overridden here.
+Keep final listing copy in the package config rather than editing a generated ZIP.
+See [OpenAI listing metadata](https://developers.openai.com/plugins/deploy/submission#listing-metadata).
+
+For a disposable sandbox portal draft, internal builds can set
+`developmentIdentity: { name: "aport-task-delivery-preview", displayName:
+"APort Tasks Preview" }`. This prevents a sandbox connection from occupying the
+canonical directory identity: changing a registered MCP server URL later is not
+a self-service update. Public validation refuses this input; use the canonical
+identity and permanent production endpoint for the actual release.
+
+The vendored portable MCP schema predates this OpenAI authentication extension.
+Validation retains the original schema bytes and adds only the documented,
+strictly validated auth overlay. The release manifest records its separate
+`submissionSchemaSha256`. Do not hand-edit the emitted ZIP to add metadata or
+weaken the portable schema to admit arbitrary server fields. Reviewer credentials
+and private reviewer instructions are rejected; enter them only in the portal.
+
+The configuration shape is:
+
+```json
+{
+  "publisher": "APort",
+  "endpoint": "https://aport.io/api/task-delivery/mcp",
+  "fixture": false,
+  "supportEmail": "<owner-selected support email>",
+  "homepage": "<owner-selected HTTPS product URL>",
+  "supportUrl": "<owner-selected HTTPS support URL>",
+  "privacyUrl": "<owner-selected HTTPS privacy URL>",
+  "termsUrl": "<owner-selected HTTPS terms URL>",
+  "licenseUrl": "<owner-selected HTTPS license URL>",
+  "resource": {
+    "uri": "ui://task-delivery/app",
+    "domain": "https://aport.io",
+    "connectDomains": ["https://aport.io"],
+    "resourceDomains": []
+  },
+  "assets": {
+    "ui": "/private/aport-ui/task-delivery.html",
+    "icon": "/private/aport-ui/icon.png",
+    "screenshots": ["/private/aport-ui/actual-host.png"]
+  }
+}
+```
+
+Replace every placeholder and bind the actual built UI's exact origins. This
+shape alone does not prove deployment or supply final assets. Public packaging
+also requires a clean source payload and verifies the requested source commit
+against HEAD. Internal dirty builds record their changed payload files and hashes.
+
+Public validation refuses absent metadata, example URLs, unavailable built UI,
+fixture assets and missing screenshots with remedies. A structurally valid
+package remains `public-candidate-unqualified`, never submission-ready by itself.
+Rebuild executable/configuration changes and invalidate affected evidence.
+
+Official formats rechecked 2026-10-12: [portable packaging](https://developers.openai.com/plugins/build/plugins),
+[UI resources](https://developers.openai.com/plugins/build/chatgpt-ui),
+[global/thread entrypoints](https://developers.openai.com/plugins/build/extensions),
+[submission](https://developers.openai.com/plugins/deploy/submission).
+Vendored portable JSON schemas retain their source URLs and recorded hashes.
+
+## APort reference integration: M6 handoff gates
+
+These gates belong to the APort integration handoff. M5 artifact tests are
+deterministic and unpaid; they are not actual host evidence.
+M6 pins the **human-merged** artifact/digest into the existing APort job, verifies
+real Pages/runtime/bindings/durable storage, and reconciles PR #414's deployment.
+The 2026-10-07 endpoint probe returned HTTP 503. That audit session had no configured
+Agents API credential/model/environment; pinned Cloud listing was accessible but
+proved neither environment repository nor inference access. Browser/capture
+inventory was available, with no task-delivery tool installed in that session.
+
+Mandatory remaining gates: actual endpoint OAuth discovery/tool scans and scoped
+account isolation; both providers' real implementation and correction PRs across
+restart; public Cloud mode only if delegation is demonstrated (otherwise trusted
+operator mode); actual sidebar/panel and fresh-account reconnect; restricted
+reviewer account with shared campaign allowance; authentic screenshots/demo;
+working legal/support pages; eligible publisher project/org/domain verification;
+bounded G9 kit with five positive/three negative cases. APort is publisher. No
+release approval, submission, deployment or publication is claimed by M5.
+
+### Model-visible discovery and evidence
+
+`list` accepts an optional saved task ID as `cursor`, returns at most 100 authorized
+tasks in ID order, and supplies `nextCursor` when `truncated` is true. Every page
+uses current account and repository authorization; a cursor grants no access.
+MCP evidence responses expose bounded artifact IDs/hashes, provider test claims,
+coordinator verification observations and the PR link. Log responses expose the
+saved window range, count, gap and `nextAfter`, while raw log text and briefs remain
+in authorized UI metadata. Neither read operation starts provider reconciliation.
+
+
+CLI task mutations serialize with runtime backup and migration using the task mutation owner, while ordinary daemon operation remains available. A namespace containing `runtime-pin.json` requires the manifest-aware delivery adapter for writes; the CLI can still list and inspect it. Keep ordinary CLI tasks in an unpinned local home. Package output directories must be outside the package source root, including destinations reached through symlinked parents.
+
+
+First-time runtime pinning requires an idle legacy namespace; retain the original runtime until active intake and execution are drained. All CLI registry mutations, chain writes and control requests share maintenance exclusion, including local web control requests. Pinned namespaces require the manifest-aware adapter.
+
+The filesystem delivery adapter admits at most 256 ordinary operation identities per account scope and caps their serialized store section at 32 MiB. At the operation-count limit, retained operation IDs remain available for idempotent retries; new ordinary operations fail with `DELIVERY_CAPACITY` before task effects. Keep old namespaces for retries, drain their active work and archive them before provisioning a separate namespace for new work. Never route retries to a new namespace or delete receipts to free capacity. A size-limit failure during acknowledgement preserves the durable intent; inspect and reconcile that operation before authorizing another identity. Oversized legacy stores require an operator-managed archival/indexed-store migration that preserves identities; files exceeding the combined byte ceiling are refused before loading into memory.
+
+Cancellation uses a separate 1 MiB reserve of at most 256 compact receipts, one per retained task. Ordinary receipts retain their 256-ID and 32 MiB limits. Cancel retries retain the original operation ID and signature, reauthorize, and return the current task view; they do not retain another full snapshot. A new cancellation identity for an already reserved task is refused with instructions to retry its original ID or inspect its status. This reserve cannot be consumed by other controls, and lost scheduling acknowledgements remain retryable without repeating cancellation effects.
+
+New ordinary receipts reserve 4 KiB for the compact acknowledgement and bounded task/repository binding before any task effects. Acknowledgements retain operation signatures and task identity, not full task-view snapshots; retries reauthorize and return the current task view without repeating effects. Historical acknowledged snapshots remain replayable. Historical pending intents must pass the same reservation check before recovery. List model responses contain task/repository identity, status and question count; inspect and mutation responses retain question text.
+
+Interrupted resume, validation and start requests whose intake revision has advanced are settled from the current saved task view, including blocked or incomplete outcomes. Exact retries do not repeat their effects or infer approval from a later revision. Further recovery requires inspection and a new operation against that revision; unresolved intake or execution state continues to pin its artifact independently of the settled delivery receipt.
+
+Public packaging rechecks HEAD and payload changes after npm packing. A changed checkout or failed Git recheck removes the staged output and requires a rebuild; internal fixtures record late payload changes or loss of source verification without claiming release qualification.
+
+Archive payload hashes are computed from packed entries and checked against the selected Git commit. The bundled parser is bound by `templates/plugin/bundled-runtime.json`, whose file hashes and lock integrity must be refreshed and committed together when upgrading that dependency. Before/after Git status remains an additional check, not byte provenance.
+
+New delivery intents fence later ordinary mutations until the original operation settles; cancellation retains its independent reserve. This prevents unrelated revision changes from being accepted as an interrupted operation's outcome. Legacy intents without this fence cannot use revision-only recovery and remain explicit reconciliation obligations.
+
+Explicit task-service refusals proven to precede effects are stored as compact acknowledged rejection receipts. Exact retries replay the bounded redacted code/message; corrected requests use a new identity and current revision. Unknown failures keep their intent and mutation fence rather than being classified as safe from an unchanged revision alone.