snipara-companion 1.4.1 → 1.4.2

package/README.md

@@ -59,6 +59,19 @@ yarn global add snipara-companion
 snipara-companion
 ```
 
+## New In 1.4.2
+
+- 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
 
 - Makes local code overlay Git hooks background by default so `git commit` and
@@ -650,7 +663,7 @@ 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` = calls hosted `snipara_end_of_task_commit` for that phase, updates local state, and advances the next phase
+- `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
@@ -734,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

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>>;
@@ -1963,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;
@@ -2150,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, 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, 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 };