@cairnkeep/cli 2.24.0 → 2.26.0

package/docs/team-pilot.md

@@ -0,0 +1,134 @@
+# 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.
+For a shorter role-by-role route and reader connection card, see
+[Team onboarding](team-onboarding.md). It does not grant deployment consent.
+
+## 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,245 @@
+# 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.
+Start with the [role-based handoff](team-onboarding.md) for operator, coding
+client and human-reviewer tasks, a tested reader check and readiness checklist.
+
+## 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
+
+Cairnkeep 2.26.0 (both client and team API) adds
+the opt-in [guided connection and recovery workflow](team-onboarding.md#guided-connection-next-release--matching-source-checkout):
+`cairn team connect`, `cairn team doctor --client` and `cairn team disconnect`.
+It adds only a dedicated project-local entry, defaults to read-only, references
+a private token file and pins the server project. No global MCP replacement or
+personal upload occurs. The manual environment recipe below remains supported
+on 2.25.0. The diagnostics API returns only authenticated project/credential
+metadata and records a value-free audit event, not memory text.
+
+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.26.0","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}

package/mcp-memory-server/dist/capability-config.js

@@ -222,7 +222,18 @@ async function acquireLock(lockPath) {
         catch (error) {
             if (error.code !== "EEXIST")
                 throw error;
-            const info = await lstat(lockPath);
+            let info;
+            try {
+                info = await lstat(lockPath);
+            }
+            catch (inspectionError) {
+                // The current writer may release its lock after our mkdir
+                // reports contention but before inspection. Only disappearance
+                // admits another bounded acquisition attempt, never ownership.
+                if (inspectionError.code === 'ENOENT')
+                    continue;
+                throw inspectionError;
+            }
             if (info.isSymbolicLink() || !info.isDirectory()) {
                 throw new Error("Capability configuration lock is unsafe.");
             }

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

@@ -0,0 +1,228 @@
+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';
+import { readTeamConnection, connectionToken } from './team-client.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 connect [--project-root PATH] [--url URL --organization ID --project ID --token-file FILE --harness LIST] [--access read-only|full] [--apply --yes]
+  cairn team disconnect [--project-root PATH] [--apply --yes]
+  cairn team doctor --client [--project-root PATH]
+  cairn team mcp [--project-root PATH | --connection FILE] # 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', 'connection']);
+    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', 'connection'], 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');
+            if (flags.connection && flags['project-root'])
+                throw new TeamError('invalid');
+            const connection = flags.connection ? readTeamConnection(resolve(flags.connection)) : undefined;
+            const token = connection ? () => connectionToken(connection) : () => teamClientToken();
+            token(); // validate private credential before startup
+            const server = await createTeamMcpServer(connection
+                ? { url: connection.url, organization: connection.organization, project: connection.project, readOnly: connection.access === 'read-only', token, projectRoot: connection.project_root }
+                : { url: process.env.CAIRN_TEAM_URL ?? '', organization: process.env.CAIRN_TEAM_ORGANIZATION ?? '', token, 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;
+});