snipara-companion 1.4.0 → 1.4.2

package/README.md

@@ -1,70 +1,31 @@
 # snipara-companion
 
-**Workflow continuity for AI coding agents. Start work, commit phases, resume anywhere.**
+**Local helper CLI for Snipara agent workflows.**
 
-`snipara-companion` is the local workflow layer for agentic coding work. It gives
-AI coding agents Git-style continuity commands: status, briefs, timelines, phase
-commits, handoffs, resume, diagnostics, hooks, folder onboarding, and optional
-Hosted Snipara context calls.
+`snipara-companion` adds Git-style continuity commands for agent work: status,
+briefs, timelines, phase commits, handoffs, resume, diagnostics, hooks, folder
+onboarding, and command-line access around Snipara Hosted MCP. It complements
+the hosted context and memory surface; it is not the primary runtime for agents.
 
-Use it as the local runtime for the open Snipara stack:
+In this repository, the source currently lives in `packages/cli`, and the installed executable is `snipara-companion`.
 
-- [`snipara-companion`](https://github.com/Snipara/snipara-companion) keeps agent work resumable.
-- [`snipara-memory`](https://github.com/Snipara/snipara-memory) provides durable local project memory primitives.
-- [`snipara-evals`](https://github.com/Snipara/snipara-evals) measures project-intelligence quality for AI coding agents.
-
-Hosted Snipara adds managed context, reviewed memory, team sync, code graph
-impact, source authority, dashboards, and production operations.
+This package complements `snipara-mcp`. It does not replace it.
 
 ```mermaid
 flowchart LR
     Project["Local project"] --> Companion["snipara-companion"]
-    Companion --> Local["status, timeline, handoff, resume"]
-    Companion --> Memory["optional local/project memory"]
-    Companion --> Hosted["optional Hosted Snipara MCP / API"]
-    Hosted --> Intelligence["project intelligence, code graph, reviewed memory"]
+    Companion --> Diagnostics["status, brief, timeline, phase commits, handoff"]
+    Companion --> Hosted["Snipara Hosted MCP / API"]
+    Hosted --> Agents["Codex, Claude Code, Cursor, ChatGPT"]
 ```
 
-## Open Source Boundary
-
-`snipara-companion` is local-first. It should be useful on a repository even
-when the user has no Snipara account.
-
-| Mode | What works |
-| --- | --- |
-| Local only | `status`, `git summary`, `timeline`, workflow state, `phase-commit`, `final-commit`, local Team Sync handoffs, `code sync`, local code overlay |
-| Local + `snipara-memory` | local `recall`, `query`, `session-bootstrap`, and local memory in `brief` |
-| Snipara Cloud connected | all local features plus hosted memory, Project Intelligence context, What Changed, MCP context, code graph impact, symbol cards, dashboards, and operations |
-
-Cloud wins when connected: if the workspace has a valid Snipara API key and
-project binding, hosted commands use Cloud surfaces. Local fallbacks only run
-when Cloud is not configured.
-
-Open source in this repo:
-
-- local workflow files under `.snipara/`
-- status, git summary, timeline, handoff, resume, phase-commit, and final-commit commands
-- local hook/install helpers for supported AI coding clients
-- diagnostic and verification-plan facades
-- optional `snipara-memory` local fallback for memory recall/session context
-- optional calls to Hosted Snipara when project auth is configured
-
-Hosted Snipara:
-
-- managed MCP context and chunk retrieval
-- reviewed project memory and authority scoring
-- team sync and dashboard workflows
-- code graph impact chains, symbol cards, and verification plans
-- production reliability, tenancy, analytics, and operations
-
 ## When To Use It
 
 | If you need...                                            | Install...               |
 | --------------------------------------------------------- | ------------------------ |
-| Hosted MCP setup and project-scoped context               | `create-snipara`         |
+| MCP tools, OAuth login, project-scoped context and memory | `snipara-mcp`            |
+| One-command Hosted MCP + companion setup                  | `create-snipara`         |
 | Git-style local continuity, workflow modes, and hooks     | `snipara-companion`      |
-| Local durable project memory primitives                   | `snipara-memory`         |
-| Project-intelligence evals for agent traces               | `snipara-evals`          |
 | Production gates, drift checks, and htask orchestration   | `snipara-orchestrator`   |
 | OpenClaw-specific automation hooks                        | `snipara-openclaw-hooks` |
 
@@ -98,19 +59,27 @@ yarn global add snipara-companion
 snipara-companion
 ```
 
-## Development
+## New In 1.4.2
 
-```bash
-pnpm install
-pnpm build
-pnpm type-check
-pnpm test
-pnpm pack:smoke
-```
+- Adds `snipara-companion collaboration start|watch|claim|guard|release|status`
+  for safe parallel coding presence, auto-claims, advisory/exclusive resource
+  claims, hosted guard checks, and conflict alarms across humans and agents.
+- Adds `snipara-companion collaboration hooks install` plus guard profiles for
+  blocking pre-commit, pre-push, pre-deploy, schema/migration, and package
+  release checks.
+- Adds `snipara-companion collaboration ide-status` for editor extensions and
+  local companion UIs that need compact live collaboration state.
+- Hardens local code impact so stale or incomplete local overlay caches report
+  missing target files instead of silently returning an empty impact set.
+
+## New In 1.4.1
 
-This standalone repository is mirrored from the Snipara monorepo package source
-while the public repo is being bootstrapped. The npm package is
-`snipara-companion`.
+- Makes local code overlay Git hooks background by default so `git commit` and
+  `git push` return quickly while Snipara refreshes local overlay state and
+  push-time promotion asynchronously.
+- Adds `snipara-companion code hooks install --synchronous` for teams that
+  intentionally want foreground hook work, plus a configurable background
+  reindex delay for pre-push promotion.
 
 ## New In 1.3.7
 
@@ -159,7 +128,6 @@ session with `snipara-companion`:
 
 ```bash
 snipara-companion status
-snipara-companion git summary
 snipara-companion brief --task "ship auth hardening" --changed-files src/auth.ts
 snipara-companion timeline
 snipara-companion workflow phase-commit build --summary "tests green"
@@ -170,8 +138,6 @@ snipara-companion workflow resume --include-session-context
 
 - `status` is the Git-style local work status: workflow phase, latest phase
   commit, git dirtiness, Team Sync handoffs, local risks, and next action.
-- `git summary` is a local-only Git companion view: branch, HEAD, upstream
-  ahead/behind, dirty files, recent commits, and suggested next commands.
 - `brief` is the short alias for `intelligence brief`.
 - `timeline` is the Git-style log for workflow starts, phase starts, phase
   commits, final commits, and Team Sync handoffs.
@@ -196,11 +162,9 @@ The mental model is intentionally close to Git:
 API only for the final Team Sync handoff. The CLI sends a compact summary with a
 longer timeout, retries once with a shorter summary on transient hosted failures,
 and then records a local fallback handoff in `.snipara/team-sync/session.json`
-if the hosted call still times out. Without Cloud config, `final-commit` closes
-the local workflow and writes the local handoff directly. A hosted final-commit
-timeout does not modify Git state. Custom final-commit categories are namespaced
-under `final-commit` before the hosted call so they stay on the handoff-only
-path.
+if the hosted call still times out. A hosted final-commit timeout does not modify
+Git state. Custom final-commit categories are namespaced under `final-commit`
+before the hosted call so they stay on the handoff-only path.
 
 ## Verification Plans
 
@@ -691,7 +655,6 @@ Semantics:
 - `snipara-companion workflow run --mode orchestrate` = explicit hosted orchestrator flow for deeper multi-step exploration; use the Python `snipara-orchestrator` package for production gates and htasks
 - `snipara-companion workflow run` = suggests Snipara Sandbox when the query calls for validation, execution, data transforms, or heavier FULL/orchestrated work
 - `snipara-companion status` = top-level agentic work status across local workflow state, git dirtiness, and Team Sync carryover
-- `snipara-companion git summary` = local-only Git companion summary with branch, HEAD, upstream ahead/behind, dirty files, recent commits, and handoff-oriented next commands
 - `snipara-companion brief` = short alias for `snipara-companion intelligence brief`
 - `snipara-companion timeline` = local timeline of workflow starts, phase starts, phase commits, final commits, and Team Sync handoffs
 - `snipara-companion handoff` = top-level agent-ready Markdown/JSON handoff artifact plus the same local/hosted Team Sync handoff persistence
@@ -700,15 +663,15 @@ Semantics:
 - `snipara-companion workflow scaffold --preset project-intelligence-continuity-layer` = creates a four-phase managed plan for memory authority, code impact, continuity summaries, and release/docs surfaces
 - `snipara-companion workflow phase-start` = marks the current phase and prints the required Snipara context gate plus code-impact / symbol-card gates; runtime-marked phases also get a stable Snipara Sandbox session binding
 - `snipara-companion workflow runtime-checkpoint` = captures a resume-ready Snipara Sandbox checkpoint for one phase using local workflow state plus a hosted automation event when configured
-- `snipara-companion workflow phase-commit` = updates local workflow state and advances the next phase; when Cloud is connected it also calls hosted `snipara_end_of_task_commit`
-- `snipara-companion workflow resume` = reloads local workflow state plus hosted durable/session memory when Cloud is connected, or local `snipara-memory` session context when available; runtime-bound phases also print a Snipara Sandbox reattach or rehydrate plan; rerun `workflow phase-start` before editing again
+- `snipara-companion workflow phase-commit` = calls hosted `snipara_end_of_task_commit` for that phase, updates local state, and advances the next phase; if the hosted commit times out or hits a transient network failure, local workflow state still advances with an explicit local fallback record
+- `snipara-companion workflow resume` = reloads local workflow state plus hosted durable/session memory after compaction or resume, then appends the latest hosted Team Sync handoff/checkpoint context when available; runtime-bound phases also print a Snipara Sandbox reattach or rehydrate plan; rerun `workflow phase-start` before editing again
 - `snipara-companion workflow resume` does not snapshot or exactly restore a live Snipara Sandbox process; exact process restore remains a roadmap item
 - `snipara-companion team-sync start-work` = keeps the local session file and fetches the hosted Start Work Brief when the workspace has project auth
 - `snipara-companion team-sync handoff` = keeps the local handoff record and publishes the hosted handoff capsule when project auth is available
 - `snipara-companion team-sync what-changed` = prints the local state summary and the hosted What Changed For Me response when configured
 - `snipara-companion team-sync sweep` = archives stale local work items after an inactivity threshold; default is 14 days and `--dry-run` previews the cleanup
 - `snipara-companion team-sync resume` = reloads local carryover plus the hosted latest handoff and checkpoint-aware resume guidance when available
-- `snipara-companion final-commit` / `workflow final-commit` = closes the managed workflow locally; when Cloud is connected it also persists the final hosted handoff, otherwise it writes a local Team Sync handoff
+- `snipara-companion final-commit` / `workflow final-commit` = final hosted commit for the managed workflow
 - `snipara-companion code symbol-card` = direct paid Context `snipara_code_symbol_card` for an important symbol before editing, with an agent guidance summary before raw JSON
 - `snipara-companion code impact` = direct paid Context `snipara_code_impact` for changed files, a file, or a symbol before risky changes, with risk/actions/gaps summarized before raw JSON
 - `snipara-companion doctor` = local readiness check for Snipara auth, deterministic hosted tool catalog access, Snipara Sandbox, Snipara Sandbox MCP wiring, provider keys, and Docker
@@ -725,10 +688,9 @@ Semantics:
 - `snipara-companion memory compact` = hosted compaction preview only; it always calls `snipara_memory_compact` with `dry_run=true` and never mutates memory
 - `snipara-companion reindex` = trigger or poll hosted `snipara_reindex`; use after uploads when immediate chunk availability matters
 - `snipara-companion code *` = direct access to the code graph tools without routing through `snipara_context_query`
-- `snipara-companion recall` = Cloud durable memory lookup when connected; otherwise local `snipara-memory` recall when installed
-- `snipara-companion query` = Cloud MCP context query when connected; otherwise local `snipara-memory` recall-style query when installed
-- `snipara-companion session-bootstrap` = Cloud durable/session memory when connected; otherwise local `snipara-memory` session bundle when installed
-- `snipara-companion task-commit` = hosted durable task/phase/workflow outcomes when connected; without Cloud, use local `team-sync handoff` or `final-commit` for OSS continuity
+- `snipara-companion recall` = direct durable memory lookup for decisions, learnings, preferences, and carryover
+- `snipara-companion session-bootstrap` = durable memory first, optional weak session carryover second
+- `snipara-companion task-commit` = durable task/phase/workflow outcomes only, not a mechanical mirror of every Git commit
 - `snipara-companion memory-guard check` = forced memory/context recall before retries, commits, or finalization when a command failed or a publishable package surface is touched
 - `snipara-companion memory-guard check --intent "<action>" --destructive --strict` = contradiction check before irreversible actions; blocks until the user explicitly confirms when memory/context disagrees or the action is destructive
 - `snipara-companion memory-guard remember --guard-tag pre-commit --text "..."` = create a project/team memory in a guard category such as `pre-commit`, `commit`, `failure`, `pre-final`, or `workflow-policy`
@@ -785,6 +747,8 @@ Companion separates two concepts:
 - `git commit` is a version-control checkpoint.
 - `snipara-companion task-commit`, `workflow phase-commit`, and `final-commit` call hosted
   `snipara_end_of_task_commit` to persist meaningful task, phase, or workflow outcomes.
+  `workflow phase-commit` and `final-commit` keep local workflow state moving on transient
+  hosted commit timeouts and surface that local fallback explicitly in the result.
 
 Do not call `snipara_end_of_task_commit` mechanically for every Git commit. For risky commits,
 package releases, or retries after failures, run Memory Guard first so the agent sees relevant
@@ -895,7 +859,8 @@ or `unchanged` counts until a real sync runs.
 For release-hardening and local packaging checks:
 
 ```bash
-pnpm pack:smoke
+pnpm --filter snipara-companion pack:smoke
+pnpm --filter create-snipara pack:smoke
 ```
 
 To test a packed tarball manually, use `npm exec --package`:

package/dist/index.d.ts

@@ -716,6 +716,113 @@ interface TeamSyncResumeResponse {
     recommendedActions: string[];
     caveats: string[];
 }
+type CollaborationActorType = "HUMAN" | "AGENT" | "SYSTEM";
+type CollaborationResourceKind = "FILE" | "ROUTE" | "SYMBOL" | "SCHEMA" | "PACKAGE" | "DEPLOY" | "SURFACE" | "CUSTOM";
+type CollaborationLeaseMode = "WATCH" | "ADVISORY" | "REQUIRES_ACK" | "EXCLUSIVE" | "HARD_BLOCK";
+type CollaborationLeaseStatus = "ACTIVE" | "RELEASED" | "EXPIRED" | "OVERRIDDEN";
+type CollaborationConflictSeverity = "INFO" | "WATCH" | "WARNING" | "CRITICAL";
+type CollaborationGuardDecision = "CLEAR" | "WATCH" | "REVIEW_REQUIRED" | "REQUIRES_ACK" | "BLOCKED";
+interface CollaborationResource {
+    kind: CollaborationResourceKind;
+    id: string;
+    label?: string;
+    sourcePath?: string;
+}
+interface CollaborationActorPayload {
+    actorId?: string;
+    actorType?: CollaborationActorType;
+    actorLabel?: string;
+    sessionId?: string;
+}
+interface CollaborationSessionSummary {
+    id: string;
+    actorId: string;
+    actorType: CollaborationActorType;
+    actorLabel?: string | null;
+    sessionId?: string | null;
+    swarmId?: string | null;
+    client?: string | null;
+    repository?: string | null;
+    branch?: string | null;
+    worktree?: string | null;
+    task?: string | null;
+    status: string;
+    dirtyFiles?: string[];
+    startedAt?: string;
+    lastHeartbeatAt?: string;
+    heartbeatTtlSeconds?: number | null;
+    [key: string]: unknown;
+}
+interface CollaborationLeaseSummary {
+    id: string;
+    workSessionId?: string | null;
+    swarmId?: string | null;
+    resourceKind: CollaborationResourceKind;
+    resourceId: string;
+    resourceLabel?: string | null;
+    mode: CollaborationLeaseMode;
+    status: CollaborationLeaseStatus;
+    claimedByActorId: string;
+    claimedByActorType: CollaborationActorType;
+    claimedByLabel?: string | null;
+    reason?: string | null;
+    claimedAt?: string;
+    heartbeatAt?: string;
+    expiresAt?: string | null;
+    [key: string]: unknown;
+}
+interface CollaborationConflict {
+    code: string;
+    decision: CollaborationGuardDecision;
+    severity: CollaborationConflictSeverity;
+    resource: CollaborationResource;
+    conflictingActor: {
+        actorId: string;
+        actorType: CollaborationActorType;
+        actorLabel?: string | null;
+        sessionId?: string | null;
+    };
+    reason: string;
+    recommendedAction: string;
+    leaseId?: string | null;
+    workSessionId?: string | null;
+}
+interface CollaborationGuardEvaluation {
+    decision: CollaborationGuardDecision;
+    severity: CollaborationConflictSeverity;
+    evaluatedAt: string;
+    resources: CollaborationResource[];
+    conflicts: CollaborationConflict[];
+    recommendedActions: string[];
+}
+interface CollaborationStateResponse {
+    project: TeamSyncProjectSummary;
+    sessions: CollaborationSessionSummary[];
+    leases: CollaborationLeaseSummary[];
+    events?: Array<Record<string, unknown>>;
+    sessionSnapshots: unknown[];
+    leaseSnapshots: unknown[];
+}
+interface CollaborationSessionResponse {
+    project: TeamSyncProjectSummary;
+    session: CollaborationSessionSummary;
+    resources: CollaborationResource[];
+}
+interface CollaborationLeaseResponse {
+    project: TeamSyncProjectSummary;
+    resources: CollaborationResource[];
+    leases: CollaborationLeaseSummary[];
+}
+interface CollaborationLeaseUpdateResponse {
+    project: TeamSyncProjectSummary;
+    lease: CollaborationLeaseSummary;
+}
+interface CollaborationGuardResponse {
+    project: TeamSyncProjectSummary;
+    resources: CollaborationResource[];
+    evaluation: CollaborationGuardEvaluation;
+    guardEvent: Record<string, unknown> | null;
+}
 interface ApiKeyProjectSummary {
     id: string;
     name: string;
@@ -736,6 +843,7 @@ declare class RLMClient {
     private resolveProjectIdentifier;
     private dashboardApiUrl;
     private fetchWithApiKeyRetry;
+    private dashboardProjectRequest;
     /**
      * Make an MCP JSON-RPC request
      */
@@ -922,6 +1030,57 @@ declare class RLMClient {
         task?: string;
         recentFiles?: string[];
     }): Promise<TeamSyncResumeResponse>;
+    getCollaborationState(): Promise<CollaborationStateResponse>;
+    startCollaborationSession(args: CollaborationActorPayload & {
+        workSessionId?: string;
+        swarmId?: string;
+        client?: string;
+        repository?: string;
+        branch?: string;
+        worktree?: string;
+        task?: string;
+        heartbeatTtlSeconds?: number;
+        files?: string[];
+        dirtyFiles?: string[];
+        resources?: CollaborationResource[];
+        metadata?: Record<string, unknown>;
+    }): Promise<CollaborationSessionResponse>;
+    updateCollaborationSession(workSessionId: string, args: CollaborationActorPayload & {
+        status?: "ACTIVE" | "STALE" | "COMPLETED" | "ABANDONED";
+        swarmId?: string;
+        client?: string;
+        repository?: string;
+        branch?: string;
+        worktree?: string;
+        task?: string;
+        heartbeatTtlSeconds?: number;
+        files?: string[];
+        dirtyFiles?: string[];
+        resources?: CollaborationResource[];
+        metadata?: Record<string, unknown>;
+    }): Promise<CollaborationSessionResponse>;
+    createCollaborationLeases(args: CollaborationActorPayload & {
+        workSessionId?: string;
+        swarmId?: string;
+        mode?: CollaborationLeaseMode;
+        reason?: string;
+        ttlSeconds?: number;
+        files?: string[];
+        resources?: CollaborationResource[];
+        metadata?: Record<string, unknown>;
+    }): Promise<CollaborationLeaseResponse>;
+    updateCollaborationLease(leaseId: string, args: {
+        action?: "heartbeat" | "release" | "override";
+        reason?: string;
+    }): Promise<CollaborationLeaseUpdateResponse>;
+    evaluateCollaborationGuard(args: CollaborationActorPayload & {
+        workSessionId?: string;
+        action?: string;
+        files?: string[];
+        resources?: CollaborationResource[];
+        persist?: boolean;
+        metadata?: Record<string, unknown>;
+    }): Promise<CollaborationGuardResponse>;
     plan(query: string, maxTokens?: number): Promise<Record<string, unknown>>;
     uploadDocument(path: string, content: string, options?: UploadDocumentOptions): Promise<Record<string, unknown>>;
     listBusinessCollections(options?: ListBusinessCollectionsOptions): Promise<Record<string, unknown>>;
@@ -1077,50 +1236,6 @@ declare function detectReleaseSurfacesFromFiles(root: string, files: string[]):
 declare function getStagedFiles(root: string): string[];
 declare function runMemoryGuardCheck(options?: MemoryGuardCheckOptions): Promise<MemoryGuardCheckResult>;
 
-interface GitCompanionSummaryOptions {
-    cwd?: string;
-    recentLimit?: number;
-}
-interface GitCompanionSummary {
-    version: "snipara.git_companion.v1";
-    generatedAt: string;
-    repository?: {
-        root: string;
-        branch?: string;
-        head?: string;
-        upstream?: string;
-        ahead?: number;
-        behind?: number;
-    };
-    status: {
-        clean: boolean;
-        total: number;
-        staged: string[];
-        unstaged: string[];
-        untracked: string[];
-        conflicted: string[];
-        lines: string[];
-    };
-    recentCommits: Array<{
-        sha: string;
-        shortSha: string;
-        author: string;
-        date: string;
-        subject: string;
-    }>;
-    hosted: {
-        status: "not_required";
-        note: string;
-    };
-    suggestedCommands: string[];
-    error?: string;
-}
-declare function buildGitCompanionSummary(options?: GitCompanionSummaryOptions): GitCompanionSummary;
-declare function gitSummaryCommand(options: {
-    recent?: number;
-    json?: boolean;
-}): Promise<void>;
-
 interface ProjectIntelligenceBriefOptions {
     task?: string;
     branch?: string;
@@ -1135,7 +1250,6 @@ interface ProjectIntelligenceBriefOptions {
 interface ProjectIntelligenceBrief {
     version: "project-intelligence-brief-v1";
     generatedAt: string;
-    provider: "hosted" | "local";
     branch?: string;
     task?: string;
     changedFiles: string[];
@@ -1143,8 +1257,6 @@ interface ProjectIntelligenceBrief {
     resumeContext?: Record<string, unknown>;
     memoryHealth?: Record<string, unknown>;
     codeImpact?: Record<string, unknown>;
-    localMemory?: RecallResult;
-    hosted?: Record<string, unknown>;
     errors: Array<{
         surface: string;
         message: string;
@@ -1327,6 +1439,7 @@ interface CodeStatusCommandOptions {
 interface CodeSyncCommandOptions extends CodeStatusCommandOptions {
     commit?: string;
     workingTree?: boolean;
+    onlyIfHead?: string;
 }
 interface CodeUploadCommandOptions extends CodeStatusCommandOptions {
     cached?: boolean;
@@ -1349,6 +1462,8 @@ interface CodeHooksInstallCommandOptions {
     dir?: string;
     maxFiles?: number;
     requestReindex?: boolean;
+    reindexDelaySeconds?: number;
+    synchronous?: boolean;
     dryRun?: boolean;
     json?: boolean;
 }
@@ -2007,6 +2122,100 @@ declare function getTeamSyncStatePath(rootDir?: string): string;
 declare function buildAgenticHandoffMarkdown(artifact: AgenticHandoffArtifact): string;
 declare function teamSyncSweepCommand(options: TeamSyncCommandOptions): Promise<void>;
 
+declare const COLLABORATION_STATE_RELATIVE_PATH: string;
+interface CollaborationCommandOptions {
+    summary?: string;
+    files?: string[];
+    resources?: string[];
+    actor?: string;
+    actorId?: string;
+    actorType?: string;
+    sessionId?: string;
+    workSessionId?: string;
+    swarmId?: string;
+    client?: string;
+    repository?: string;
+    branch?: string;
+    worktree?: string;
+    action?: string;
+    profile?: string;
+    mode?: string;
+    reason?: string;
+    ttlSeconds?: string;
+    heartbeatTtlSeconds?: string;
+    intervalSeconds?: string;
+    maxFiles?: string;
+    leaseId?: string;
+    all?: boolean;
+    once?: boolean;
+    autoClaim?: boolean;
+    releaseStale?: boolean;
+    persist?: boolean;
+    enforce?: boolean;
+    dir?: string;
+    json?: boolean;
+}
+interface CollaborationHooksInstallOptions {
+    dir?: string;
+    dryRun?: boolean;
+    json?: boolean;
+}
+interface CollaborationLocalLeaseRecord {
+    id: string;
+    mode: CollaborationLeaseMode;
+    status: CollaborationLeaseStatus;
+    resources: CollaborationResource[];
+    reason?: string;
+    claimedAt?: string;
+    expiresAt?: string | null;
+}
+interface CollaborationLocalState {
+    schemaVersion: "snipara.collaboration.v1";
+    updatedAt: string;
+    workSessionId?: string;
+    sessionId?: string;
+    actorId?: string;
+    actorType?: CollaborationActorType;
+    actorLabel?: string;
+    client?: string;
+    repository?: string;
+    branch?: string;
+    worktree?: string;
+    task?: string;
+    files: string[];
+    resources: CollaborationResource[];
+    leases: CollaborationLocalLeaseRecord[];
+    lastGuard?: {
+        decision: CollaborationGuardDecision;
+        severity: string;
+        checkedAt: string;
+        action: string;
+        resources: CollaborationResource[];
+        conflictCount: number;
+    };
+}
+interface ResolvedCollaborationContext {
+    rootDir: string;
+    config: RLMConfig;
+    actor: Required<Pick<CollaborationActorPayload, "actorId" | "actorType" | "actorLabel">> & {
+        sessionId?: string;
+    };
+    client: string;
+    branch?: string;
+    repository?: string;
+    worktree?: string;
+}
+declare function createEmptyCollaborationState(now?: Date): CollaborationLocalState;
+declare function getCollaborationStatePath(rootDir?: string): string;
+declare function loadCollaborationState(rootDir?: string): CollaborationLocalState;
+declare function saveCollaborationState(state: CollaborationLocalState, rootDir?: string): void;
+declare function buildCollaborationActor(options: Pick<CollaborationCommandOptions, "actor" | "actorId" | "actorType" | "sessionId" | "client">, config: RLMConfig): ResolvedCollaborationContext["actor"];
+declare function normalizeCollaborationFiles(files: string[] | undefined): string[];
+declare function parseCollaborationResources(values: string[] | undefined): CollaborationResource[];
+declare function deriveLocalCollaborationResourcesFromFiles(files: string[] | undefined, rootDir?: string, maxFiles?: number): CollaborationResource[];
+declare function buildCollaborationHooksInstallPlan(options?: CollaborationHooksInstallOptions): Record<string, unknown>;
+declare function collaborationIdeStatusCommand(options: CollaborationCommandOptions): Promise<void>;
+
 interface JournalCheckpointPayload {
     action: string;
     summary: string;
@@ -2194,4 +2403,4 @@ interface WrittenOrchestratorHandoff {
 declare function buildOrchestratorHandoff(options: OrchestratorHandoffOptions): OrchestratorHandoffArtifact;
 declare function writeOrchestratorHandoff(options: OrchestratorHandoffOptions): WrittenOrchestratorHandoff;
 
-export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, archiveInactiveTeamSyncWork, autoArchiveTeamSyncState, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildGitCompanionSummary, buildHostedCodeOverlayUploadPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, collectSyncDocuments, collectSyncDocumentsInput, createClient, createEmptyTeamSyncState, createLocalQueryCache, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, extractCommandFromToolInput, extractFilesFromToolInput, formatOrchestratorRecommendationReason, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getConfigPath, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, gitSummaryCommand, ingestReferences, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, normalizeGuardTag, normalizeWorkflowPlanInput, projectIntelligenceBriefCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, referencesIngestCommand, referencesScanCommand, resolveQueryFromToolInput, runMemoryGuardCheck, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };
+export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, COLLABORATION_STATE_RELATIVE_PATH, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, archiveInactiveTeamSyncWork, autoArchiveTeamSyncState, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCollaborationActor, buildCollaborationHooksInstallPlan, buildHostedCodeOverlayUploadPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, collaborationIdeStatusCommand, collectSyncDocuments, collectSyncDocumentsInput, createClient, createEmptyCollaborationState, createEmptyTeamSyncState, createLocalQueryCache, deriveLocalCollaborationResourcesFromFiles, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, extractCommandFromToolInput, extractFilesFromToolInput, formatOrchestratorRecommendationReason, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getCollaborationStatePath, getConfigPath, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, parseCollaborationResources, projectIntelligenceBriefCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, referencesIngestCommand, referencesScanCommand, resolveQueryFromToolInput, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };