humanish 0.0.1 → 0.15.1

package/docs/architecture/terminal-product-lane.md

@@ -0,0 +1,148 @@
+# Terminal-product real-agent lane (issue #154)
+
+Date: 2026-06-16
+
+Status: SLICE 1 shipped — the config + routing skeleton, DRY-RUN only. The live
+in-sandbox backend, the command-scoped credential boundary, cleanup,
+interventions, the cost/no-spend ledger, and the product-adapter extension seam
+are later slices. See the ratified goal packet
+([`docs/goals/terminal-product-lane/goal.md`](../goals/terminal-product-lane/goal.md))
+for the full slice plan and the safety contract.
+
+## What this is
+
+A lab lane for **terminal-product real-agent studies**: a real autonomous coding
+agent (Codex) discovering and using a CLI/product from its **public surfaces
+only**, running **inside an E2B shell** with command-scoped runtime auth, capped
+at no-spend, emitting durable terminal/substrate/cost/no-spend/cleanup/
+intervention proof that verifies fail-closed. This is distinct from the browser
+lanes: it is not testing whether a browser can click a local web app — it tests
+whether an autonomous agent can discover and use a CLI/product surface from
+public materials.
+
+It rides the established lane-addition pattern (proven by the scripted-browser
+and local-app lanes): a new `subject.source` × `execution.target`, a routing
+predicate, a backend enum + dispatch, a registered actor with a capability lane,
+fail-closed cross-validation, and forward-declared warnings.
+
+## The composition
+
+| Axis | Value |
+| --- | --- |
+| `subject.source` | `terminal-product` |
+| `subject.product` | `{ name, publicSurfaces[] }` — the only world the agent sees |
+| `execution.target` | `e2b-terminal` (or absent → implied) |
+| `execution.terminal` | `{ transport: exec-stream, stdin: disabled }` |
+| `execution.runtimeAuth` | `openai-env` (names-only evidence this slice) |
+| `scenario.caps` | `{ maxUsd, maxJobs, maxMinutes }` — the blast-radius budget |
+| `policies` | `allowPrivateRepoAccess` / `allowProviderCredentials` / `allowPaymentCredentials` / `allowGitHubMutation`, all DEFAULT FALSE |
+| `actors[0].type` | `codex-exec` — a registered terminal actor (`keyPlacement: in-sandbox-command-scoped`) |
+| `LabBackend` | `terminal` → `runTerminalProductLab` ([`src/e2b-terminal-lab.ts`](../../src/e2b-terminal-lab.ts)) |
+
+Routing is `routesToTerminalProduct(config)` — the single source of truth that
+both `selectLabBackend` and the forward-declared-warning logic consume, mirroring
+`routesToComputerUse` / `routesToScriptedBrowser`.
+
+## The safety contract (the lane's reason to exist)
+
+This lane **inverts** the credential-placement default of every other E2B route.
+On the computer-use route the model's key stays *outside* the sandbox; here the
+agent-under-test runs *inside* with a real `OPENAI_API_KEY`/`CODEX_API_KEY` and
+is **presumed exfiltratable**. The doctrine (invariants-and-defaults.md, the
+placement rule): *keys live where the keyed process runs — and nowhere else;
+blast radius is bounded by key scoping and budgets, not by hoping.*
+
+The inversion is declared as registry metadata, not a code convention: the
+terminal actor's capabilities carry `keyPlacement: "in-sandbox-command-scoped"`.
+SLICE 1 ships the DECLARED field + value (the contract is honest about where the
+key would go); SLICE 2's engine enforces command-scoped injection (only into the
+per-command `envs` of the `codex` invocation, never `Sandbox.create({envs})`)
+keyed off that capability, plus the deny-by-default credential allowlist, the
+positive-allowlist sandbox metadata, the cleanup proof, the interventions ledger,
+and a minimal fail-closed cap.
+
+## SLICE 1 scope (DRY-RUN only — what is honest now)
+
+`runTerminalProductLab` implements ONLY the dry-run path: it builds a valid
+`humanish.run-bundle.v1` contract bundle, honestly labeled contract-only, with:
+
+- the subject declared as a terminal-product with its public surfaces, provenance
+  **UNPINNED** (the agent drives public surfaces, not a clone — invariant 5);
+- the author mission recorded as plaintext (public-safe committed lab text) + a
+  **digest** of the full composed prompt (nothing beyond the author mission goes
+  plaintext);
+- the caps / deny-by-default policies / runtime-auth channel recorded as
+  declarations (names only — invariant 1);
+- a terminal-kind stream that is an honest **contract placeholder**: stdin
+  disabled, empty tail, `transport: snapshot` — **not** `pty` (captured
+  non-interactive exec output is never an interactive PTY; invariant 6 + the
+  goal packet's PTY ruling). SLICE 2 fills the redacted exec-stream capture;
+- empty/placeholder ledgers (substrate lifecycle, command log, terminal event
+  stream, interventions, cost) that SLICE 2/3 fill.
+
+The dry-run bundle passes the EXISTING `verifyRun`. Terminal-specific verifier
+checks (terminal/transcript presence, lifecycle, cleanup, interventions,
+metadata allowlist, no-credential-in-artifacts, no-spend) are SLICE 2/3.
+
+A non-dry-run (live) call returns a structured `HUMANISH_TERMINAL_AGENT_NOT_IMPLEMENTED`
+failure (fail-closed, clear code) — it never creates a sandbox, never injects a
+key, never spends. SLICE 2 implements the real session.
+
+The DI seams SLICE 2 needs (`loadModule`, `buildSandbox`, `runtimeAuthEnv`,
+`detachedTimers`) are declared on `TerminalProductLabHooks` and threaded through
+`RunLabOptions.terminalHooks`, mirroring `cuaHooks` / `scriptedHooks` — but only
+the dry-run path is implemented this slice.
+
+## SLICE 4 — the product-adapter extension seam (layer 6)
+
+This lane is proof-roadmap **layer 6**: an adopter attaches product-specific
+scoring + feedback as a THIN in-repo extension WITHOUT forking core. SLICE 4
+ships the SEAM (not a built-in product scorer — the adopter's scorecard lives in
+the adopter's repo):
+
+- **Exported contract types** a thin adapter types against from the package
+  barrel (`humanish`) alone — never a deep `src/` import: `RunBundle`,
+  `RunFeedbackCandidate`, `RunAdapterScore`, `RunMeaningfulUseScore`
+  (+ `RunMeaningfulUseComponentId`), `ActorTrace`, and the terminal-lane
+  `TerminalProductScoringContext` / `TerminalLedgers` / `TerminalCostLedger` /
+  `NoSpendProof` / `CostLine` / record types. Before this slice these were not
+  exported — which FORCED a fork (a thin adapter could not type against the
+  bundle), the gap issue #154 acceptance #8 names.
+- **A registrable scorer / feedback DI hook** on `TerminalProductLabHooks`:
+  `score?(ctx: TerminalProductScoringContext) => RunAdapterScore | Promise<…>`
+  and `deriveFeedback?(ctx) => RunFeedbackCandidate[] | Promise<…>`. The lane
+  calls the hooks over the FULLY-ASSEMBLED, redacted evidence and attaches the
+  results (`bundle.adapterScore`, appended `bundle.feedbackCandidates`) WITHOUT
+  core knowing any product noun. Default (no hook) behavior is unchanged: the
+  mission-based verdict stands alone.
+- **Adapter-namespaced product nouns.** Product-specific concepts (public
+  CLI/product command observed, hosted product success-or-blocker, feedback
+  id/draft, media/job/asset ids, no-media/no-provider-spend proof,
+  defection/friction risk) ride ONLY under a single namespaced field
+  (`RunFeedbackCandidate.adapter: { namespace, data }` and
+  `RunAdapterScore.{namespace, data}`) so core's enums stay product-agnostic and
+  a future inert-field audit never misfires. No adopter noun is hardcoded into a
+  core enum (avoiding closed-taxonomy rot); `e2b-terminal` is added to the
+  substrate enum so a terminal-agent candidate names its substrate honestly.
+
+The seam is fail-closed: the lane scrubs+redacts the returned payloads and DROPS
+any malformed score/candidate with a warning, and `verifyRun` re-checks the
+surviving shapes — a bad extension never poisons a verifiable bundle. Proven by
+`tests/terminal-product-adapter-seam.test.ts` (a thin in-repo example adapter
+typing against the barrel only, registering a scorer, attaching namespaced nouns,
+emitting a candidate; the bundle verifies). No live rung — the seam is contract,
+not spend.
+
+The adopter's real scorecard is its OWN thin extension; the live receipt for the
+end-to-end lane is tracked under #159, and true duplex PTY replay is deferred to
+SLICE 5.
+
+## The reference adopter (codename-neutral)
+
+The requesting adopter is a public creative-CLI product (see issue #154 for its
+concrete public surfaces). Committed source and docs here stay codename-neutral
+per the public-surface scan; the committed CI fixture
+([`humanish/labs/terminal-product-demo.yaml`](../../humanish/labs/terminal-product-demo.yaml))
+uses a FICTIONAL mock CLI (`widgetsmith-cli`) with `example.com` surfaces. The
+adopter's real public surfaces appear only in operator-run docs and the GitHub
+issue, never in scanned committed text.

package/docs/contracts/adapter-fixtures.md

@@ -0,0 +1,80 @@
+# Adapter Fixture Parity Contract
+
+Date: 2026-06-02
+
+Status: v0 draft contract for public-safe adapter fixture parity.
+
+## Purpose
+
+Adapter fixtures prove that Humanish can carry target-specific evidence without
+moving target truth into core schemas. A fixture is not a product claim. It is a
+public-safe contract packet that shows the routes, personas, milestones,
+terminal evidence, feedback drafts, and policy decisions a real adapter must
+emit before live behavior can be trusted.
+
+The fixture contract keeps three boundaries explicit:
+
+- Core owns run-bundle identity, artifact layout, verification, review,
+  redaction, and feedback mechanics.
+- Adapters own target routes, scenario language, personas, milestone names,
+  command surfaces, and acceptance proof.
+- Public issue drafts use redacted artifact pointers only; they do not require
+  GitHub tokens, hosted product memory, private transcripts, or live mutation.
+
+## Fixture Set
+
+The committed fixture set lives under `adapters/fixtures/`.
+
+| Fixture | Proves | Required artifacts |
+| --- | --- | --- |
+| `post-auth-return-dry-run` | A web-app adapter can keep upload, studio, and auth-return milestones adapter-owned while emitting a product-neutral dry-run bundle. | `adapter.json`, `persona.json`, `scenario.json`, `milestones.json`, `run-bundle.json` |
+| `terminal-feedback-lifecycle` | A terminal-first adapter can emit sanitized transcript evidence, issue-draft material, cost/redaction policy, verification checks, and feedback lifecycle proof without browser-only assumptions. | `adapter.json`, `policy.json`, `run-bundle.json`, `feedback-draft.json`, `verify-result.json`, `transcripts/sanitized-terminal.txt` |
+
+## Promotion Gates
+
+A fixture can be promoted only when:
+
+- every example is synthetic or redacted;
+- artifact paths are relative and do not contain traversal segments, absolute
+  local paths, hosted stream URLs, or auth-bearing links;
+- credential policy records env var names only, never values;
+- adapter-owned nouns do not appear in core schema docs or core runtime code;
+- public feedback material states that GitHub mutation was not performed;
+- the fixture can be checked with `pnpm test tests/adapter-fixtures.test.ts`
+  and `pnpm public-surface:scan`.
+
+## Dry-Run Web-App Fixture Shape
+
+The web-app fixture models a local app with three adapter-owned route groups:
+
+- `upload`: synthetic file input and validation state;
+- `studio`: synthetic work surface and result-review state;
+- `auth-return`: a post-authentication return path using a synthetic state id.
+
+The dry-run bundle does not add route or milestone fields to core. Instead, it
+references adapter-owned routes through `streams[].ui.route`, milestone events
+through lifecycle/event records, and the milestone manifest through relative
+artifact pointers.
+
+## Terminal Feedback Fixture Shape
+
+The terminal fixture models a command-driven product surface. Its bundle uses a
+`terminal` evidence stream, a sanitized transcript pointer, a feedback
+candidate, a separate feedback draft artifact, and a verification result that
+checks required public-safe files without reading or requiring raw private
+transcripts. Policy is adapter-owned and records:
+
+- `spend_policy: no_spend`;
+- `network_policy: no_network`;
+- `github.mutation: not_requested`;
+- `hosted_product_memory.required: false`;
+- redaction status and denied material classes.
+
+This keeps terminal and feedback parity independent from browser screenshots.
+
+## Proof Commands
+
+```bash
+pnpm test tests/adapter-fixtures.test.ts
+pnpm public-surface:scan
+```

package/docs/contracts/core.md

@@ -0,0 +1,71 @@
+# Core Contract
+
+Date: 2026-06-02
+
+Status: v0 draft contract with tested primitive helpers in `src/core`.
+
+## Purpose
+
+Core is the reusable layer that makes a run bundle stable enough for agents,
+reviewers, and maintainers to trust. It owns generic run identity, artifact
+layout, source state summaries, lifecycle records, latest/history pointers, and
+timing summaries.
+
+Core does not own product routes, personas, scenarios, app topology, provider
+setup, or repository-specific proof language.
+
+## Public-Safe Defaults
+
+Core records must be safe to include in public run bundles by default:
+
+- artifact paths are relative;
+- run ids contain only lowercase letters, numbers, and dashes;
+- git state summarizes status without branch names, remotes, file names, file
+  paths, or absolute working directories;
+- lifecycle and timing records are explicit inputs, not inferred prose;
+- latest/history pointers identify local artifacts, not hosted private logs.
+
+## Primitive Set
+
+| Primitive | Contract |
+| --- | --- |
+| Run id | Deterministic from explicit prefix, timestamp, and entropy; valid ids match `^[a-z0-9][a-z0-9-]{0,127}$`. |
+| Artifact layout | Builds stable relative pointers under `.humanish/runs/<run-id>/` plus `.humanish/runs/latest.json`. |
+| Latest pointer | `{ schema, runId, path, updatedAt }` using `humanish.latest-run.v1`. |
+| History entry | `{ schema, runId, createdAt, mode, path }` using `humanish.run-history-entry.v1`. |
+| Lifecycle event | `{ at, event, message }`; event and message are required. |
+| Timing summary | `{ startedAt, endedAt, durationMs, status }`; running records have null end and duration. |
+| Git state | `{ schema, status, capturedAt, head, changes, note }` using `humanish.git-state.v1`. |
+
+## Git State Boundary
+
+Git state is intentionally lossy. It answers:
+
+- is this a work tree?
+- is it clean or dirty?
+- what short HEAD hash is available?
+- is HEAD attached, detached, unborn, or unknown?
+- how many staged, unstaged, and untracked entries exist?
+
+It does not record:
+
+- branch names;
+- remotes;
+- file names;
+- file paths;
+- absolute directories;
+- diffs;
+- commit messages.
+
+That makes it useful for repeatability and review without turning run bundles
+into a source leak.
+
+## Stop Conditions
+
+Core work stops if:
+
+- a core primitive needs a product-specific noun to make sense;
+- an artifact path can escape the run root;
+- a public record includes a raw cwd, branch name, remote, file name, diff, or
+  credential-like value;
+- a run id cannot be reproduced from explicit inputs.

package/docs/contracts/feedback.md

@@ -0,0 +1,145 @@
+# Feedback Contract
+
+Date: 2026-06-01
+
+Status: v0 local issue draft generation with run-candidate support.
+
+## Purpose
+
+Feedback is the bridge between simulation evidence and public issue filing.
+
+`humanish feedback` should let a persona simulation say:
+
+```text
+this user-like run found this concrete friction
+here is the evidence
+here is the likely owner
+here is the redaction proof
+here is the next state
+```
+
+It should not be an issue spammer, infra dependency, or generic comment
+collector.
+
+## Privacy Rule
+
+Feedback payloads must be public-safe by default. They may not contain PII,
+PHI, secrets, keys, tokens, raw private transcripts, private screenshots, raw
+customer data, raw patient data, or private product source.
+
+Public issue drafting fails closed if redaction cannot prove the payload is
+safe. A verified run bundle is not automatically public-promotable: feedback
+commands also require `humanish verify` to report
+`shareSafety.status: share_ready`.
+
+## Command Stages
+
+```bash
+humanish feedback list --run latest
+humanish feedback draft --run latest --json
+humanish feedback verify --run latest --json
+humanish feedback issue --run latest --repo owner/repo --format markdown
+humanish feedback issue-url --run latest --repo owner/repo
+```
+
+### `list`
+
+Reads feedback candidates from the run bundle. Does not mutate. Candidates are
+generated by lab/adapters when actor evidence identifies a concrete
+setup-quality gap, ceremonial/absent study quality, target-app blocker, or
+Humanish CLI blocker. The OSS
+meta-lab is one maintainer dogfood example, not the only candidate source.
+
+### `draft`
+
+Builds structured feedback from the strongest run candidate first. If no
+candidate is present, falls back to the dry-run contract follow-up. Writes a
+draft under the run bundle, not GitHub.
+
+### `verify`
+
+Checks schema, evidence pointers, idempotency key, redaction result, and public
+issue eligibility.
+
+### `issue`
+
+Prints or writes a public-safe GitHub issue body. It does not call the GitHub
+API. The user files the issue in the public or eventually public repository.
+
+### `issue-url`
+
+Prints a prefilled GitHub issue URL when the platform supports one. It still
+does not create the issue.
+
+## Schema
+
+```yaml
+humanish_feedback:
+  schema: humanish.feedback.v1
+  run_id: "<run-id>"
+  adapter_id: "<adapter-id>"
+  scenario_id: "<scenario-id>"
+  persona_id: "<persona-id-or-class>"
+  actor: "<actor-runtime>"
+  substrate: "<substrate>"
+  failure_owner: "harness|target-app|actor|environment|unknown"
+  summary: "<public-safe concrete summary>"
+  expected: "<public-safe expected behavior>"
+  actual: "<public-safe observed behavior>"
+  source_bundle: "<path-or-url>"
+  evidence:
+    - path: "<relative artifact pointer>"
+      kind: "screenshot|state|review|trace|log|filesystem"
+      note: "<public-safe note>"
+  redaction:
+    status: "passed|failed|not_applicable"
+    notes: "<public-safe note>"
+  idempotency_key: "<stable-key>"
+  proposed_next_state: "watch|adapter-hardening|target-app-setup|actor-auth|setup-quality-review|study-quality-review"
+  acceptance_proof:
+    - "<command or artifact that would close this>"
+  adapter:
+    namespace: "<adapter namespace>"
+    data: {}
+```
+
+`adapter` is optional and namespaced. Adapters may place product-specific
+concepts there (for example route groups, milestone ids, product acceptance
+details, or adopter-owned rubric data). Core validates only that `namespace` is
+non-empty and `data` is a record; keys inside `data` are never core enums.
+
+## Failure Owners
+
+| Owner | Meaning |
+| --- | --- |
+| `harness` | Humanish or adapter logic produced invalid evidence or execution. |
+| `target-app` | The target app setup, dev server, or local surface blocked the run. |
+| `actor` | The coding-agent/persona actor failed to complete a requested setup or usage path. |
+| `environment` | E2B, local browser, shell, filesystem, network, or dependency substrate failed. |
+| `unknown` | Evidence is useful but ownership is not yet clear. |
+
+## Issue Draft Gates
+
+Generating a public issue draft is blocked when:
+
+- required schema fields are missing;
+- source bundle is missing;
+- evidence pointers are missing or invalid;
+- redaction did not pass;
+- `shareSafety.status` is `local_only` or `blocked`;
+- any payload may contain PII, PHI, secrets, or private operational context;
+- proposed next state is `agent_ready` without a readiness block;
+- the feedback is a dry-run-only product claim;
+- idempotency key is missing.
+
+## GitHub Issue Semantics
+
+GitHub issues filed from feedback should say `contributes to` unless the
+acceptance proof closes the full product claim. The public issue should include
+only redacted evidence pointers and reproduction instructions that a maintainer
+can use without private local context.
+
+The public CLI should not require GitHub tokens, hosted product memory, queues,
+webhooks, Actions, databases, or Projects. Maintainers may later build separate
+repo-local tooling that consumes the same issue schema, but that is outside the
+default public feedback path.