owlrunkit 0.16.1 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.17.0
+
+- Adds an Agent-native persistent project model for milestones, workstreams,
+  WorkItems, dependencies, per-Agent assignments, checkpoints, decisions,
+  handoffs, integration gates, and evidence-backed data candidates.
+- Projects honest per-Agent progress from append-only artifacts instead of
+  accepting self-reported percentages. WorkItems may use predeclared measured
+  units, and execution-bound completion requires a trusted accepted closeout
+  with a released lease.
+- Adds blank-session takeover packets so a successor Agent can recover the
+  objective, assigned work, blockers, evidence, history, and next action without
+  relying on an old chat.
+- Adds `owlrunkit project` commands for initialization, assignment,
+  checkpointing, decisions, handoff, evidence capture, status, and takeover.
+- Adds an enforced Verification Envelope for real Formal checks with explicit
+  source/output/scratch/forbidden paths, environment, network, process,
+  timeout, setup/check/teardown, cleanup, and content-addressed evidence.
+- Provides a macOS sandbox backend and fails closed on platforms where the
+  declared filesystem, network, credential, process, and cleanup policy cannot
+  be proved.
+- Preserves the 0.16 execution, lease, SourceCandidate, closeout, fleet,
+  deployment, recovery, and authority boundaries.
+
 ## 0.16.1
 
 - Replaces mutable publication-state assertions in the bundled Codex Skill

package/README.md

@@ -8,7 +8,7 @@ evidence, then close out once.
 ## Install
 
 ```bash
-npm install --save-exact owlrunkit@0.16.1
+npm install --save-exact owlrunkit@0.17.0
 ```
 
 The `owlrunkit` bootstrap uses the project's exact locally bound CLI for
@@ -26,6 +26,35 @@ owlrunkit init --workspace /absolute/path/to/project
 owlrunkit doctor --workspace /absolute/path/to/project
 ```
 
+## Coordinate a multi-Agent project
+
+RunKit 0.17 keeps the project alive independently of any one Agent or chat.
+Define durable milestones, workstreams, WorkItems, dependencies, integration
+gates, and optional measured units, then record append-only assignment and
+checkpoint events:
+
+```bash
+owlrunkit project init --workspace . \
+  --definition scripts/runkit-contract/templates/team-project-definition.json
+owlrunkit project assign --workspace . \
+  --request scripts/runkit-contract/templates/team-project-event.json
+owlrunkit project status --workspace .
+owlrunkit project takeover --workspace . --agent agent-runtime
+```
+
+`project status` reports every Agent's active, waiting, completed, and failed
+work; unresolved dependencies and decisions; the ready queue; critical work;
+and integration gates. It does not accept a guessed completion percentage.
+Measured progress is allowed only when the unit and total were declared in the
+WorkItem. An assignment may bind an exact RunKit execution and lease; in that
+case, the WorkItem cannot complete until the execution has a trusted accepted
+closeout and its lease is released.
+
+The Agent-facing natural actions are stable: split and assign work, report
+status, open or resolve a decision, hand off, take over, capture evidence, and
+verify. The CLI is the durable implementation surface; users can keep speaking
+in project terms.
+
 ## Detect and apply project profiles
 
 Preview deterministic, project-local commands, or atomically adopt only
@@ -94,14 +123,24 @@ the authorized permission scope really changes. Repeating the same `check` or
 `finish` command resumes exact create-only artifacts after an interruption;
 different bytes fail closed.
 
-Formal accepted evidence currently admits only the built-in Node syntax check
-shown above: the exact `process.execPath`, `--check`, and an ordinary workspace
-file. Profile, package-manager, wrapper, and custom commands are rejected
-before spawn because RunKit does not yet enforce a filesystem-write and network
-sandbox for them. Existing full verification and legacy `verify` commands
-remain available for controlled execution, but their deny rules are not
-sandbox-equivalent and their output is not silently promoted into this Formal
-accepted-evidence path.
+Formal also accepts a real project command through an enforced Verification
+Envelope:
+
+```bash
+owlrunkit formal check --workspace . --run-id release-001 \
+  --work-item delivery --check-id project-tests \
+  --envelope scripts/runkit-contract/templates/verification-envelope.json
+```
+
+The envelope declares exact commands, cwd, lockfiles, environment, timeout,
+immutable source, writable outputs, disposable scratch, forbidden paths,
+network mode, subprocess policy, and bounded setup/check/teardown. RunKit
+captures stdout, stderr, output hashes, source before/after fingerprints,
+runner identity, cleanup, and a self-verifying receipt. The public 0.17 package
+provides a real macOS enforcement backend. If the current platform cannot prove
+the policy, the command is not run and no Formal acceptance is possible.
+Existing legacy verification may still capture evidence, but it is not silently
+promoted into this Formal path.
 
 Use `owlrunkit status --workspace .` for a concise human view of what is ready,
 what has not happened, how many gates remain, and the next allowed action.

package/docs/architecture/OWLCODA_RUNKIT_017_AGENT_NATIVE_PRODUCT_DEFINITION.md

@@ -0,0 +1,154 @@
+# OwlRunKit 0.17 Agent-Native Product Definition
+
+Status: implemented candidate pending Formal acceptance and public release.
+
+## Product purpose
+
+OwlRunKit exists so a software objective can outlive one chat, one Agent, and
+one execution attempt. Its public value is not the number of receipts it can
+produce. Its value is that a user can give a large objective to an Agent team,
+see who owns each part, recover the work after interruption, make decisions at
+the right point, and inspect the evidence behind the result.
+
+The 0.17 product sentence is:
+
+> A persistent project truth coordinates multiple Agents while RunKit proves
+> the work, handoffs, decisions, and delivery state behind that truth.
+
+0.17 is an upgrade of the 0.16 trustworthy-execution kernel, not a replacement.
+Executions, exact leases, SourceCandidate, verification receipts, closeouts,
+recovery, and authority boundaries remain the enforcement foundation.
+
+## Primary user experience
+
+The product is Agent-native. Users do not need to learn the internal command
+graph. Natural requests map to durable actions:
+
+| User intent | Agent action | Durable truth |
+| --- | --- | --- |
+| "Break this large task up and run it in parallel" | Define workstreams and work items, then assign Agents | Project definition and assignment events |
+| "What is everyone doing?" | Read the project projection | Per-Agent active, waiting, completed, and failed work |
+| "What is blocking us?" | Read dependencies, decisions, and critical work | Blockers, open decisions, ready queue, integration gates |
+| "I have decided" | Resolve the named decision with rationale and evidence | Append-only decision history |
+| "Hand this to another Agent" | Record a handoff, then create a successor assignment | Preserved assignment and handoff history |
+| "Continue this work" | Build a blank-session takeover packet | Goal, owned work, evidence, blocker, and next action |
+| "Verify and finish it" | Run the appropriate assurance lane and bind its result | Execution, lease, verification, closeout, and gate truth |
+| "Keep this as training data" | Record a provenance-bound candidate | Candidate only; never automatic dataset admission |
+
+The Agent may use CLI commands internally, but the user-facing interaction
+remains goal, progress, decision, and outcome oriented.
+
+## Persistent project model
+
+The minimum project truth consists of:
+
+- Project objective;
+- Milestones and workstreams;
+- WorkItems with dependency edges and non-overlapping owned paths;
+- AgentAssignment history, including optional exact RunKit execution and lease
+  binding;
+- Checkpoints with state, evidence, blockers, decision references, and the next
+  action;
+- DecisionNodes with an explicit Owner and append-only resolution;
+- IntegrationGates that cannot pass before their work and decision
+  prerequisites;
+- EvidenceLineage and data candidates with source, rights, input, output,
+  decision, verification, outcome, and version references.
+
+The WorkItem is persistent. An Agent is its current assignee. Reassigning an
+item does not replace its history or create a new project identity.
+
+## Honest progress contract
+
+RunKit does not accept self-reported completion percentages. Progress is one of:
+
+- a typed state: planned, active, waiting for a dependency, waiting for a
+  decision, verifying, ready to integrate, completed, or failed;
+- measured units against a total declared before work starts.
+
+A completed checkpoint requires evidence. If an assignment is bound to a
+RunKit execution, completion additionally requires a trusted accepted closeout
+and a released or preserved-inactive lease. A blocked or rejected execution is
+projected as failed even if an Agent claims success.
+
+Project status is derived from immutable definition and append-only events. It
+shows:
+
+- each Agent's active, waiting, completed, and failed work;
+- milestone and workstream completion counts;
+- unresolved dependencies and decisions;
+- critical work and the ready queue;
+- integration-gate readiness;
+- the exact project-truth hash and evidence references.
+
+## Cross-Agent continuity
+
+A blank-session Agent must be able to recover its part without reading an old
+chat. A takeover packet contains the project objective, its assigned work,
+current state, dependency and decision blockers, evidence, assignment history,
+and next action. Reading status or building a takeover packet is read-only.
+
+A handoff is two explicit events:
+
+1. the old Agent records what was done, the evidence, and the next action;
+2. a successor assignment names the new Agent and supersedes the old
+   assignment.
+
+This preserves responsibility history and prevents a chat summary from becoming
+the project system of record.
+
+## Verification Envelope
+
+Formal Delivery may execute a real project command only inside a
+Verification Envelope that declares and enforces:
+
+- exact executable, argv, working directory, lockfiles, environment allowlist,
+  and timeout;
+- immutable source, declared output, disposable scratch, and forbidden paths;
+- denied or loopback-only network;
+- subprocess policy and cleanup;
+- bounded setup, check, and teardown phases.
+
+The enforcement backend must prove these constraints. If it cannot, RunKit may
+capture an observation but cannot produce Formal-eligible evidence. The 0.17
+public package provides the enforced macOS backend; Linux remains fail-closed
+until equivalent process, filesystem, credential, network, and cleanup
+enforcement is available.
+
+## Data boundary
+
+Execution evidence can become a high-quality data candidate, but not a dataset
+member by implication. A candidate remains incomplete until its rights,
+decision, verification, and outcome references are present. Dataset selection,
+deduplication, adjudication, quality measurement, retention, and domain meaning
+remain separate responsibilities.
+
+## Authority boundary
+
+Project actions and Verification Envelopes never grant Git, release, publish,
+deploy, credential, destructive, production, or business authority. Existing
+RunKit authority checks remain mandatory. A status projection describes truth;
+it does not authorize the next side effect.
+
+## 0.17 acceptance standard
+
+The release is acceptable only when all of these are mechanically demonstrated:
+
+1. one project can project several Agents working in parallel;
+2. dependencies, decisions, handoffs, integration gates, and ready work are
+   derived from append-only artifacts;
+3. a fresh Agent can recover a bounded next action without old chat context;
+4. an execution-bound WorkItem cannot claim completion before accepted closeout
+   and lease release;
+5. concurrent assignments with overlapping owned paths are rejected;
+6. data candidates are not silently promoted into a dataset;
+7. real verification commands can enter Formal only under an enforced
+   Verification Envelope;
+8. source writes, undeclared outputs, forbidden credential reads, unauthorized
+   network, leaked processes, receipt drift, and unavailable enforcement all
+   fail closed;
+9. existing 0.16 execution, migration, fleet, deployment, and release contracts
+   remain compatible;
+10. the standalone npm artifact is reproducible, scrubbed, identity-bound, and
+    independently verified after publication.
+

package/integrations/codex/skills/owlcoda-runkit/SKILL.md

@@ -1,24 +1,58 @@
 ---
 name: owlcoda-runkit
-description: Run receipt-backed, project-owned software execution with OwlCoda RunKit. Use when Codex needs to initialize or inspect `.owlcoda/runkit/`, plan bounded work with engine pins and leases, capture exact shell or visual verification evidence, finalize delivery evidence, avoid duplicate covered tests, close an execution, produce a ready-for-commit receipt, or perform a read-only foreign-project shadow without widening Git or release authority.
+description: Run receipt-backed, project-owned work with OwlCoda RunKit. Use when Codex needs to coordinate a large multi-Agent project, show per-Agent progress, manage dependencies or decisions, hand work to another Agent, recover a blank-session next action, initialize or inspect `.owlcoda/runkit/`, plan bounded work with engine pins and leases, capture exact verification evidence, close an execution, produce a ready-for-commit receipt, or perform a read-only foreign-project shadow without widening Git or release authority.
 ---
 
 # OwlCoda RunKit
 
 Use the bundled deterministic Core to coordinate work through project artifacts rather than chat memory. Require Node.js 20 or later.
 
-Bundled release: standalone `owlrunkit@0.16.1`, bundling Contract `0.2` and
-Core `0.16.1` with manifest
-`sha256:38ac9110e328c38a81db05f1359734ca810b991c9f4de77647f9719f5e6af78b`.
+Bundled release: standalone `owlrunkit@0.17.0`, bundling Contract `0.2` and
+Core `0.17.0` with manifest
+`sha256:0c0c52e7f6299bdd3d3ea49005c8ceef0b28831d60af25d77da65a4e4de714c9`.
 Publication and dist-tag state are mutable registry facts: verify the exact
 official npm registry provenance before adoption. The immutable rollback
-baseline for this release is `owlrunkit@0.16.0` with SHA-1
-`bab651b0e10111a7a179a3a58917a8e90e43c35f` and canonical npm tarball URL
-`https://registry.npmjs.org/owlrunkit/-/owlrunkit-0.16.0.tgz`.
+baseline for this release is `owlrunkit@0.16.1` with SHA-1
+`1bc119d24879bdd8959af16b364af55ca9d61ea9` and canonical npm tarball URL
+`https://registry.npmjs.org/owlrunkit/-/owlrunkit-0.16.1.tgz`.
 The root `owlcoda` package has a separate version lifecycle.
 
 The session is an execution interface. Project artifacts are the system of record.
 
+## Agent-native project actions
+
+Translate ordinary user requests into durable project actions. Do not ask the
+user to operate the CLI when the request and authority are already clear.
+
+- "Split this large task and run it in parallel": initialize one project
+  definition before dispatch, then assign a distinct WorkItem to each Agent.
+- "What is everyone doing?": read `project status`; do not reconstruct progress
+  from chat updates.
+- "What is blocked or needs my decision?": report open decisions, unresolved
+  dependencies, critical work, and ready work from the projection.
+- "I decided ...": append a decision resolution with rationale and evidence.
+- "Hand this to another Agent": append the handoff, then a successor assignment;
+  never overwrite the old assignment.
+- "Continue/take over": build `project takeover` for the current Agent and use
+  its bounded next action and evidence refs.
+- "Capture this as data": append a data candidate only. Never call it a dataset
+  member without a separate admission decision.
+- "Verify/finish": select No RunKit, Quick, or Formal from risk; bind a Formal
+  WorkItem to its actual execution and lease when applicable.
+
+For a multi-Agent project, checkpoint meaningful state changes promptly. A
+checkpoint is not a heartbeat and must not contain a guessed percentage.
+Completion requires evidence. If an assignment binds an execution, derive its
+state from the closeout and lease rather than trusting the Agent's claim.
+
+```bash
+owlrunkit project init --workspace "$PROJECT_ROOT" --definition "$PROJECT_JSON"
+owlrunkit project assign --workspace "$PROJECT_ROOT" --request "$EVENT_JSON"
+owlrunkit project checkpoint --workspace "$PROJECT_ROOT" --request "$EVENT_JSON"
+owlrunkit project status --workspace "$PROJECT_ROOT" --json
+owlrunkit project takeover --workspace "$PROJECT_ROOT" --agent "$AGENT_ID" --json
+```
+
 ## Start safely
 
 1. Locate the project root and read its AGENTS.md chain.
@@ -285,13 +319,24 @@ create a linked successor only when authority or write scope truly changes.
 Repeating the same `check` or `finish` command resumes exact create-only
 artifacts; a mismatch fails closed.
 
-Formal accepted evidence currently admits only the built-in Node syntax check:
-the exact `process.execPath`, `--check`, and an ordinary workspace file.
-Profile, package-manager, wrapper and custom commands are rejected before
-spawn because RunKit does not yet enforce a filesystem-write and network
-sandbox for them. Full controlled execution and legacy `verify` remain
-available, but their deny rules are not sandbox-equivalent and their receipts
-must not be silently promoted into this Formal accepted-evidence path.
+Formal accepted evidence admits the built-in Node syntax check and real project
+commands executed through a Verification Envelope:
+
+```bash
+owlrunkit formal check \
+  --workspace "$PROJECT_ROOT" --run-id "$RUN_ID" \
+  --work-item "$WORK_ITEM_ID" --check-id "$CHECK_ID" \
+  --envelope "$VERIFICATION_ENVELOPE_JSON"
+```
+
+The envelope must declare exact executable, argv, cwd, lockfiles, environment,
+timeout, immutable source, declared output, disposable scratch, forbidden
+paths, network mode, subprocess policy, and setup/check/teardown. RunKit must
+actually enforce those constraints and verify cleanup. If the current platform
+has no suitable backend, it must refuse Formal evidence instead of running the
+command optimistically. The public 0.17 package provides the enforced macOS
+backend; Linux remains fail-closed. Legacy `verify` may capture evidence but
+must not be silently promoted into this Formal path.
 
 ## Freeze a dirty SourceCandidateV2
 

package/integrations/codex/skills/owlcoda-runkit/assets/templates/config.json

@@ -2,9 +2,9 @@
   "schemaVersion": "OwlCodaRunKitConfigV2",
   "core": {
     "contractVersion": "0.2",
-    "coreVersion": "0.16.1",
-    "coreManifestSha256": "sha256:38ac9110e328c38a81db05f1359734ca810b991c9f4de77647f9719f5e6af78b",
-    "coreSourceRef": "artifact:sha256:38ac9110e328c38a81db05f1359734ca810b991c9f4de77647f9719f5e6af78b"
+    "coreVersion": "0.17.0",
+    "coreManifestSha256": "sha256:0c0c52e7f6299bdd3d3ea49005c8ceef0b28831d60af25d77da65a4e4de714c9",
+    "coreSourceRef": "artifact:sha256:0c0c52e7f6299bdd3d3ea49005c8ceef0b28831d60af25d77da65a4e4de714c9"
   },
   "authorizationPolicy": "external_explicit_authority_required"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "owlrunkit",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Project-owned execution, evidence, verification, and recovery for coding agents.",
   "license": "GPL-3.0-or-later",
   "author": "yeemio <owlclaw@163.com>",

package/packages/attest/distribution-manifest-v1.json

@@ -36,6 +36,11 @@
     "sha256": "sha256:3972dc9744f6499f0f9b2dbf76696f2ae7ad8af9b23dde66d6af86c9dfb36986"
   },
   "supportedProducerCoreIdentities": [
+    {
+      "contractVersion": "0.2",
+      "coreVersion": "0.17.0",
+      "coreManifestSha256": "sha256:0c0c52e7f6299bdd3d3ea49005c8ceef0b28831d60af25d77da65a4e4de714c9"
+    },
     {
       "contractVersion": "0.2",
       "coreVersion": "0.16.1",

package/packages/attest/src/quick.mjs

@@ -18,6 +18,11 @@ import { captureWorkspaceSnapshot } from "./workspace-snapshot.mjs";
 export { validQuickReceiptShape } from "./quick-receipt-contract.mjs";
 
 export const SUPPORTED_QUICK_CORE_IDENTITIES = Object.freeze([
+  {
+    contractVersion: "0.2",
+    coreVersion: "0.17.0",
+    coreManifestSha256: "sha256:0c0c52e7f6299bdd3d3ea49005c8ceef0b28831d60af25d77da65a4e4de714c9",
+  },
   {
     contractVersion: "0.2",
     coreVersion: "0.16.1",

package/registry-release-policy-v1.json

@@ -2,7 +2,7 @@
   "schemaVersion": "OwlCodaRunKitRegistryReleasePolicyV1",
   "status": "release_candidate_unpublished",
   "packageName": "owlrunkit",
-  "candidateVersion": "0.16.1",
+  "candidateVersion": "0.17.0",
   "registry": "https://registry.npmjs.org",
   "registryRequiredBeforeAdoption": true,
   "exactVersionRequired": true,
@@ -23,10 +23,10 @@
   ],
   "currentPublishedRelease": {
     "packageName": "owlrunkit",
-    "version": "0.16.0",
-    "shasum": "bab651b0e10111a7a179a3a58917a8e90e43c35f",
-    "integrity": "sha512-qrlJueVypcetnFXAEHhDcYlZvpJAnTsbtLu9Rtp9SXNekAAD/rtBM8p2GqM5dOc1ERojixc3ipQkDGw6T7IR1A==",
-    "tarballUrl": "https://registry.npmjs.org/owlrunkit/-/owlrunkit-0.16.0.tgz"
+    "version": "0.16.1",
+    "shasum": "1bc119d24879bdd8959af16b364af55ca9d61ea9",
+    "integrity": "sha512-+DxKnADly7WIsGMiWDmo/rzG7XEsyqDtq7/1lUwqTf7aeekZJLw0qL5p7vm04YhgrTCd/rw9M0tUWihemYxyqQ==",
+    "tarballUrl": "https://registry.npmjs.org/owlrunkit/-/owlrunkit-0.16.1.tgz"
   },
   "registryRelease": null,
   "registryEvidenceMustBeExternal": true,

package/sbom.spdx.json

@@ -2,8 +2,8 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "owlrunkit-0.16.1",
-  "documentNamespace": "https://owlcoda.com/spdx/owlrunkit/0.16.1",
+  "name": "owlrunkit-0.17.0",
+  "documentNamespace": "https://owlcoda.com/spdx/owlrunkit/0.17.0",
   "creationInfo": {
     "created": "2026-07-29T00:00:00Z",
     "creators": [
@@ -14,8 +14,8 @@
     {
       "name": "owlrunkit",
       "SPDXID": "SPDXRef-Package-OwlRunKit",
-      "versionInfo": "0.16.1",
-      "downloadLocation": "https://registry.npmjs.org/owlrunkit/-/owlrunkit-0.16.1.tgz",
+      "versionInfo": "0.17.0",
+      "downloadLocation": "https://registry.npmjs.org/owlrunkit/-/owlrunkit-0.17.0.tgz",
       "filesAnalyzed": false,
       "licenseConcluded": "GPL-3.0-or-later",
       "licenseDeclared": "GPL-3.0-or-later",
@@ -24,7 +24,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/owlrunkit@0.16.1"
+          "referenceLocator": "pkg:npm/owlrunkit@0.17.0"
         }
       ]
     }

package/scripts/runkit-contract/core-contract.mjs

@@ -14,7 +14,7 @@ import { fileURLToPath } from "node:url";
 import { parseProjectControlState } from "./project-control-parser.mjs";
 
 export const CONTRACT_VERSION = "0.2";
-export const CORE_VERSION = "0.16.1";
+export const CORE_VERSION = "0.17.0";
 export const RUNTIME_ROOT = ".owlcoda/runkit";
 
 const CORE_FILES = [
@@ -65,7 +65,10 @@ const CORE_FILES = [
   "snapshot.mjs",
   "source-candidate.mjs",
   "source-fingerprint.mjs",
-  "sync-core016-release-identity.mjs",
+  "sync-release-identity.mjs",
+  "team-project.mjs",
+  "verification-envelope.mjs",
+  "verification-envelope-check.mjs",
   "verification-receipt-gate.mjs",
   "verification-context.mjs",
   "verification-plan.mjs",
@@ -117,6 +120,10 @@ const CORE_FILES = [
   "schemas/visual-smoke-request-v1.schema.json",
   "schemas/visual-smoke-result-v1.schema.json",
   "schemas/verification-context-v1.schema.json",
+  "schemas/team-project-definition-v1.schema.json",
+  "schemas/team-project-event-v1.schema.json",
+  "schemas/team-project-status-v1.schema.json",
+  "schemas/verification-envelope-v1.schema.json",
   "schemas/verification-finalize-attempt-v1.schema.json",
   "schemas/verification-preflight-v1.schema.json",
   "schemas/verification-plan-v1.schema.json",
@@ -141,6 +148,9 @@ const CORE_FILES = [
   "templates/visual-smoke-request.json",
   "templates/verify-plan-request.json",
   "templates/worker-lease.json",
+  "templates/team-project-definition.json",
+  "templates/team-project-event.json",
+  "templates/verification-envelope.json",
 ];
 
 const CORE_DEPENDENCY_FILES = [