PaperClipAI/doc/manual-e2e-private-evidence.md

# Restricted evidence for manual AWS E2E runs

The manual AWS workflow has a separate restricted evidence route. It uses the
existing private-history bucket, protected environments, OIDC role and bounded
archive transfer. It does not change the scheduled private-history lane.

GitHub Actions artifacts in a public repository are readable by repository
readers. They are not an organization-private evidence store. The restricted
route never uploads raw cell evidence or a merged report to Actions, S3 public
history, or Pages. This stays true on setup failure, launcher failure and report
failure. Previously staged files do not enable a public fallback.

## Supported selections

An approved original run selects at most **eight** distinct execution IDs from
one fixed registry of the frozen 244 chat scenarios. All use profile
`runner-opencode` and environment `local`. The 242 catalog tasks retain their
exact `area.case` IDs. The two standalone scenarios retain their existing task
IDs: `tasks.create-backlog` maps to
`chat-features.runner-opencode.local.create-backlog`, and
`tasks.delegate-announcement` maps to
`chat-features.runner-opencode.local.delegate-announcement`. The dotted task
aliases are not registered. The exact registry is in
`tests/runner-e2e/manual-private-retention.ts`.

These IDs require the reviewed AWS Fleet route. Broad chat suites, mixed
unsupported IDs, reruns and runs without dispatch authority fail closed. All chat-feature IDs
are classified as restricted by trusted code. A target descriptor cannot opt out.
Other manual selections keep the existing Actions route only after a trusted
per-cell check confirms that the actual selected execution is not restricted.
Selector whitespace and exclusivity follow the catalog producer.

The registry size does not increase the per-run limit or the eight fixed report
read slots. Classification, cell binding, every approval row and session policy
reject a private selection larger than eight before actionable outputs or archive
credentials. Generic nonprivate catalog selection retains its existing semantics.

A registered ID is not a claim of feature readiness or permission to run it.
Each target still needs the exact reviewed producer contracts, matching helper
bytes, declared private inputs, fresh source fingerprints, an available original
attempt and an allowlisted manual dispatch. Earlier accepted target branches do not
acquire these bytes automatically. Running jobs keep their pinned
sources. No retained grade or historical qualification transfers to a new target.

The private cell report contract binds the installed pinned Playwright producer
and the selected cell before it accepts canonical static trace files. Default
cell evidence keeps its existing unknown-carrier rules. Excluded installed build
staging is outside the evidence tree; unknown carriers inside standard evidence
paths still fail. A target with stronger ZIP or embedded-report scanning must
retain those checks when it adapts this contract. Installed-target identities
and runtime evidence remain separate from source-preparation metadata.

## Deployment and operator gates

This source change alone does not configure a role, bucket, environment, target,
or run. Before a supported run, the operator must:

1. Deploy this workflow and its helpers together on the protected default branch.
2. Keep the existing numeric actor allowlist and protected default-branch checks.
3. Keep `runner-e2e-private-paid` and `runner-e2e-private-history` restricted to
   the default branch.
4. Provide the existing private-history role ARN, AWS region and bucket variables
   in those environments. The existing role must support the existing bounded
   prefix and bucket-policy, ownership, public-access and retention reads.
5. Use a compatible target. Its private handoff and policy modules must match
   the workflow implementation byte for byte. Earlier target branches do not
   gain this protocol automatically.

### Dispatch authority

In `runner-full-stack-e2e.yml`, the manual run itself authorizes its private
evidence. There is no separate per-run approval record. Trusted code in
`tests/runner-e2e/manual-dispatch-authority.ts` admits a cell only when all of
these are true:

- The event is `workflow_dispatch` of this workflow on the default branch, with
  the `manual` cadence. Scheduled and bounded-cadence runs never qualify.
- The run is on attempt `1`. A rerun does not inherit authority.
- The dispatching actor is in `RUNNER_E2E_ALLOWED_ACTOR_IDS`, the event sender is
  that actor, and the triggering actor is the same person.
- The trusted cell selection equals the dispatch's own `id` input.

The authority binds the workflow SHA, the target SHA resolved by the authorize
job, the run ID and the cells. The dispatcher chooses and vouches for the target
branch, so its launcher digest is recorded in the private identity instead of
compared with a separately approved digest. Classification still happens before
the protected job, and a failed check still stops before target dependency
setup, archive credentials, model credentials or fixture secrets. The per-run
limit of eight cells is unchanged.

### Stored approval records

The TestOps catalog case workflow still passes a protected approval record as
`MANUAL_PRIVATE_APPROVALS_JSON`. That record has this closed shape (all values
below are placeholders):

```json
{
  "version": 1,
  "approvals": [{
    "workflowSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "targetSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "runId": "123456789",
    "attempt": "1",
    "executionIds": ["chat-features.runner-opencode.local.activity.agent-feedback"],
    "protocol": "paperclip.manual-private-evidence/v1",
    "launchSha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
  }]
}
```

## Trust and credential lifetime

The workflow checks out its own immutable `github.sha` into a separate directory.
It prepares pinned publication dependencies with `--ignore-scripts` and a
separate store before archive credentials. Transfers use that checkout's
absolute helper, tsx and archive-script paths. They do not load the target's
node_modules or an ambient Node loader. The target executes only after the
evidence authority and private-storage preflight pass.

The AWS action returns session credentials as step outputs, not job-wide
environment exports. Only trusted preflight and transfer steps receive those
outputs. Transfers require an explicit complete session and disable EC2 metadata
fallback. A failed or expired session fails retention. It never enables an
Actions upload. Exact-key session policies limit the intended transfer calls. Each current cell
uses its own two-object read session; the report writer uses a separate session.
Every generated policy is checked against the 2,048-character STS limit before
the credential action. No wildcard object access is added.

This is **operator-approved target execution**, not a sandbox for malicious
source. The protected job has OIDC permission. Its target launcher can inherit
the GitHub OIDC request environment, and the existing harness copies its process
environment into server/native children. A target that can request a new OIDC
session may re-assume the role. An inline session policy does not prevent that.
Reviewers must approve the complete exact target, not just its evidence flag.
This change does not alter IAM, OIDC trust, host roles or credential duration.

## Evidence and failure rules

The launcher keeps its ordinary standard evidence in an owned temporary root.
It preserves the original framework result before launcher result updates. It
also seals final packaged results after cleanup and campaign finalization.
The transfer validates exact file inventories and hashes before archiving.
It excludes instance databases, workspaces, credential registries, auth files,
raw capture directories and arbitrary files outside the standard evidence scope.
Free-form launcher console capture is not an approved retained carrier.

The existing credential scanners and PASS PNG, HTML, blob and snapshot checks
still apply. Original text, ZIP and media bytes receive those scans before
retention. Raw and encoded registered roots and provider-shaped names are also
rejected from original paths and inventories. Unknown extensions and SVG files
that the ordinary packager does not inspect cannot become complete originals.
Files cannot be silently dropped to meet a bound. Credential contamination,
unsupported carriers or a changed inventory stop the transfer. Missing required
PASS files still convert the attempt to infrastructure FAIL. The private inventory
retains all safe available originals and records `requiredEvidenceComplete: false`
and the exact missing list. Its `complete` field means the available file inventory
is complete; it does not certify PASS evidence completeness. Failed framework
attempts do not claim that PASS evidence checks ran. No file is synthesized and
no secret-bearing original is uploaded just because the bucket is private.

The existing archive bounds remain unchanged: at most 256 MiB of source files,
4,097 archive entries and 264 MiB transferred archive bytes. Duplicated original
and packaged files count toward those bounds. A run that exceeds a bound does
not have complete retained evidence and needs an explicit disposition.

Private objects use immutable conditional puts and version receipts under
`runner-e2e-private/bounded-v1/campaigns/gha-RUN_ID-1/`. Each cell has a hash-derived
object name. The report reads only the approved current cells and verifies each
archive against its retained transfer digest. Fresh merged HTML, blob, normalized output and report logs receive a final
standard-file scan and sealed inventory with the actual current report-step
credential roots, including its explicit AWS session. The report uses the same
raw, encoded-root and provider-shape checks before transfer. It retains the
scanned report in the same restricted store. A report error stays a report
error; retention does not change its grade or manufacture a public page.

Authenticated retrieval uses the existing private-history operator machinery
and approved bucket access. This PR does not grant a reader role or perform an
upload. Actual deployment, environment approval, compatible target fingerprints,
private storage access and one exact run approval remain operational gates.