@cairnkeep/cli 2.24.0 → 2.25.0

package/docs/privacy-and-data-flow.md

@@ -71,12 +71,12 @@ timestamp, and the supplied actor/session labels. It excludes prompt content,
 file content, patches, command output, secrets, endpoint values, and environment
 snapshots. Changed paths influence a decision but are not copied into receipts.
 
-In v2.15, actor identity is an unauthenticated local assertion even when a
+Local playbook actor identity remains an unauthenticated assertion even when a
 harness supplies it. Do not use receipts for employee monitoring,
-authorization, non-repudiation, or team access decisions. The future
-[team-mode contract](design/team-mode.md) requires authenticated subjects,
-deny-by-default ACLs, tenant isolation, retention, and append-only auditing
-before shared operation can ship.
+authorization, non-repudiation, or team access decisions. The separate
+[team preview](team.md) uses verified credentials and server-side memberships,
+never these labels. The broader [team-mode contract](design/team-mode.md)
+retains independent production-admission, isolation and retention requirements.
 
 ## Data at rest
 
@@ -701,3 +701,22 @@ skill readable; Cairnkeep never copies it into a harness or executes it.
 
 Pack digests and proposal digests protect integrity and stale-state detection;
 they do not authenticate a publisher or make extracted statements true.
+
+## Team preview flow and isolation
+
+The default-off [team preview](team.md) reads no personal memory automatically.
+Only explicitly supplied, inspected text becomes an immutable project proposal;
+only review by a different human credential publishes a shared revision.
+Workload tokens cannot review. The agent's local stdio bridge sends explicit
+organization/project requests and bearer authorization to the separately
+configured JSON API. Search uses substring matching, never an embedding/model
+provider. There is no background ingestion or sync.
+
+Membership and credentials, not cwd or local playbook actor labels, select
+authority. Server checks happen on every operation. Profile/capability
+restrictions only narrow MCP tools. Shared values, source digests and identities
+are stored privately; audit includes operation/outcome/digests without text or
+tokens. Backups include shared proposals and memberships and need separate
+encryption and access control. No unapproved personal content is discoverable.
+A hash confirmation does not establish human consent or content truth.
+Review and production admission remain separate operator responsibilities.

package/docs/security-assurance.md

@@ -222,3 +222,31 @@ fallback; its response cap is 8 MiB. OpenViking retains its 1 MiB cap, explicit
 consents and HTTPS-or-loopback rule. Both reject malformed UTF-8 and suppress
 network/stream diagnostics. Health probes use only `127.0.0.1` with a validated
 port and the existing private token resolver, and never follow redirects.
+
+## Team preview assurance boundary
+
+The [team preview](team.md) adds a separate authenticated organization/project
+boundary; it does not retrofit ACLs onto the existing personal HTTP server.
+Expiring/revocable credentials, independent project roles, workload-review
+denial, self-review denial, policy/base conflicts, immutable proposals and
+transactional publication/audit have maintained synthetic controls.
+The local MCP bridge has no review/admin tools, no scope fallback and a
+restrictive profile/capability intersection. The loopback JSON API rejects
+browser origins and unexpected Host headers, bounds requests/responses and
+rechecks authority after body receipt.
+
+`smoke-team*.mjs` additionally covers concurrent/cross-process state changes,
+audit failure rollback, oversized chunked bodies, restore integrity, revoked
+restored credentials, CLI exit and uninstall retention. Built-in SQLite needs
+Node 22.13+ only when opted in. Linux fixture execution is not native Windows
+evidence, and same-account processes remain trusted. Hash-linked local audit
+cannot detect an OS owner rewriting the entire chain; backups are unencrypted.
+Capacity exhaustion fails closed rather than removing audit history.
+
+The governed internal separate-context review and approved isolated native
+pilot are complete; this is not an external professional assessment or a study
+with two independent human participants. The released preview remains default
+off. Independent production security review, platform/package/container
+verification and a deployment-specific approved real-data pilot remain
+mandatory production gates. Inline review alone is not independent review.
+The service is token-first JSON HTTP plus local stdio MCP, not OAuth remote MCP.

package/docs/storage.md

@@ -602,3 +602,21 @@ store; it does not turn the proposal directory into a second memory authority.
 Context-usage receipts are strict links in the existing work-evidence store.
 They inherit work-evidence inspection, retention, and doctor behavior; there is
 no separate prompt or retrieved-content log.
+
+## Separate team store (opt-in 2.25 preview)
+
+[Team continuity](team.md) keeps organization/project records in a separate
+`team.db` under `CAIRN_TEAM_BASE_DIR` (default `~/.cairnkeep/team`). Built-in
+SQLite transactions serialize state and audit across processes; personal
+AgentFS stores and layouts are unchanged. No migration or automatic copying
+of personal memory occurs. The OS owner is trusted; stored text is unencrypted.
+
+Use `cairn team backup`, not a live directory copy, for a verified consistent
+snapshot. Restore publishes only a new directory, requires its exact digest,
+and revokes all copied credentials. Doctor verifies references, object hashes,
+audit links and temporary remnants without choosing a recovery state.
+Manual logical key deletion retains audit metadata and does not erase free
+pages, WAL or backup copies. Uninstall retains team data and refuses purge
+targets overlapping its configured directory. Independently selected
+`--data` stores must be outside purge targets or also configured through
+`CAIRN_TEAM_BASE_DIR`. Keep encrypted backups separately protected.

package/docs/team-pilot.md

@@ -0,0 +1,132 @@
+# An isolated team-continuity pilot
+
+This guide is for the opt-in Cairnkeep 2.25.0 team preview. It is **not production admission**.
+Obtain explicit pilot approval first. Keep automated rehearsal, human review,
+native-harness observations and release authorization as separate evidence.
+Use the exact matching source checkout for the source controls below, not an
+unverified global command or a production overlay. The released CLI includes
+the optional team commands, but installation does not authorize this pilot.
+
+The pilot runs beside existing personal memory: a new private store, expiring
+credentials, a separate loopback port and additional isolated client profiles.
+It never imports a personal store or replaces an existing MCP registration.
+Use synthetic project decisions, not employer, personal or customer data.
+
+## 1. Prepare a private lab
+
+Build the matching checkout. The following setup uses Bash on Linux/macOS; on
+native Windows use the equivalent explicit CLI commands from [Team continuity](team.md).
+Choose an absolute, **nonexistent** lab directory outside source checkouts,
+personal memory, backup stores and other private stores. Do not reuse an old lab.
+
+```sh
+TEAM_CAIRN=/absolute/path/to/feature-checkout/bin/cairn
+TEAM_PILOT_DIR=/absolute/private/new-team-pilot
+```
+
+Run this setup block in that shell. The operator chooses these two paths; the
+block refuses an existing lab directory. Credential values are never printed.
+
+<!-- team-pilot-setup:start -->
+```sh
+set -e
+: "${TEAM_CAIRN:?Set the absolute feature-checkout command}"
+: "${TEAM_PILOT_DIR:?Set a new absolute private lab directory}"
+case "$TEAM_CAIRN:$TEAM_PILOT_DIR" in /*:/*) ;; *) exit 1 ;; esac
+mkdir -m 0700 "$TEAM_PILOT_DIR"
+mkdir -m 0700 "$TEAM_PILOT_DIR/author-workspace" "$TEAM_PILOT_DIR/reader-workspace"
+TEAM_PILOT_EXPIRY=$(node -p 'new Date(Date.now() + 2 * 3600000).toISOString()')
+team_pilot_admin() {
+  (cd "$TEAM_PILOT_DIR" && env -i PATH="$PATH" CAIRN_TEAM=1 \
+    "$TEAM_CAIRN" team "$@" --data "$TEAM_PILOT_DIR/store")
+}
+team_pilot_admin init --organization trial-org
+team_pilot_admin project create trial-project
+team_pilot_admin project create unrelated-project
+team_pilot_admin member set author --project trial-project --roles reader,contributor
+team_pilot_admin member set reader --project trial-project --roles reader
+team_pilot_admin member set reviewer --project trial-project --roles reader,reviewer,auditor
+team_pilot_admin credential issue author --class workload --expires-at "$TEAM_PILOT_EXPIRY" --output "$TEAM_PILOT_DIR/author.token"
+team_pilot_admin credential issue reader --class workload --expires-at "$TEAM_PILOT_EXPIRY" --output "$TEAM_PILOT_DIR/reader.token"
+team_pilot_admin credential issue reviewer --class human --expires-at "$TEAM_PILOT_EXPIRY" --output "$TEAM_PILOT_DIR/reviewer.token"
+team_pilot_admin doctor
+```
+<!-- team-pilot-setup:end -->
+
+If setup fails, stop and inspect only that generated lab; do not rerun against a
+partially initialized directory. Keep the reviewer token outside both agent
+workspaces. File-only credentials are private, but processes under the same OS
+owner are not mutually isolated: use separate accounts or machines if that is
+part of the pilot's threat model. Do not claim role tests prove OS isolation.
+
+## 2. Start only the disposable service
+
+In a dedicated terminal, choose a separate unused port and run the exact feature
+command from the lab directory. Do not kill another listener to claim its port.
+
+```sh
+cd "$TEAM_PILOT_DIR"
+env -i PATH="$PATH" CAIRN_TEAM=1 CAIRN_TEAM_HTTP=1 \
+  "$TEAM_CAIRN" team serve --data "$TEAM_PILOT_DIR/store" --port 17955
+```
+
+Keep it in the foreground and use Ctrl+C for shutdown. It binds loopback only.
+A second machine needs an authenticated SSH tunnel, not a public API listener.
+Keep the production service, personal stores and existing MCP definitions intact.
+
+## 3. Use two additional client profiles
+
+Configure only a new `cairn-team-memory` stdio server in disposable profiles for
+the chosen harnesses. Do not edit their user-wide settings, trust lists or tokens.
+Use the feature command with arguments `team mcp --project-root WORKSPACE` and
+an explicit private workspace path for each client. Both clients receive:
+
+- `CAIRN_TEAM=1`, `CAIRN_TEAM_ORGANIZATION=trial-org`;
+- `CAIRN_TEAM_URL=http://127.0.0.1:17955` (or the explicit loopback tunnel);
+- `CAIRN_TEAM_TOKEN_FILE` pointing to **only** their own workload credential.
+
+Each tool call must explicitly name project `trial-project`; the working folder
+and client name do not select or grant project access.
+
+The author uses `author.token`; the other client uses `reader.token` and
+`CAIRN_TEAM_MCP_TOOL_PROFILE=read-only`. Never give either model `reviewer.token`,
+an administrative command, production credentials or an inherited cloud-provider
+key for this lab. Use a provider explicitly authorized for the pilot. Starting
+a server or downloading a model is not implicit subscription authorization.
+
+## 4. Exercise the actual review boundary
+
+Have the author propose one exact synthetic project decision, with explicit
+mutation consent. Record the immutable proposal ID, digest, selected bytes and
+provenance privately. The reader must not see it before publication.
+
+In the operator-only terminal, use `proposal-show` with the human reviewer
+credential to inspect the **actual stored proposal**, not an agent's paraphrase.
+Only after the reviewer explicitly approves those bytes, call `review` with
+the exact proposal digest as described in [the reference](team.md#harness-connection).
+Do not put a human token into an agent profile or script automatic human review.
+Checking a hash does not establish human consent or verify a person's identity.
+
+Restart the reader harness in a different empty working folder, retaining the
+explicit authorized team project. Verify it reads identical approved text and
+provenance. Capture actual tool-use evidence, not a model's claim of recall.
+Exercise an unrelated-project denial, a read-only proposal denial, membership
+removal on a connected client, and restore into a fresh store with old tokens
+refused. Do not change production roles or activate the restored lab implicitly.
+
+## 5. Record, stop and decide
+
+Keep a private, payload-free summary of source revision, client versions,
+projects/roles, consent method and outcomes. Label unattended SDK controls as
+automated rehearsal; do not turn their pass result into a human-pilot claim.
+Record missing steps and failures, including model/tool-use failures.
+
+Stop the foreground lab server. Verify its listener and clients have exited.
+Revoke lab credentials if retaining the store; retain or remove only the exact
+generated lab after preserving agreed evidence. Never purge a real memory base.
+Confirm production configuration hashes are unchanged. No team setting is
+enabled globally, so stopping the lab requires no production rollback.
+
+Independent security review, platform checks, pilot approval/results and release
+authorization remain distinct gates. Completing this guide does not itself
+authorize a merge, release, production enrollment or fleet deployment.

package/docs/team.md

@@ -0,0 +1,234 @@
+# Team continuity preview
+
+Status: opt-in experimental preview included in **Cairnkeep 2.25.0**;
+**not general production admission**. Existing local memory and trusted
+shared-token HTTP are unchanged. Installing or upgrading does not enable team
+sharing, enroll users or start a team service.
+
+The governed internal security review and a separately approved isolated
+native-harness pilot are complete. That pilot used selected synthetic context,
+one actual human reviewer and two workload identities; it was not a study with
+two independent human participants or an external professional assessment.
+Independent production review and deployment-specific acceptance remain
+necessary before using this preview with real organization data.
+
+Team memory is a separate store of explicitly selected, reviewed project
+context. It never scans or uploads personal stores, prompts, transcripts or
+repositories. The same project IDs work across harnesses and working folders.
+Sharing changes visibility: inspect and redact the selected text first.
+
+For a trial alongside unchanged personal memory, use the
+[isolated pilot guide](team-pilot.md). It keeps stores, credentials, ports and
+client profiles separate and distinguishes actual human review from rehearsal.
+
+## Trust boundary
+
+The initial service has one organization, server-owned subjects, explicit
+project memberships and expiring/revocable human or workload credentials.
+Caller-supplied actor labels do not grant authority. Each operation rechecks
+credentials and membership inside its transaction.
+
+Roles are independent: reader retrieves approved memory; contributor submits
+and inspects their proposals; reviewer inspects and approves/rejects proposals;
+auditor reads scoped audit metadata. Maintainer does **not** imply review or
+read authority. Membership administration currently trusts the local OS owner,
+not a remote maintainer token. Workload credentials cannot review, even when
+their subject has a reviewer role. Self-review is always refused.
+
+Proposals retain exact selected bytes, source digest, base revision, expiry and
+policy digest. Review confirms the proposal digest; stale policy/base produces a
+conflict, never automatic merging. Publication, head update and audit append are
+atomic. Audit stores identities, digests and outcomes—not memory text or tokens.
+Hash links detect corruption; they do not prevent a trusted storage owner from
+rewriting the database. Digests establish integrity, not publisher authenticity.
+
+## Enable explicitly
+
+Use Node 22.13 or newer for the optional built-in SQLite store. Node 24/26 are
+also supported. The core's Node engine floor remains 22; the optional team
+store needs the later built-in SQLite API. Use current maintained patch releases.
+No new runtime dependency or personal-store migration is needed.
+
+```sh
+export CAIRN_TEAM=1
+cairn team init --organization demo-org --data /absolute/private/team
+cairn team project create alpha --data /absolute/private/team
+cairn team member set alice --project alpha --roles reader,contributor --data /absolute/private/team
+cairn team member set bob --project alpha --roles reader,reviewer --data /absolute/private/team
+cairn team credential issue alice --class workload --expires-at 2026-12-01T00:00:00Z --output /absolute/private/alice.token --data /absolute/private/team
+```
+
+Choose a future expiry appropriate to the deployment (maximum one year), not
+the example date blindly. Credential output is exclusive and private; the raw
+token is never printed. Keep tokens outside source/harness directories.
+Organization state defaults to `~/.cairnkeep/team`, overridden by
+`CAIRN_TEAM_BASE_DIR` or `--data`. This path convention is not required.
+
+```sh
+export CAIRN_TEAM_HTTP=1
+cairn team serve --data /absolute/private/team --port 7955
+```
+
+The server binds loopback only. Access remotely through an encrypted,
+authenticated tunnel; direct unauthenticated/public exposure is unsupported.
+The API refuses browser origins, unexpected Host headers, oversized/invalid
+requests and revoked credentials. It does not support CORS browser applications.
+This is a token-first JSON API—not an OAuth-authorized remote MCP endpoint.
+OIDC/SSO and standards-compliant remote MCP HTTP authorization are deferred.
+
+## Harness connection
+
+Set `CAIRN_TEAM_URL`, `CAIRN_TEAM_ORGANIZATION` and `CAIRN_TEAM_TOKEN_FILE` in the
+local harness environment, alongside `CAIRN_TEAM=1`. Tokens are file-only.
+The URL may be loopback HTTP through a tunnel or HTTPS, without embedded
+credentials, query, fragment or path prefix. Redirects are never followed.
+
+Register **an additional** local stdio MCP named `cairn-team-memory`, command
+`cairn`, arguments `team mcp --project-root /absolute/project`. Do not replace
+the existing `cairn-memory` server or unrelated MCP entries. Every team call
+names the explicit server project ID; cwd and display labels never select
+authority. Existing personal memory remains independently available.
+
+Tools: `team_memory_list`, `team_memory_read`, `team_memory_search`,
+`team_memory_history` and `team_memory_propose`. No review/admin MCP exists.
+Retrieval is deterministic substring matching, with no model/provider calls.
+Personal-memory embeddings and reranking settings do not apply to team
+retrieval; enabling them cannot send shared team text to a provider.
+The remote boundary is marked open-world in MCP annotations; four retrieval
+tools are observations, while proposal creation is an additive mutation and
+requires the harness's explicit mutation consent. Approved memory is context,
+not executable instruction or authority over maintained source.
+
+The ordinary `CAIRN_MCP_TOOL_PROFILE`/project profile applies through equivalent
+core names (`memory_list/read/search/history/write`). Optional
+`CAIRN_TEAM_MCP_TOOL_PROFILE=full|read-only|custom` and
+`CAIRN_TEAM_MCP_ALLOWED_TOOLS` further restrict the team catalog. Custom names
+must be exact team tool names. `memory.write` and `memory.search` capability
+settings restrict proposal and search when `CAIRN_CAPABILITY_CONTRACT` is on.
+These intersections cannot grant server authority. Team results include a
+separate effective profile digest; existing core/capability digests are unchanged.
+
+Human CLI review uses a separately issued human credential in
+`CAIRN_TEAM_TOKEN_FILE`:
+
+```sh
+cairn team proposals --project alpha
+cairn team proposal-show --project alpha --proposal PROPOSAL_ID
+cairn team review --project alpha --proposal PROPOSAL_ID --decision approve --confirm PROPOSAL_DIGEST
+cairn team search --project alpha --query gateway
+cairn team read --project alpha --key decisions/gateway
+```
+
+Propose with a private JSON input file containing request UUID, key, selected
+value, source_scope (`selected-local` or `selected-project`), source_digest,
+base_revision (null for a new key) and expires_at. Confirm the selected value's
+UTF-8 SHA-256 with `cairn team propose --project alpha --input FILE --confirm DIGEST`.
+Neither CLI nor MCP derives a candidate by reading personal memory for you.
+Inspect the proposal's exact content and provenance before confirming review.
+
+Failure is explicit; the bridge never falls back to personal/global storage or
+a different identity. Local memory commands still work independently offline.
+
+## Recovery, retention and credential rotation
+
+Local administration requires access as the trusted storage OS owner. It is
+not exposed over HTTP or MCP. Keep the data directory private (`0700` on POSIX,
+owner-only ACL on Windows); database, WAL, credential and snapshot files are
+private too. Do not put a live store inside a source checkout or another store.
+
+```sh
+cairn team doctor --data /absolute/private/team
+cairn team backup --data /absolute/private/team --output /absolute/private/team-snapshot.json
+cairn team restore --input /absolute/private/team-snapshot.json --confirm SNAPSHOT_DIGEST --data /absolute/private/restored-team
+cairn team doctor --data /absolute/private/restored-team
+```
+
+Backup is a consistent transaction including records and value-free audit.
+The output must be a new file; it contains shared text, proposals, subject IDs,
+memberships and token hashes. Encrypt and restrict retained copies separately:
+the store and JSON snapshot are not encrypted by Cairnkeep. Restore checks
+schema, object digests, references and audit links before publishing a new
+directory. It never overwrites an existing store. Concurrent cooperating
+restores are exclusive; a failure never activates partial restored state.
+Every restored credential is revoked. Issue fresh credentials and explicitly
+select the restored store only after doctor passes. No automatic service switch
+or identity approval occurs. Snapshot digests prove integrity, not authenticity.
+
+Doctor reports temporary-remnant counts without deleting or selecting them.
+If an interrupted restore leaves a lock or temporary directory, stop competing
+administration, verify process ownership and preserve a copy before manually
+removing the exact abandoned path. Doctor never chooses which version to use.
+
+Rotate a credential by issuing a fresh private token file, distributing it
+through a separate secure channel, and revoking the old credential ID with
+`cairn team credential revoke ID --data DIR`. Replacing the configured token
+file makes the bridge use it on the next request; revocation and membership
+changes are also enforced on already-connected clients. There are no cached
+authorization grants. Protect human reviewer tokens from agent environments.
+
+For a compromised workload token, revoke it first and remove project roles if
+needed. Remove all of a subject's access to one project explicitly:
+
+```sh
+cairn team member remove alice --project alpha --data /absolute/private/team
+```
+
+This clears that project's roles immediately, including for connected clients.
+Other project memberships and credentials remain unchanged; revoke credentials
+separately for complete offboarding. Existing revisions and audit history are
+retained. To re-enroll, use `member set` with an explicit nonempty `--roles` list.
+Missing or empty role lists are rejected rather than silently removing access.
+
+Inspect `cairn team audit --project ID` using an auditor credential;
+accepted, denied and conflicted authenticated operations record bounded
+metadata. Invalid credentials do not create unauthenticated identity records.
+Audit integrity is not external tamper resistance against the OS owner.
+
+Current retention is manual: approved revisions, pending/rejected proposals
+and audit events do not expire out of storage automatically. Proposal expiry
+prevents review, not retention. An operator can delete a selected shared key,
+its revisions and associated proposals/reviews using its current head digest:
+
+```sh
+cairn team memory-delete --project alpha --key decisions/gateway --confirm REVISION_DIGEST --data /absolute/private/team
+```
+
+This is logical deletion, not certified erasure: audit metadata, SQLite free
+pages/WAL and older snapshots may retain traces or bytes. Apply a separately
+reviewed storage/backup disposal policy if erasure is required. Ordinary
+uninstall retains team data. Purge operations overlapping the configured team
+store are refused before any uninstall changes; a store selected only through
+`--data` must remain outside purge targets or also be set as
+`CAIRN_TEAM_BASE_DIR` for that retention check.
+
+## Bounded preview and admission
+
+Selected values are at most 64 KiB UTF-8; requests 512 KiB; responses 2 MiB;
+snapshots 64 MiB. Records are capped at 32,768 and 16 MiB of stored JSON;
+audit at 100,000 events and 16 MiB, with a 1,000-event/256 KiB OS-operator reserve.
+Limits fail closed rather than discarding records. Back up and review retention
+before approaching them; the preview has no audit archival/compaction command.
+Retrieval is bounded (100 list/history items, ten search results); the API
+currently has no pagination. HTTP separately limits malformed authentication
+per connection address and authenticated requests per subject to 120 per minute;
+invalid token-shaped credentials receive ten attempts per token digest. Each
+budget holds at most 512 identities, and invalid authentication cannot consume
+an authenticated subject's quota. Headers are capped at 32 KiB, inactive
+requests at ten seconds, and bridge fetches at fifteen seconds.
+
+Digest confirmation proves selected bytes match; it cannot prove a human
+clicked approval. MCP hosts must obtain mutation consent. Only separate human
+CLI credentials can review, and the OS owner remains trusted to assign them.
+No automatic setup, existing MCP replacement or fleet deployment is performed.
+
+Release checks cover Node 22/24/26, native Windows, real Bash 3.2,
+installed-package and container behavior. The internal governed review and
+approved isolated native pilot covered exact human proposal approval,
+cross-harness recall, offboarding, restore and project isolation. Automated
+fixtures are regression evidence, not proof of human consent. These results do
+not admit arbitrary production deployments: establish an independent security
+review appropriate to the deployment, named operational ownership, a separately
+approved limited real-data pilot with rollback, and explicit operator acceptance
+before enabling a real organization. Keep reviewer credentials out of agents.
+OIDC/SSO, multi-organization tenancy, team packs, remote maintainer administration,
+provider retrieval and externally anchored audit are deferred.

package/examples/eval/bundled-fake.json

@@ -1 +1 @@
-{"identifier":"cairn-offline-fake-v1","package_version":"2.24.0","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}
+{"identifier":"cairn-offline-fake-v1","package_version":"2.25.0","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}