@cairnkeep/cli 2.23.1 → 2.25.0

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.23.1","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}
+{"identifier":"cairn-offline-fake-v1","package_version":"2.25.0","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}

package/mcp-memory-server/dist/index.js

@@ -16,6 +16,7 @@ import { artifactIdSchema, artifactKindSchema, artifactMediaTypeSchema, artifact
 import { isCapabilityContractEnabled, resolveCapabilityStatus, } from "./capability-config.js";
 import { EmbeddingCache, cosineSimilarity, embedTexts, getEmbeddingConfig, hashText, } from "./embeddings.js";
 import { queryDomainKnowledge, resolveDomainRetrievalProvider } from "./domain-retrieval-provider.js";
+import { getMemoryRerankerConfig, memoryRerankCandidateCount, rerankMemoryResults } from "./memory-reranker.js";
 import { formatHostAuthority, normalizeHostAuthority, normalizeHttpHost, parseHttpPort, resolveHttpToken } from "./http-security.js";
 import { computeRepoState, exploreCacheKey, normalizeExploreQuery, readExploreCache, writeExploreCache, } from "./explore-cache.js";
 import { canonicalTagsSchema, isTypedMemoryNodesEnabled, memoryImportEnvelopeSchema, noteNodeSchema, nodeTypeSchema, } from "./node-schema.js";
@@ -377,7 +378,7 @@ function entryText(entry) {
 function embeddingCachePath(scope, projectId) {
     return join(getBaseDir(), ".embeddings", `${hashText(resolveScopePath(scope, { projectId }))}.json`);
 }
-async function semanticSearch(scope, query, topK, minScore, config = getMemoryConfig(), projectId, options = {}) {
+async function semanticSearchCandidates(scope, query, topK, minScore, config = getMemoryConfig(), projectId, options = {}) {
     const scopes = getSearchScopes(scope, config);
     const embeddingConfig = getEmbeddingConfig();
     const perScopeEntries = await Promise.all(scopes.map(async (candidate) => ({
@@ -480,6 +481,32 @@ async function semanticSearch(scope, query, topK, minScore, config = getMemoryCo
         return substringFallback();
     }
 }
+async function semanticSearch(...args) {
+    const reranker = getMemoryRerankerConfig();
+    if (!reranker)
+        return semanticSearchCandidates(...args);
+    const [, query, topK] = args;
+    const options = args[6] ?? {};
+    const candidateArgs = [...args];
+    candidateArgs[2] = memoryRerankCandidateCount(topK, reranker);
+    // The existing path still owns scope, current-value, typed and relevance
+    // admission. The external ranker never sees records rejected by that path.
+    const candidate = await semanticSearchCandidates(...candidateArgs);
+    const exactKeys = new Set([query, ...(options.aliases ?? [])].map(value => value.normalize('NFKC').toLowerCase().trim()));
+    const pinned = (entry) => options.strategy === 'hybrid'
+        ? exactKeys.has(entry.key.normalize('NFKC').toLowerCase())
+        : Boolean(options.typed && isExactTextHit(entry, query));
+    const { results } = await rerankMemoryResults(candidate.results, query, topK, reranker, pinned);
+    const retrieval = candidate.retrieval;
+    if (retrieval?.possible_conflicts) {
+        const keys = new Set(results.map(entry => entry.key));
+        // Explain only selected keys, including when the larger candidate pool
+        // falls back. Do not leak explanations for unreturned candidates.
+        return { ...candidate, results, retrieval: { ...retrieval,
+                possible_conflicts: retrieval.possible_conflicts.filter(row => keys.has(row.key)) } };
+    }
+    return { ...candidate, results };
+}
 // Confines a candidate wiki source file to inside `<repoRoot>/.planning/wiki/sources`
 // via relative()-based containment (Phase 2 SEC-0001 idiom, reused from
 // opencode/plugins/memory-recall.ts) — `resolve() === join()` misses `../`
@@ -708,8 +735,9 @@ function gitToplevel(cwd) {
 // serve many concurrent clients within one trusted server-side storage domain.
 function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProfile = resolveMcpToolProfile({ projectRoot: process.cwd() })) {
     const server = new McpServer({ name: "cairn-memory", version: "0.1.0" });
+    const memoryReranking = getMemoryRerankerConfig() !== null;
     const registerTool = (name, config, callback) => {
-        const metadata = metadataForTool(name);
+        const metadata = metadataForTool(name, { memoryReranking });
         if (!profileAllowsTool(toolProfile, name))
             return;
         server.registerTool(name, {

package/mcp-memory-server/dist/mcp-tool-catalog.js

@@ -45,8 +45,11 @@ export const MCP_TOOL_NAMES = Object.freeze(Object.keys(MCP_TOOL_CATALOG));
 export function isCairnToolName(value) {
     return Object.hasOwn(MCP_TOOL_CATALOG, value);
 }
-export function metadataForTool(name) {
+export function metadataForTool(name, options = {}) {
     if (!isCairnToolName(name))
         throw new Error(`MCP tool ${name} has no annotation contract.`);
+    if (name === 'memory_search' && options.memoryReranking) {
+        return { ...MCP_TOOL_CATALOG[name], annotations: { ...MCP_TOOL_CATALOG[name].annotations, openWorldHint: true } };
+    }
     return MCP_TOOL_CATALOG[name];
 }

package/mcp-memory-server/dist/memory-reranker.js

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+const MAX_CANDIDATES = 50;
+const MAX_TEXT_BYTES = 4096;
+const MAX_REQUEST_BYTES = 256 * 1024;
+const MAX_RESPONSE_BYTES = 64 * 1024;
+const responseSchema = z.object({ results: z.array(z.object({
+        index: z.number().int().min(0).max(MAX_CANDIDATES - 1),
+        relevance_score: z.number().finite(),
+    })).max(MAX_CANDIDATES) });
+/** Configuration alone never grants permission: explicit opt-in is required. */
+export function getMemoryRerankerConfig(env = process.env) {
+    if (env.CAIRN_MEMORY_RERANK !== '1')
+        return null;
+    try {
+        const url = new URL(env.CAIRN_MEMORY_RERANK_URL ?? '');
+        const model = env.CAIRN_MEMORY_RERANK_MODEL?.trim();
+        const rawTimeout = env.CAIRN_MEMORY_RERANK_TIMEOUT_MS ?? '2000';
+        const timeoutMs = Number(rawTimeout);
+        if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash
+            || !model || Buffer.byteLength(model) > 256 || !/^\d+$/.test(rawTimeout)
+            || !Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 10000)
+            return null;
+        const apiKey = env.CAIRN_MEMORY_RERANK_API_KEY?.trim();
+        if (apiKey && (apiKey.length > 8192 || /[\r\n]/.test(apiKey)))
+            return null;
+        return { apiUrl: url.href.replace(/\/+$/, ''), model, ...(apiKey ? { apiKey } : {}), timeoutMs };
+    }
+    catch {
+        return null;
+    }
+}
+export function memoryRerankCandidateCount(topK, config) {
+    if (!Number.isInteger(topK) || topK < 1 || topK > MAX_CANDIDATES)
+        throw new Error('Reranking requires a bounded result count.');
+    return config ? Math.min(MAX_CANDIDATES, Math.max(32, topK * 4)) : topK;
+}
+function textPrefix(value, maxUnits) {
+    let end = Math.min(value.length, maxUnits);
+    const last = value.charCodeAt(end - 1);
+    if (end < value.length && last >= 0xD800 && last <= 0xDBFF)
+        end--;
+    return value.slice(0, end);
+}
+function rankingText(entry) {
+    // Bound allocation before UTF-8 encoding, then discard an incomplete final
+    // code point rather than introducing replacement characters at the cutoff.
+    const text = `${textPrefix(entry.key, 1024)}\n${textPrefix(entry.value, MAX_TEXT_BYTES)}`;
+    const bytes = Buffer.from(text);
+    return new TextDecoder().decode(bytes.subarray(0, MAX_TEXT_BYTES), { stream: true });
+}
+async function readRankingResponse(response) {
+    if (!response.ok || !response.body || Number(response.headers.get('content-length')) > MAX_RESPONSE_BYTES) {
+        await response.body?.cancel();
+        throw new Error('Reranker response unavailable.');
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_RESPONSE_BYTES)
+                throw new Error('Reranker response exceeds limit.');
+            chunks.push(value);
+        }
+        const bytes = Buffer.concat(chunks, size);
+        return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+/** Reorder admitted records only. No input object, score, scope or value is changed. */
+export async function rerankMemoryResults(entries, query, topK, config, pinned = () => false) {
+    const baseline = entries.slice(0, topK);
+    if (!config)
+        return { results: baseline, status: 'disabled' };
+    if (entries.length < 2 || entries.length > MAX_CANDIDATES || !query.trim() || Buffer.byteLength(query) > MAX_TEXT_BYTES) {
+        return { results: baseline, status: 'skipped' };
+    }
+    try {
+        const body = JSON.stringify({ model: config.model, query, documents: entries.map(rankingText), top_n: entries.length });
+        if (Buffer.byteLength(body) > MAX_REQUEST_BYTES)
+            return { results: baseline, status: 'skipped' };
+        const response = await fetch(`${config.apiUrl}/rerank`, {
+            method: 'POST', redirect: 'manual', signal: AbortSignal.timeout(config.timeoutMs),
+            headers: { 'Content-Type': 'application/json', ...(config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}) },
+            body,
+        });
+        const parsed = responseSchema.parse(await readRankingResponse(response));
+        if (parsed.results.length !== entries.length
+            || new Set(parsed.results.map(row => row.index)).size !== entries.length
+            || parsed.results.some(row => row.index >= entries.length))
+            throw new Error('Invalid ranking indices.');
+        const scores = new Map(parsed.results.map(row => [row.index, row.relevance_score]));
+        const ordered = entries.map((entry, index) => ({ entry, index, pinned: pinned(entry) }));
+        ordered.sort((a, b) => Number(b.pinned) - Number(a.pinned)
+            || scores.get(b.index) - scores.get(a.index) || a.index - b.index);
+        return { results: ordered.slice(0, topK).map(row => row.entry), status: 'reranked' };
+    }
+    catch {
+        // Never return endpoint errors, response bodies or credentials to clients.
+        return { results: baseline, status: 'failed' };
+    }
+}

package/mcp-memory-server/dist/team-cli.js

@@ -0,0 +1,218 @@
+import { closeSync, existsSync, openSync, writeFileSync, fsyncSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { readStableJson } from './stable-file.js';
+import { hardenPrivatePath } from './platform-security.js';
+import { openTeamStore, restoreTeamSnapshot, verifyTeamSnapshot, prepareTeamPrivateDirectory, TEAM_SNAPSHOT_MAX_BYTES, TeamError } from './team-store.js';
+import { createTeamHttpServer, teamRequest } from './team-http.js';
+import { createTeamMcpServer, teamClientToken } from './team-mcp.js';
+const HELP = `cairn team — experimental token-first team continuity (default off)
+
+CAIRN_TEAM=1 is required. Personal memory is never uploaded.
+
+  cairn team init --organization ID [--data DIR]
+  cairn team project create ID [--data DIR]
+  cairn team member set SUBJECT --project ID --roles LIST [--data DIR]
+  cairn team member remove SUBJECT --project ID [--data DIR]
+  cairn team credential issue SUBJECT --class human|workload --expires-at ISO --output FILE [--data DIR]
+  cairn team credential revoke ID [--data DIR]
+  cairn team serve [--data DIR] [--port PORT]  # requires CAIRN_TEAM_HTTP=1; loopback only
+  cairn team mcp [--project-root PATH]        # local stdio MCP; no review/admin tools
+  cairn team list --project ID
+  cairn team proposals --project ID
+  cairn team audit --project ID             # scoped, value-free metadata
+  cairn team read --project ID --key KEY [--revision DIGEST]
+  cairn team history --project ID --key KEY
+  cairn team search --project ID --query TEXT
+  cairn team proposal-show --project ID --proposal ID
+  cairn team propose --project ID --input FILE --confirm VALUE_DIGEST
+  cairn team review --project ID --proposal ID --decision approve|reject --confirm PROPOSAL_DIGEST
+  cairn team doctor [--data DIR]
+  cairn team backup --output FILE [--data DIR]
+  cairn team restore --input FILE --confirm SNAPSHOT_DIGEST --data NEW_DIR
+  cairn team memory-delete --project ID --key KEY --confirm REVISION_DIGEST [--data DIR]
+
+Clients require CAIRN_TEAM_URL, CAIRN_TEAM_ORGANIZATION and CAIRN_TEAM_TOKEN_FILE.
+Never put tokens in command arguments, source trees or harness config.
+Team API is not OAuth MCP HTTP. Independent production security review and a
+deployment-specific approved real-data pilot remain admission gates. See docs/team.md.
+`;
+function parse(args) {
+    const words = [];
+    const flags = {};
+    const known = new Set(['data', 'organization', 'project', 'roles', 'class', 'expires-at', 'output', 'port', 'project-root', 'key', 'revision', 'query', 'proposal', 'input', 'confirm', 'decision']);
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith('--')) {
+            const name = arg.slice(2);
+            if (!known.has(name) || flags[name] !== undefined || !args[i + 1] || args[i + 1].startsWith('--'))
+                throw new TeamError('invalid');
+            flags[name] = args[++i];
+        }
+        else
+            words.push(arg);
+    }
+    return { words, flags };
+}
+export function writePrivateExclusive(path, bytes) {
+    path = resolve(path);
+    const directory = dirname(path);
+    prepareTeamPrivateDirectory(directory, true);
+    const fd = openSync(path, 'wx', 0o600);
+    try {
+        hardenPrivatePath(path);
+        writeFileSync(fd, bytes, 'utf8');
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+async function main(args) {
+    if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+        console.log(HELP);
+        return;
+    }
+    if (process.env.CAIRN_TEAM !== '1')
+        throw new TeamError('disabled');
+    const { words, flags } = parse(args);
+    const [command, subcommand, subject] = words;
+    const allowed = {
+        init: ['data', 'organization'], project: ['data'], member: subcommand === 'remove' ? ['data', 'project'] : ['data', 'project', 'roles'],
+        credential: subcommand === 'issue' ? ['data', 'class', 'expires-at', 'output'] : ['data'],
+        serve: ['data', 'port'], mcp: ['project-root'], doctor: ['data'], backup: ['data', 'output'],
+        restore: ['data', 'input', 'confirm'], 'memory-delete': ['data', 'project', 'key', 'confirm'],
+        list: ['project'], proposals: ['project'], audit: ['project'], read: ['project', 'key', 'revision'],
+        history: ['project', 'key'], search: ['project', 'query'], 'proposal-show': ['project', 'proposal'],
+        propose: ['project', 'input', 'confirm'], review: ['project', 'proposal', 'decision', 'confirm'],
+    };
+    if (!allowed[command] || Object.keys(flags).some(flag => !allowed[command].includes(flag)))
+        throw new TeamError('invalid');
+    const memberRoles = (flags.roles ?? '').split(',').filter(Boolean);
+    if (command === 'member' && (!['set', 'remove'].includes(subcommand) || !subject || words.length !== 3 || !flags.project || (subcommand === 'set' && memberRoles.length === 0)))
+        throw new TeamError('invalid');
+    const root = resolve(flags.data ?? process.env.CAIRN_TEAM_BASE_DIR ?? join(homedir(), '.cairnkeep', 'team'));
+    const print = (result) => console.log(JSON.stringify(result, null, 2));
+    let store;
+    try {
+        if (command === 'mcp') {
+            if (words.length !== 1)
+                throw new TeamError('invalid');
+            teamClientToken(); // validate private credential before startup
+            const server = await createTeamMcpServer({ url: process.env.CAIRN_TEAM_URL ?? '', organization: process.env.CAIRN_TEAM_ORGANIZATION ?? '', token: () => teamClientToken(), projectRoot: flags['project-root'] });
+            await server.connect(new StdioServerTransport());
+            return;
+        }
+        if (command === 'restore') {
+            if (words.length !== 1 || !flags.input || !flags.confirm || !flags.data)
+                throw new TeamError('invalid');
+            const snapshot = verifyTeamSnapshot(readStableJson(resolve(flags.input), { label: 'Team snapshot', maxBytes: TEAM_SNAPSHOT_MAX_BYTES, private: true }));
+            store = await restoreTeamSnapshot(root, snapshot, flags.confirm);
+            print({ restored: true, organization: store.organization, credentials_revoked: true });
+            return;
+        }
+        if (['init', 'project', 'member', 'credential', 'serve', 'doctor', 'backup', 'memory-delete'].includes(command)) {
+            if (command === 'init' && (words.length !== 1 || !flags.organization))
+                throw new TeamError('invalid');
+            store = await openTeamStore(root, command === 'init' ? { create: true, organization: flags.organization } : {});
+            if (command === 'doctor' && words.length === 1) {
+                print(await store.doctor());
+                return;
+            }
+            if (command === 'backup' && words.length === 1) {
+                if (!flags.output)
+                    throw new TeamError('invalid');
+                const snapshot = await store.snapshot();
+                writePrivateExclusive(flags.output, `${JSON.stringify(snapshot)}\n`);
+                print({ snapshot_digest: snapshot.digest, written: true });
+                return;
+            }
+            if (command === 'memory-delete' && words.length === 1) {
+                await store.admin({ operation: 'memory-delete', project: flags.project, key: flags.key, confirm: flags.confirm });
+                print({ deleted: true, backup_copies_retained: true });
+                return;
+            }
+            if (command === 'init') {
+                print({ initialized: true, organization: store.organization, experimental: true });
+                return;
+            }
+            if (command === 'project' && subcommand === 'create' && subject && words.length === 3) {
+                await store.admin({ operation: 'project-create', project: subject });
+                print({ created: true });
+                return;
+            }
+            if (command === 'member') {
+                await store.admin({ operation: 'member-set', subject, project: flags.project, roles: subcommand === 'remove' ? [] : memberRoles });
+                print(subcommand === 'remove' ? { removed: true } : { updated: true });
+                return;
+            }
+            if (command === 'credential' && subcommand === 'issue' && subject && words.length === 3) {
+                if (!flags.output || existsSync(resolve(flags.output)))
+                    throw new TeamError('invalid');
+                const credential = await store.issue({ subject, credential_class: flags.class, expires_at: flags['expires-at'] });
+                try {
+                    writePrivateExclusive(flags.output, `${credential.token}\n`);
+                }
+                catch (error) {
+                    await store.admin({ operation: 'credential-revoke', credential: credential.id });
+                    throw error;
+                }
+                print({ credential_id: credential.id, token_file_created: true });
+                return;
+            }
+            if (command === 'credential' && subcommand === 'revoke' && subject && words.length === 3) {
+                await store.admin({ operation: 'credential-revoke', credential: subject });
+                print({ revoked: true });
+                return;
+            }
+            if (command === 'serve' && words.length === 1) {
+                const raw = flags.port ?? '7955';
+                if (!/^[1-9][0-9]{0,4}$/.test(raw) || Number(raw) > 65535)
+                    throw new TeamError('invalid');
+                const server = createTeamHttpServer(store);
+                await new Promise((resolve, reject) => { server.once('error', reject); server.listen(Number(raw), '127.0.0.1', resolve); });
+                process.stderr.write(`Team preview API listening on loopback port ${raw}.\n`);
+                await new Promise(resolve => {
+                    const stop = () => { server.close(() => resolve()); server.closeAllConnections(); };
+                    process.once('SIGINT', stop);
+                    process.once('SIGTERM', stop);
+                });
+                return;
+            }
+            throw new TeamError('invalid');
+        }
+        if (words.length !== 1 || !flags.project)
+            throw new TeamError('invalid');
+        const common = { organization: process.env.CAIRN_TEAM_ORGANIZATION, project: flags.project, operation: command };
+        let input;
+        if (['list', 'proposals', 'audit'].includes(command))
+            input = common;
+        else if (['read', 'history'].includes(command))
+            input = { ...common, key: flags.key, ...(flags.revision ? { revision: flags.revision } : {}) };
+        else if (command === 'search')
+            input = { ...common, query: flags.query };
+        else if (command === 'proposal-show')
+            input = { ...common, proposal_id: flags.proposal };
+        else if (command === 'review')
+            input = { ...common, proposal_id: flags.proposal, decision: flags.decision, confirm: flags.confirm };
+        else if (command === 'propose') {
+            if (!flags.input || !flags.confirm)
+                throw new TeamError('invalid');
+            const selected = readStableJson(resolve(flags.input), { label: 'Team selected proposal', maxBytes: 512 * 1024, private: true });
+            if (!selected || typeof selected !== 'object' || Array.isArray(selected))
+                throw new TeamError('invalid');
+            input = { ...selected, ...common, confirm: flags.confirm };
+        }
+        else
+            throw new TeamError('invalid');
+        print(await teamRequest(process.env.CAIRN_TEAM_URL ?? '', teamClientToken(), input));
+    }
+    finally {
+        await store?.close();
+    }
+}
+void main(process.argv.slice(2)).catch(error => {
+    process.stderr.write(`${error instanceof TeamError ? error.message : 'Team operation failed; no credential or input content is logged.'}\n`);
+    process.exitCode = 1;
+});