Define agent harness terminal receipt surface

.github/workflows/agent-harness-terminal-receipts.yml

@@ -0,0 +1,37 @@
+name: Agent Harness Terminal Receipts
+
+on:
+  pull_request:
+    paths:
+      - 'docs/sourceos/AGENT_HARNESS_TERMINAL_RECEIPTS.md'
+      - 'schemas/agent-harness-terminal-receipts.schema.json'
+      - 'examples/agent-harness-terminal-receipts.example.json'
+      - 'scripts/verify-agent-harness-terminal-receipts.py'
+      - '.github/workflows/agent-harness-terminal-receipts.yml'
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/sourceos/AGENT_HARNESS_TERMINAL_RECEIPTS.md'
+      - 'schemas/agent-harness-terminal-receipts.schema.json'
+      - 'examples/agent-harness-terminal-receipts.example.json'
+      - 'scripts/verify-agent-harness-terminal-receipts.py'
+      - '.github/workflows/agent-harness-terminal-receipts.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  validate-agent-harness-terminal-receipts:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Validate TurtleTerm Agent Harness receipts
+        run: python3 scripts/verify-agent-harness-terminal-receipts.py

docs/sourceos/AGENT_HARNESS_TERMINAL_RECEIPTS.md

@@ -0,0 +1,184 @@
+# Agent Harness Terminal Receipt Surface
+
+Status: v0.1 planning baseline  
+Owner plane: TurtleTerm governed terminal/operator surface  
+Consumers: SourceOS spec, AgentPlane, Policy Fabric, Memory Mesh, SCOPE-D, Delivery Excellence
+
+## Purpose
+
+TurtleTerm is the SourceOS policy-aware, agent-addressable terminal workbench. The Aden/Hive production-agent pattern requires terminal work to be visible, bounded, receipt-producing, and measurable. TurtleTerm should make terminal/operator execution auditable without granting ambient shell authority to agents or cognition layers.
+
+## Boundary
+
+TurtleTerm owns:
+
+- terminal/session UX
+- command wrapper behavior
+- local agent gateway surface
+- terminal receipts
+- operator approval surfaces
+- tmux/mux bridge receipts
+- skill manifests for terminal operations
+- replayable operator workflows
+
+TurtleTerm does not own:
+
+- AgentPlane graph execution
+- Policy Fabric gate authority
+- Agent Machine runtime provider lifecycle
+- Delivery Excellence scoreboards
+- Memory Mesh artifact storage
+- SCOPE-D security exercise execution
+
+## Receipt classes
+
+### TerminalSessionReceipt
+
+Records an operator or agent-addressable terminal session.
+
+Required semantics:
+
+- terminal session id
+- actor/agent ref
+- workspace ref
+- shell profile
+- gateway profile
+- policy admission ref
+- AgentPlane run/session refs
+- start/end timestamps
+- mux/tmux pane refs when applicable
+- environment profile hash
+
+### CommandReceipt
+
+Records a command execution through TurtleTerm.
+
+Required semantics:
+
+- command id
+- terminal session ref
+- command hash
+- command display text when policy permits
+- working directory
+- environment profile hash
+- stdin/stdout/stderr artifact pointer refs
+- exit code
+- duration
+- policy decision ref
+- side-effect class
+- replay eligibility
+
+### MutationReceipt
+
+Records observed filesystem, process, deployment, or host mutation.
+
+Required semantics:
+
+- mutation id
+- command ref
+- mutation class
+- target scope
+- dry-run/live-run mode
+- policy decision ref
+- human-control event ref when required
+- before/after artifact refs when available
+- rollback ref
+- denied operation refs
+
+### OperatorApprovalReceipt
+
+Records human operator decisions in TurtleTerm.
+
+Required semantics:
+
+- approval id
+- actor ref
+- subject ref
+- decision
+- reason
+- timestamp
+- policy gate ref
+- AgentPlane run/session ref
+- Delivery Excellence human-control event ref
+
+## Controlled actions
+
+Require Policy Fabric decisions for:
+
+- package install
+- filesystem mutation outside workspace scope
+- deployment/apply operations
+- service start/stop/restart
+- network listener creation
+- secret/key material access
+- credential helper invocation
+- privilege escalation
+- destructive command patterns
+- host mutation
+- cluster mutation
+
+Fail closed when controlled actions lack a policy decision ref.
+
+## AgentPlane integration
+
+AgentPlane should cite TurtleTerm receipts in:
+
+- RunArtifact
+- ReplayArtifact
+- SessionEnvelope
+- EvidencePack
+- FailureDiagnosis
+- PromotionGate
+
+TurtleTerm receipts should preserve enough evidence for replay, diagnosis, and customer-safe proof without exposing raw secrets.
+
+## Memory Mesh integration
+
+Large stdout/stderr, shell transcripts, generated files, diffs, and terminal artifacts should be moved behind Memory Mesh `ArtifactPointer` refs when large, sensitive, replay-critical, or customer-proof relevant.
+
+## Delivery Excellence integration
+
+Delivery Excellence should consume derived metrics/readouts:
+
+- command success/failure
+- policy-blocked command count
+- host mutation denied/approved/performed
+- approval latency
+- replay-eligible command count
+- operator intervention count
+- terminal workflow cycle time
+- customer-safe proof of operator work
+
+Delivery Excellence should not consume raw terminal transcripts unless policy explicitly permits it.
+
+## SCOPE-D integration
+
+SCOPE-D should validate TurtleTerm workflows for:
+
+- command injection
+- shell escape
+- destructive command bypass
+- privilege escalation
+- secret exfiltration
+- unauthorized filesystem mutation
+- unauthorized service exposure
+- hostile generated scripts
+- host/cluster mutation bypass
+
+## Non-negotiables
+
+- TurtleTerm must not grant ambient shell authority to agents.
+- Agent Machine owns machine-local runtime provider lifecycle.
+- Policy Fabric decides controlled action authority.
+- Command outputs may need redaction and artifact pointers.
+- Host mutation must be explicit, policy-referenced, and rollback-aware.
+- Human approvals are typed control events, not freeform notes.
+- Delivery Excellence receives metrics and readouts, not uncontrolled shell logs.
+
+## Near-term implementation path
+
+1. Align TurtleTerm command wrapper receipts with SourceOS `ShellReceiptEvent` and SourceOS execution receipt boundaries.
+2. Add examples for terminal session, command, mutation, and operator approval receipts.
+3. Add a verifier requiring policy refs for controlled action classes.
+4. Add Delivery Excellence projection examples for command success, mutation posture, and approval latency.
+5. Add SCOPE-D terminal-risk checks for command injection, secret access, host mutation, and shell escape.

examples/agent-harness-terminal-receipts.example.json

@@ -0,0 +1,50 @@
+{
+  "schemaVersion": "v0.1",
+  "kind": "AgentHarnessTerminalReceipts",
+  "terminalSessionReceipt": {
+    "sessionId": "turtleterm-session-agent-harness-v0.1",
+    "actorRef": "github://mdheller",
+    "workspaceRef": "github://SocioProphet/sociosphere",
+    "shellProfile": "sourceos-local-dev",
+    "gatewayProfile": "turtle-agentd-local",
+    "policyAdmissionRef": "github://SocioProphet/policy-fabric/pull/60",
+    "agentplaneRunRef": "github://SocioProphet/agentplane/pull/107",
+    "muxPaneRefs": [],
+    "environmentProfileHash": "sha256:1111111111111111111111111111111111111111111111111111111111111111"
+  },
+  "commandReceipt": {
+    "commandId": "command-agent-harness-validate-runtime-contracts",
+    "terminalSessionRef": "turtleterm-session-agent-harness-v0.1",
+    "commandHash": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
+    "workingDirectory": "~/dev/agentplane",
+    "environmentProfileHash": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
+    "stdoutPointerRef": "artifact://sha256/3333333333333333333333333333333333333333333333333333333333333333",
+    "stderrPointerRef": "artifact://sha256/4444444444444444444444444444444444444444444444444444444444444444",
+    "exitCode": 0,
+    "policyDecisionRef": "github://SocioProphet/policy-fabric/pull/60",
+    "sideEffectClass": "none",
+    "replayEligible": true
+  },
+  "mutationReceipt": {
+    "mutationId": "mutation-none-agent-harness-v0.1",
+    "commandRef": "command-agent-harness-validate-runtime-contracts",
+    "mutationClass": "none",
+    "targetScope": "workspace-only",
+    "mode": "dry-run",
+    "policyDecisionRef": "github://SocioProphet/policy-fabric/pull/60",
+    "humanControlEventRef": "",
+    "rollbackRef": "",
+    "mutatedHost": false,
+    "deniedOperationRefs": []
+  },
+  "operatorApprovalReceipt": {
+    "approvalId": "operator-approval-agent-harness-baseline",
+    "actorRef": "github://mdheller",
+    "subjectRef": "github://SourceOS-Linux/TurtleTerm/pull/5",
+    "decision": "deferred",
+    "reason": "Baseline receipt fixture only; live terminal mutation approval is not requested.",
+    "policyGateRef": "github://SocioProphet/policy-fabric/pull/60",
+    "agentplaneRunRef": "github://SocioProphet/agentplane/pull/107",
+    "deliveryExcellenceEventRef": "github://SocioProphet/delivery-excellence-automation/pull/7"
+  }
+}

schemas/agent-harness-terminal-receipts.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sourceos.dev/schemas/turtleterm/agent-harness-terminal-receipts.schema.json",
+  "title": "AgentHarnessTerminalReceipts",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "terminalSessionReceipt", "commandReceipt", "mutationReceipt", "operatorApprovalReceipt"],
+  "properties": {
+    "schemaVersion": { "const": "v0.1" },
+    "kind": { "const": "AgentHarnessTerminalReceipts" },
+    "terminalSessionReceipt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sessionId", "actorRef", "workspaceRef", "shellProfile", "gatewayProfile", "policyAdmissionRef", "agentplaneRunRef", "environmentProfileHash"],
+      "properties": {
+        "sessionId": { "type": "string" },
+        "actorRef": { "type": "string" },
+        "workspaceRef": { "type": "string" },
+        "shellProfile": { "type": "string" },
+        "gatewayProfile": { "type": "string" },
+        "policyAdmissionRef": { "type": "string" },
+        "agentplaneRunRef": { "type": "string" },
+        "muxPaneRefs": { "type": "array", "items": { "type": "string" } },
+        "environmentProfileHash": { "type": "string" }
+      }
+    },
+    "commandReceipt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["commandId", "terminalSessionRef", "commandHash", "workingDirectory", "environmentProfileHash", "exitCode", "policyDecisionRef", "sideEffectClass", "replayEligible"],
+      "properties": {
+        "commandId": { "type": "string" },
+        "terminalSessionRef": { "type": "string" },
+        "commandHash": { "type": "string" },
+        "workingDirectory": { "type": "string" },
+        "environmentProfileHash": { "type": "string" },
+        "stdoutPointerRef": { "type": "string" },
+        "stderrPointerRef": { "type": "string" },
+        "exitCode": { "type": "integer" },
+        "policyDecisionRef": { "type": "string" },
+        "sideEffectClass": { "type": "string", "enum": ["none", "workspace-write", "host-mutation", "secret-access", "network-service", "deployment"] },
+        "replayEligible": { "type": "boolean" }
+      }
+    },
+    "mutationReceipt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mutationId", "commandRef", "mutationClass", "targetScope", "mode", "policyDecisionRef", "mutatedHost"],
+      "properties": {
+        "mutationId": { "type": "string" },
+        "commandRef": { "type": "string" },
+        "mutationClass": { "type": "string" },
+        "targetScope": { "type": "string" },
+        "mode": { "type": "string", "enum": ["dry-run", "live"] },
+        "policyDecisionRef": { "type": "string" },
+        "humanControlEventRef": { "type": "string" },
+        "rollbackRef": { "type": "string" },
+        "mutatedHost": { "type": "boolean" },
+        "deniedOperationRefs": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "operatorApprovalReceipt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["approvalId", "actorRef", "subjectRef", "decision", "policyGateRef", "agentplaneRunRef", "deliveryExcellenceEventRef"],
+      "properties": {
+        "approvalId": { "type": "string" },
+        "actorRef": { "type": "string" },
+        "subjectRef": { "type": "string" },
+        "decision": { "type": "string", "enum": ["approved", "rejected", "deferred", "accepted-risk", "revoked"] },
+        "reason": { "type": "string" },
+        "policyGateRef": { "type": "string" },
+        "agentplaneRunRef": { "type": "string" },
+        "deliveryExcellenceEventRef": { "type": "string" }
+      }
+    }
+  }
+}