RunSpecimen

RunSpecimen is a local safety and evidence layer for consequential agent-driven research and engineering commands.

Current package version (this branch): 0.2.0rc14
Release: v0.2.0-rc.14 / PyPI runspecimen==0.2.0rc14 (identical bytes; checksum-only, not SLSA-attested).
Do not publish draft v0.2.0-rc.11 (points at ecc1709). Do not move v0.2.0-rc.12. See docs/RELEASE_IDENTITY.md.

Core promise

Exactly one approved, bounded run at a time, with:

1. Approved provenance — interactive TTY approval binds contract, source, and resolved executable hashes with expiry
2. Crash-safe state — atomic JSON state writes
3. Mandatory postflight — successor runs refuse an unpostflighted / failed predecessor
4. Tamper-evident receipts — append-only SHA-256 hash-chained event log + verifiable certificate

No watchers, no recurring scheduler, no parallel workers.

0.2.0rc14 includes opt-in isolation (none by default), a workspace policy file, retain, digest, and diff. See docs/USER_GUIDE.md. none does not confine the process. sandbox-exec and bwrap are not an OS sandbox. Published 0.2.0rc12 rejects isolation and policy.

Requirements

• Python 3.9+
• POSIX (fcntl leases)
• Stdlib only (no third-party dependencies)

Docs

• About — what RunSpecimen does, lifecycle, safety model, dashboard role
• User guide — install, lifecycle, contracts, dashboard, plugins, troubleshooting
• FAQ — vs CI/sandbox/agents, TTY approval, verify-after-clone, parallelism, receipts
• Product plan — invariants and roadmap
• Market and distribution — wedge, channels, commercial sequence
• Integrations — adapter status ledger + frontier-lab research
• Marketing pitches — honest one-liners, elevators, CTAs
• Grok tandem — external xAI Grok review log (Composio GROK_*)
• Submission — marketplace submission checklist (Cursor/Codex/Claude/Grok)
• Release identity — live vs draft vs next tag; checksum-only vs attested
• Threat model — trusted boundary and residual risks
• Schema compatibility — contract/receipt versions
• Ed25519 receipts (optional) — offline public-key verify
• Phased roadmap — feature and UX pipeline
• ADR-003 iOS companion observation — remote observe / attention (Accepted defaults: loopback HTTP OK; LAN TLS + Tailscale preferred)
• ADR-004 remote human confirm — Mac-armed challenge + phone APPROVE (not TTY-equivalent; plugins cannot approve)
• Incident bundle — local Community evidence pack (runspecimen bundle); not a Veto vault
• Remote confirm card — one-card iOS UX, refuse+reason, confirm_channel on verify
• iOS Observe app — com.darashkevich.runspecimen.observe (TestFlight/later)
• macOS companion helper — com.darashkevich.runspecimen.companion (not MAS packaging / PR #6)
• macOS app — native SwiftUI companion (sandbox-first; see APP_STORE.md)

Install

From PyPI

python3 -m pip install runspecimen==0.2.0rc14
runspecimen --version

Pin the version. pip will not select an RC without ==0.2.0rc14. The rc11 draft tag must stay unpublished.

PyPI project: runspecimen 0.2.0rc14

From Homebrew

brew tap darashkevich/runspecimen
brew install runspecimen
runspecimen --version

Or: brew install darashkevich/runspecimen/runspecimen.

Tap: darashkevich/homebrew-runspecimen. Pins the same v0.2.0-rc.14 sdist as the GitHub Release (not main).

If runspecimen --version lags brew, check which -a runspecimen — an old ~/.local/bin/runspecimen often shadows /opt/homebrew/bin/runspecimen. Rename the shim and rehash; details in docs/FAQ.md.

From GitHub release

python3 -m pip install https://github.com/darashkevich/runspecimen/releases/download/v0.2.0-rc.14/runspecimen-0.2.0rc14-py3-none-any.whl

Or from source tarball:

python3 -m pip install https://github.com/darashkevich/runspecimen/releases/download/v0.2.0-rc.14/runspecimen-0.2.0rc14.tar.gz

Verify checksums: SHA256SUMS

From local clone

git clone https://github.com/darashkevich/runspecimen
cd runspecimen
python3 -m pip install .

For development, prefer the bootstrap. It pins setuptools>=77 and performs a regular local install; this avoids an editable-install edge case in some Python builds where the command is created but cannot import the package:

sh scripts/bootstrap_dev.sh

Or manually: python3 -m pip install --upgrade 'setuptools>=77' wheel then python3 -m pip install --no-build-isolation .. Stock setuptools before 77 rejects the project metadata used by scripts/release_check.py. Re-run the install after source edits.

Check the host and contract before approval. After a pip install, there is no repository examples/ tree in the current directory — create one with init-demo (or clone the repo and use examples/demo_contract.json):

runspecimen init-demo --workspace ./runspecimen-demo
cd runspecimen-demo
runspecimen doctor --workspace .
runspecimen validate --workspace . --contract contract.json

From a git checkout you can instead validate the in-tree example:

runspecimen doctor --workspace .
runspecimen validate --workspace . --contract examples/demo_contract.json

Typical sequence

Prefer init-demo after a pip/Homebrew install. The block below uses the in-tree example path (git clone) or substitute contract.json inside an init-demo workspace:

# 1) Bind approval on a real TTY (refuses pipes/CI without a TTY)
runspecimen approve --workspace . --contract examples/demo_contract.json

# 2) Optional explicit preflight
runspecimen preflight --workspace . --contract examples/demo_contract.json

# 3) Execute one bounded run (reacquires lease + rechecks under lease)
runspecimen run --workspace . --contract examples/demo_contract.json

# 4) Assert outcomes and issue certificate (required before a successor)
runspecimen postflight --workspace . --contract examples/demo_contract.json

# 5) Verify receipts (requires contract; rehashes live contract+source+runtime)
runspecimen verify --workspace . --contract examples/demo_contract.json \
  --campaign-id demo-campaign --run-id run-001
runspecimen status --workspace . --campaign-id demo-campaign --run-id run-001

# Optional: local incident pack (Community). Never a 7-day Veto vault.
runspecimen bundle --workspace . --campaign-id demo-campaign --run-id run-001 \
  --out /tmp/rs-incident --contract examples/demo_contract.json

Local dashboard for agent-host users

Open a contract-scoped dashboard from a terminal, or ask the installed RunSpecimen integration (Codex / Cursor / Claude Code / Grok Build / Gemini CLI / Junie / Windsurf) to do so:

runspecimen dashboard --workspace . --contract examples/demo_contract.json --open

dashboard blocks in the foreground while it serves HTTP. Background it (&), detach it, or use a separate terminal if you still need the shell for approve / lifecycle commands (agents should not wait on it in the main turn).

It binds only to 127.0.0.1, has no remote service or telemetry, and is read-only: it shows an About overview, the current phase, approval/lease/receipt evidence, and the exact lifecycle commands. It cannot approve or execute a run. This keeps the real-TTY approval gate and the CLI enforcement boundary intact while making the workflow visible in the browser. Docs links open the published About, User guide, and FAQ on GitHub. CLI shortcut: runspecimen about.

Showcase receipt

examples/showcase/ holds a regeneratable postflight receipt with outputs/result.json. Verify it with:

runspecimen verify --workspace examples/showcase \
  --contract examples/showcase/contract.json \
  --campaign-id showcase-campaign --run-id run-001

Refresh without a TTY (uses the library test hook skip_tty_check; not for production approvals): python3 scripts/refresh_showcase.py. Interactive TTY path: scripts/demo_rc.sh.

Any local /.runspecimen/runs/demo-campaign/run-001 left from earlier RCs is historical / pre-runtime certificate and is not verifiable on rc2.

Contract surface (v1)

See examples/demo_contract.json. Important fields:

Field	Role
argv	Executed as an argument vector (shell=False always)
source.roots / excludes	Deterministic source hashing / provenance
outputs.required	Must be absent at preflight; present at postflight when required
caps.*	Wall timeout + bounded stdout/stderr capture (hard tool maxima apply)
approval.ttl_sec	Approval expiry bound into the approval document
predecessor	Gate on prior run postflight / failure
postflight.*	Exit code, output existence/SHA, JSON field equality, source unchanged

Every path involved in an output existence, SHA-256, or JSON assertion must be absent before launch and is hashed into the receipt after it passes.

State layout

Per run under {workspace}/.runspecimen/runs/{campaign_id}/{run_id}/:

• approval.json — bound hashes + expiry
• state.json — atomic phase document
• events.jsonl — hash-chained append-only log (events.append.lock serializes appends)
• stdout.capture / stderr.capture — bounded captures
• certificate.json — postflight receipt

Workspace-wide execution lease: {workspace}/.runspecimen/execution.lock (held by approve/preflight/run/postflight; status is read-only).

New in rc9: Missing features implemented

Crash recovery with audited human decisions

When a run crashes mid-execution, use the new recovery commands:

# Check if a run needs recovery
runspecimen recovery-status --workspace . --campaign-id demo --run-id run-001

# Abandon a crashed run (TTY confirmation required)
runspecimen abandon --workspace . --campaign-id demo --run-id run-001

Authenticated receipts (shared-secret)

Authenticate certificates with local HMAC keys for tamper detection:

# Generate an authentication key
runspecimen keygen --workspace .

# List available keys
runspecimen list-keys --workspace .

# Authenticate a certificate (creates .signed.json with MAC)
runspecimen sign --workspace . --key-id <key-id> --certificate path/to/certificate.json

# Verify an authenticated certificate
runspecimen verify-signature --workspace . --key-id <key-id> --signed path/to/certificate.signed.json

Shared-secret limitation: HMAC-SHA256 uses the same key for authentication and verification. Anyone with the key can forge certificates. For independent third-party verification without sharing secrets, use asymmetric cryptography.

Extended runtime provenance

Contracts now support a runtime field for enhanced provenance binding:

{
  "runtime": {
    "env_allowlist": ["PATH", "HOME", "PYTHONPATH"],
    "interpreter": "/usr/bin/python3",
    "capture_libs": true
  }
}

This binds environment variables, interpreter, and optionally linked libraries into the certificate's runtime_id.

Release-candidate limitations

• Default authenticated receipts use HMAC-SHA256 shared-secret MACs. Anyone with the key can forge certificates. Optional Ed25519 offline public-key verification is available via pip install 'runspecimen[ed25519]' (see docs/ED25519_RECEIPTS.md). Trusted Ed25519 verify requires an external public-key trust anchor; a key embedded only in the receipt is never enough for ok: true. Soft keys on disk are not absolute non-repudiation.

• Default isolation.backend is none: the workload is not confined. Published 0.2.0rc14 accepts opt-in sandbox-exec and bwrap when the contract names them and the tool is installed; a missing tool fails closed. Those backends can confine writes to the workspace and deny network. They are not an OS sandbox. Linux CI installs bubblewrap and runs a real bwrap spawn regression when the tool is present; macOS does not execute bwrap. CPU, memory, and child-process limits are not part of either backend. Published 0.2.0rc12 rejects the isolation field. Optional Ed25519 is not an OS sandbox. A companion app’s UI sandbox (if any) does not imply payload confinement.

• RunSpecimen does not schedule work and does not prove scientific claims.

• The resolved executable or interpreter is automatically hashed. Native libraries, environment variables, and input datasets still need to be placed in source.roots or otherwise asserted by the workload.

• This release is licensed under Apache-2.0. The CLI remains the enforcement boundary; Codex, Cursor, Claude Code, Grok Build, Gemini CLI, Junie, and Windsurf integrations are constrained adapters to it (no auto-approve).

Non-goals

• Not an OS sandbox. Process groups, wall clocks, and path containment are orchestration controls, not a security boundary against a hostile payload.
• Finite computation is not proof. A green postflight and a valid certificate mean the approved contract ran under recorded provenance and assertions passed — not that the scientific/engineering claim is true.
• Not a job scheduler. No cron, no watchers, no fan-out workers, no multi-run parallelism inside one lease domain.
• Not a remote execution fabric. Local workspace only.

Tests

python3 -m unittest discover -s tests -v

For the complete release-candidate gate, run python3 scripts/release_check.py. Day-to-day usage: about, user guide, and FAQ. Before sensitive work: threat model, release checklist, and security policy.