@sayknow-cli/coding-agent 0.4.1 → 0.4.3

package/dist/types/skc-runtime/team-notify.d.ts

@@ -0,0 +1,45 @@
+import type { SkcTeamConfig, SkcTeamMailboxMessage } from "./team-runtime";
+import type { SkcTeamMailboxDeliveryInput, SkcTeamMailboxDeliveryResult, SkcTeamMailboxDeliveryTransport, SkcTeamNotification, SkcTeamNotificationDeliveryState, SkcTeamNotificationSummary } from "./team-store";
+/** Runtime-owned filesystem and participant operations used by notification delivery. */
+export interface TeamNotificationRuntime {
+    findTeamDir(teamName: string, cwd: string, env: NodeJS.ProcessEnv): Promise<string>;
+    readConfig(dir: string): Promise<SkcTeamConfig>;
+    assertKnownParticipant(config: SkcTeamConfig, participant: string): void;
+    messageId(input: {
+        teamName: string;
+        fromWorker: string;
+        toWorker: string;
+        body: string;
+        idempotencyKey?: string;
+        createdKey: string;
+    }): string;
+    messageNotificationId(teamName: string, recipient: string, messageId: string): string;
+    now(): string;
+    randomId(): string;
+    appendEvent(dir: string, event: {
+        type: string;
+        worker?: string;
+        message?: string;
+        data?: Record<string, unknown>;
+    }): Promise<void>;
+    readMailbox(dir: string, worker: string): Promise<{
+        messages: SkcTeamMailboxMessage[];
+    }>;
+    writeMailboxMessage(dir: string, worker: string, message: SkcTeamMailboxMessage): Promise<SkcTeamMailboxMessage>;
+    listNotifications(dir: string): Promise<SkcTeamNotification[]>;
+    readNotification(dir: string, id: string): Promise<SkcTeamNotification>;
+    writeNotification(dir: string, notification: SkcTeamNotification): Promise<SkcTeamNotification>;
+}
+export declare function deliverTeamMailboxMessage(transport: SkcTeamMailboxDeliveryTransport | undefined, input: SkcTeamMailboxDeliveryInput): Promise<SkcTeamMailboxDeliveryResult | null>;
+export declare function emptyTeamNotificationSummary(): SkcTeamNotificationSummary;
+export declare function isReplayEligibleTeamNotification(state: SkcTeamNotificationDeliveryState): boolean;
+export declare function summarizeTeamNotifications(notifications: SkcTeamNotification[]): SkcTeamNotificationSummary;
+export declare function createTeamMessageNotification(runtime: TeamNotificationRuntime, dir: string, teamName: string, message: SkcTeamMailboxMessage, state?: SkcTeamNotificationDeliveryState): Promise<SkcTeamNotification>;
+export declare function reconcileTeamNotifications(runtime: TeamNotificationRuntime, dir: string, config: SkcTeamConfig): Promise<SkcTeamNotificationSummary>;
+export declare function replayTeamNotifications(runtime: TeamNotificationRuntime, teamName: string, cwd: string, env: NodeJS.ProcessEnv, transport?: SkcTeamMailboxDeliveryTransport): Promise<{
+    notifications: SkcTeamNotification[];
+    summary: SkcTeamNotificationSummary;
+}>;
+export declare function sendTeamMessage(runtime: TeamNotificationRuntime, teamName: string, fromWorker: string, toWorker: string, body: string, cwd: string, env: NodeJS.ProcessEnv, idempotencyKey?: string, transport?: SkcTeamMailboxDeliveryTransport): Promise<SkcTeamMailboxMessage>;
+export declare function listTeamMailbox(runtime: TeamNotificationRuntime, teamName: string, worker: string, cwd: string, env: NodeJS.ProcessEnv): Promise<SkcTeamMailboxMessage[]>;
+export declare function markTeamMailboxMessage(runtime: TeamNotificationRuntime, teamName: string, worker: string, messageId: string, field: "delivered_at" | "notified_at", cwd: string, env: NodeJS.ProcessEnv): Promise<SkcTeamMailboxMessage>;

package/dist/types/skc-runtime/team-runtime.d.ts

@@ -0,0 +1,361 @@
+import type { WorkflowHudSummary } from "../skill-state/active-state";
+import type { GcPidProbe, GcRecord } from "./gc-runtime";
+export type SkcTeamPhase = "starting" | "running" | "awaiting_integration" | "complete" | "failed" | "cancelled";
+export type SkcTeamTaskStatus = "pending" | "blocked" | "in_progress" | "completed" | "failed";
+export type SkcWorkerStatusState = "idle" | "working" | "blocked" | "done" | "failed" | "draining" | "unknown";
+export type SkcTeamWorkerLifecycleState = "starting" | "ready" | "working" | "draining" | "stopped" | "failed" | "unknown";
+export type SkcTeamShutdownMode = "graceful" | "force" | "abort";
+export declare const SKC_TEAM_DEFAULT_WORKERS = 3;
+export declare const SKC_TEAM_MAX_WORKERS = 20;
+export type SkcTeamWorkerCli = "skc";
+export interface SkcTeamLeader {
+    session_id: string;
+    pane_id: string;
+    cwd: string;
+}
+export interface SkcTeamWorker {
+    id: string;
+    name: string;
+    index: number;
+    agent_type: string;
+    role: string;
+    pane_id?: string;
+    status: "starting" | "idle" | "busy" | "stopped";
+    last_heartbeat: string;
+    assigned_tasks: string[];
+    worktree_repo_root?: string;
+    worktree_path?: string;
+    worktree_branch?: string | null;
+    worktree_detached?: boolean;
+    worktree_created?: boolean;
+    worktree_base_ref?: string;
+    team_state_root?: string;
+}
+export interface SkcTeamTaskClaim {
+    owner: string;
+    token: string;
+    leased_until: string;
+}
+export type SkcTeamTaskCompletionEvidenceKind = "command" | "inspection" | "artifact";
+export type SkcTeamTaskCompletionEvidenceStatus = "passed" | "failed" | "not_run" | "verified" | "rejected";
+export interface SkcTeamTaskCompletionEvidenceItem {
+    kind: SkcTeamTaskCompletionEvidenceKind;
+    status: SkcTeamTaskCompletionEvidenceStatus;
+    summary: string;
+    command?: string;
+    artifact?: string;
+    location?: string;
+    output?: string;
+}
+export interface SkcTeamTaskCompletionEvidence {
+    summary: string;
+    items: SkcTeamTaskCompletionEvidenceItem[];
+    files?: string[];
+    notes?: string;
+    recorded_by: string;
+    recorded_at: string;
+}
+export interface SkcTeamTask {
+    id: string;
+    subject: string;
+    description: string;
+    title: string;
+    objective: string;
+    status: SkcTeamTaskStatus;
+    assignee?: string;
+    owner?: string;
+    result?: string;
+    completion_evidence?: SkcTeamTaskCompletionEvidence;
+    error?: string;
+    blocked_by?: string[];
+    depends_on?: string[];
+    lane?: string;
+    required_role?: string;
+    allowed_roles?: string[];
+    version: number;
+    claim?: SkcTeamTaskClaim;
+    created_at: string;
+    updated_at: string;
+    completed_at?: string;
+}
+export type SkcTeamWorktreeMode = {
+    enabled: false;
+} | {
+    enabled: true;
+    detached: true;
+    name: null;
+} | {
+    enabled: true;
+    detached: false;
+    name: string;
+};
+import type { SkcTeamMailboxDeliveryTransport } from "./team-store";
+export interface SkcTeamConfig {
+    team_name: string;
+    display_name: string;
+    requested_name: string;
+    task: string;
+    agent_type: string;
+    worker_count: number;
+    max_workers: number;
+    state_root: string;
+    worker_command: string;
+    worker_cli_plan: SkcTeamWorkerCli[];
+    tmux_command: string;
+    tmux_session: string;
+    tmux_session_name: string;
+    tmux_target: string;
+    workspace_mode: "direct" | "worktree";
+    dry_run: boolean;
+    leader: SkcTeamLeader;
+    leader_cwd: string;
+    team_state_root: string;
+    workers: SkcTeamWorker[];
+    created_at: string;
+    skc_session_id?: string;
+    updated_at: string;
+}
+export type SkcTeamIntegrationStatus = "idle" | "integrated" | "integration_failed" | "merge_conflict" | "cherry_pick_conflict" | "rebase_conflict";
+export interface SkcTeamWorkerIntegrationState {
+    last_seen_head?: string;
+    last_integrated_head?: string;
+    last_leader_head?: string;
+    last_rebased_leader_head?: string;
+    status?: SkcTeamIntegrationStatus;
+    conflict_commit?: string;
+    conflict_files?: string[];
+    updated_at?: string;
+}
+export interface SkcTeamMonitorSnapshot {
+    integration_by_worker: Record<string, SkcTeamWorkerIntegrationState>;
+    updated_at: string;
+}
+export interface SkcTeamWorkerLifecycle {
+    worker: string;
+    lifecycle_state: SkcTeamWorkerLifecycleState;
+    worker_status_state: SkcWorkerStatusState;
+    pane_id?: string;
+    pid?: number;
+    started_at?: string;
+    updated_at: string;
+    stopped_at?: string;
+    stop_reason?: string;
+    shutdown_request_id?: string;
+    shutdown_requested_at?: string;
+    shutdown_acknowledged_at?: string;
+    shutdown_ack_status?: string;
+    shutdown_mode?: SkcTeamShutdownMode;
+}
+export type SkcTeamNotificationDeliveryState = "pending" | "sent" | "queued" | "deferred" | "failed" | "delivered" | "acknowledged";
+export type SkcTeamPaneAttemptResult = "sent" | "queued" | "deferred" | "failed";
+export interface SkcTeamNotification {
+    id: string;
+    kind: "mailbox_message" | "worker_lifecycle" | "invalid_attempt";
+    team_name: string;
+    recipient: string;
+    source: {
+        type: "message" | "task" | "worker" | "event";
+        id: string;
+    };
+    idempotency_key?: string;
+    delivery_state: SkcTeamNotificationDeliveryState;
+    pane_attempt_result?: SkcTeamPaneAttemptResult;
+    pane_attempt_reason?: string;
+    pane_attempt_at?: string;
+    created_at: string;
+    updated_at: string;
+    replay_count: number;
+}
+export interface SkcTeamNotificationSummary {
+    total: number;
+    replay_eligible: number;
+    by_state: Record<SkcTeamNotificationDeliveryState, number>;
+}
+export interface SkcTeamSnapshot {
+    team_name: string;
+    display_name: string;
+    phase: SkcTeamPhase;
+    state_dir: string;
+    tmux_session: string;
+    tmux_session_name: string;
+    tmux_target: string;
+    task_total: number;
+    task_counts: Record<SkcTeamTaskStatus, number>;
+    workers: SkcTeamWorker[];
+    integration_by_worker?: Record<string, SkcTeamWorkerIntegrationState>;
+    worker_lifecycle_by_id: Record<string, SkcTeamWorkerLifecycle>;
+    notification_summary: SkcTeamNotificationSummary;
+    updated_at: string;
+}
+export interface SkcTeamSnapshotOptions {
+    reconcileNotifications?: boolean;
+}
+export interface SkcTeamStartOptions {
+    workerCount: number;
+    agentType: string;
+    task: string;
+    teamName?: string;
+    worktreeMode?: SkcTeamWorktreeMode;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    dryRun?: boolean;
+    /** Per-team mailbox delivery transport override (sdk vs pane). */
+    mailboxDeliveryTransport?: SkcTeamMailboxDeliveryTransport;
+    /** Platform override for testability; defaults to process.platform. */
+    platform?: NodeJS.Platform;
+}
+export interface SkcTeamApiClaimResult {
+    ok: boolean;
+    task?: SkcTeamTask;
+    worker_id?: string;
+    claim_token?: string;
+    reason?: string;
+}
+export type SkcTeamLivenessRecoveryReason = "claim_expired" | "stale_heartbeat" | "missing_pane" | "worker_lifecycle_failed" | "worker_lifecycle_stopped";
+export interface SkcTeamRecoveredClaim {
+    task_id: string;
+    worker: string;
+    reasons: SkcTeamLivenessRecoveryReason[];
+}
+export interface SkcTeamLivenessRecoveryResult {
+    recovered_claims: SkcTeamRecoveredClaim[];
+    stale_workers: Record<string, SkcTeamLivenessRecoveryReason[]>;
+}
+export interface SkcTeamMailboxMessage {
+    message_id: string;
+    from_worker: string;
+    to_worker: string;
+    body: string;
+    created_at: string;
+    delivered_at?: string;
+    notified_at?: string;
+    idempotency_key?: string;
+}
+export declare function resolveSkcTeamWorkerCli(env?: NodeJS.ProcessEnv): SkcTeamWorkerCli;
+export declare function resolveSkcTeamWorkerCliPlan(workerCount: number, env?: NodeJS.ProcessEnv): SkcTeamWorkerCli[];
+export declare function translateSkcWorkerLaunchArgsForCli(workerCli: SkcTeamWorkerCli, args: string[]): string[];
+export interface SkcTeamEvent {
+    event_id: string;
+    ts: string;
+    type: string;
+    worker?: string;
+    task_id?: string;
+    message?: string;
+    data?: Record<string, unknown>;
+}
+export interface SkcTeamTraceEvent {
+    schema_version: 1;
+    trace_id: string;
+    span_id: string;
+    source_event_id: string;
+    event_type: string;
+    ts: string;
+    worker?: string;
+    task_id?: string;
+    message?: string;
+    evidence_refs?: string[];
+    data?: Record<string, unknown>;
+}
+export interface WorkerStatusFile {
+    state: SkcWorkerStatusState;
+    current_task_id?: string;
+    reason?: string;
+    updated_at: string;
+}
+export interface WorkerHeartbeatFile {
+    pid: number;
+    last_turn_at: string;
+    turn_count: number;
+    alive: boolean;
+}
+export interface SkcWorkerIntegrationAttemptRequestResult {
+    requested: boolean;
+    reason: "requested" | "not_worker" | "missing_worktree" | "no_changes" | "deduped" | "git_error";
+    worker?: string;
+    team_name?: string;
+    fingerprint?: string;
+    head?: string | null;
+    status?: SkcWorkerCheckpointClassification["kind"];
+}
+export declare const SKC_TEAM_API_OPERATIONS: readonly ["send-message", "broadcast", "mailbox-list", "mailbox-mark-delivered", "mailbox-mark-notified", "notification-list", "notification-read", "notification-replay", "notification-mark-pane-attempt", "worker-startup-ack", "create-task", "read-task", "list-tasks", "update-task", "claim-task", "transition-task-status", "transition-task", "release-task-claim", "read-config", "read-manifest", "read-worker-status", "update-worker-status", "read-worker-heartbeat", "recover-stale-claims", "update-worker-heartbeat", "write-worker-inbox", "write-worker-identity", "append-event", "read-events", "read-traces", "await-event", "write-shutdown-request", "read-shutdown-ack", "read-monitor-snapshot", "write-monitor-snapshot", "read-task-approval", "write-task-approval"];
+export declare function resolveSkcTeamStateRoot(cwd?: string, env?: NodeJS.ProcessEnv): string;
+/** @internal */
+export declare function listTeamWorkerGcRecords(teamRoot: string, probe: GcPidProbe): Promise<GcRecord[]>;
+/** @internal */
+export declare function pruneTeamWorkerGcRecord(record: GcRecord, probe: GcPidProbe): Promise<boolean>;
+export declare function persistSkcTeamModeStateSummary(snapshot: SkcTeamSnapshot, cwd?: string): Promise<void>;
+export declare function recoverSkcTeamStaleClaims(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<SkcTeamLivenessRecoveryResult>;
+type SkcTeamTaskMetadataInput = Partial<Pick<SkcTeamTask, "owner" | "lane" | "required_role" | "allowed_roles" | "depends_on" | "blocked_by">>;
+export declare function resolveSkcWorkerCommand(cwd?: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, argv?: string[], execPath?: string): string;
+/** @internal Exported for unit tests. */
+export declare function buildWorkerCommand(config: SkcTeamConfig, worker: SkcTeamWorker, platform?: NodeJS.Platform): string;
+export type SkcWorkerCheckpointClassification = {
+    kind: "clean";
+    files: string[];
+} | {
+    kind: "eligible";
+    files: string[];
+} | {
+    kind: "protected_only";
+    files: string[];
+} | {
+    kind: "conflicted";
+    files: string[];
+} | {
+    kind: "git_error";
+    files: string[];
+    detail: string;
+};
+export declare function classifySkcTeamCheckpointFiles(files: string[]): {
+    eligible: string[];
+    protected: string[];
+};
+export declare function classifyWorkerCheckpointStatus(cwd: string): SkcWorkerCheckpointClassification;
+export declare function startSkcTeam(options: SkcTeamStartOptions): Promise<SkcTeamSnapshot>;
+export declare function readSkcTeamSnapshot(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv, options?: SkcTeamSnapshotOptions): Promise<SkcTeamSnapshot>;
+export declare function monitorSkcTeamSnapshot(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<SkcTeamSnapshot>;
+export declare function requestSkcWorkerIntegrationAttempt(cwd?: string, env?: NodeJS.ProcessEnv): Promise<SkcWorkerIntegrationAttemptRequestResult>;
+export declare function buildTeamHudSummary(snapshot: SkcTeamSnapshot, latestEvent?: SkcTeamEvent, latestMessage?: SkcTeamMailboxMessage): Promise<WorkflowHudSummary>;
+export declare function monitorSkcTeam(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<SkcTeamSnapshot>;
+export declare function listSkcTeams(cwd?: string, env?: NodeJS.ProcessEnv): Promise<SkcTeamSnapshot[]>;
+export declare function shutdownSkcTeam(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<SkcTeamSnapshot>;
+export declare function listSkcTeamTasks(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<SkcTeamTask[]>;
+export declare function readSkcTeamTask(teamName: string, taskId: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<SkcTeamTask>;
+export declare function createSkcTeamTask(teamName: string, subject: string, description: string, cwd?: string, env?: NodeJS.ProcessEnv, taskOptions?: SkcTeamTaskMetadataInput): Promise<SkcTeamTask>;
+export declare function updateSkcTeamTask(teamName: string, taskId: string, updates: Partial<Pick<SkcTeamTask, "subject" | "description" | "blocked_by" | "depends_on" | "lane" | "required_role" | "allowed_roles">>, cwd?: string, env?: NodeJS.ProcessEnv): Promise<SkcTeamTask>;
+export declare function claimSkcTeamTask(teamName: string, workerId: string, cwd?: string, env?: NodeJS.ProcessEnv, taskId?: string): Promise<SkcTeamApiClaimResult>;
+export declare function transitionSkcTeamTaskStatus(teamName: string, taskId: string, status: SkcTeamTaskStatus, cwd?: string, env?: NodeJS.ProcessEnv, claimToken?: string, workerId?: string, completionEvidenceInput?: unknown): Promise<SkcTeamTask>;
+export declare function transitionSkcTeamTask(teamName: string, taskId: string, status: SkcTeamTaskStatus | "complete", cwd?: string, env?: NodeJS.ProcessEnv, claimToken?: string, completionEvidenceInput?: unknown): Promise<SkcTeamTask>;
+export declare function releaseSkcTeamTaskClaim(teamName: string, taskId: string, claimToken: string, workerId: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<SkcTeamTask>;
+export declare function replaySkcTeamNotifications(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<{
+    notifications: SkcTeamNotification[];
+    summary: SkcTeamNotificationSummary;
+}>;
+export declare function sendSkcTeamMessage(teamName: string, fromWorker: string, toWorker: string, body: string, cwd?: string, env?: NodeJS.ProcessEnv, idempotencyKey?: string): Promise<SkcTeamMailboxMessage>;
+export declare function broadcastSkcTeamMessage(teamName: string, fromWorker: string, body: string, cwd?: string, env?: NodeJS.ProcessEnv, idempotencyKey?: string): Promise<SkcTeamMailboxMessage[]>;
+export declare function listSkcTeamMailbox(teamName: string, worker: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<SkcTeamMailboxMessage[]>;
+export declare function markSkcTeamMailboxMessage(teamName: string, worker: string, messageId: string, field: "delivered_at" | "notified_at", cwd?: string, env?: NodeJS.ProcessEnv): Promise<SkcTeamMailboxMessage>;
+export declare function readSkcWorkerStatus(teamName: string, worker: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<WorkerStatusFile>;
+export declare function updateSkcWorkerStatus(teamName: string, worker: string, status: SkcWorkerStatusState, cwd?: string, env?: NodeJS.ProcessEnv, currentTaskId?: string, reason?: string): Promise<WorkerStatusFile>;
+export declare function readSkcWorkerHeartbeat(teamName: string, worker: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<WorkerHeartbeatFile | null>;
+export declare function updateSkcWorkerHeartbeat(teamName: string, worker: string, heartbeat: WorkerHeartbeatFile, cwd?: string, env?: NodeJS.ProcessEnv): Promise<WorkerHeartbeatFile>;
+export declare function writeSkcWorkerInbox(teamName: string, worker: string, content: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<{
+    path: string;
+}>;
+export declare function writeSkcWorkerIdentity(teamName: string, worker: SkcTeamWorker, cwd?: string, env?: NodeJS.ProcessEnv): Promise<SkcTeamWorker>;
+export declare function readSkcTeamEvents(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<SkcTeamEvent[]>;
+export declare function readSkcTeamTraces(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<SkcTeamTraceEvent[]>;
+export declare function appendSkcTeamEvent(teamName: string, type: string, worker?: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<SkcTeamEvent>;
+export declare function awaitSkcTeamEvent(teamName: string, _timeoutMs?: number, cwd?: string, env?: NodeJS.ProcessEnv): Promise<{
+    status: "event" | "timeout";
+    event?: SkcTeamEvent;
+}>;
+export declare function writeSkcMonitorSnapshot(teamName: string, snapshot: unknown, cwd?: string, env?: NodeJS.ProcessEnv): Promise<unknown>;
+export declare function readSkcMonitorSnapshot(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<unknown>;
+export declare function writeSkcTaskApproval(teamName: string, taskId: string, approval: Record<string, unknown>, cwd?: string, env?: NodeJS.ProcessEnv): Promise<Record<string, unknown>>;
+export declare function readSkcTaskApproval(teamName: string, taskId: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<Record<string, unknown> | null>;
+export declare function writeSkcShutdownRequest(teamName: string, worker: string, requestedBy: string, cwd?: string, env?: NodeJS.ProcessEnv, requestId?: string, mode?: SkcTeamShutdownMode, requestedAt?: string): Promise<Record<string, unknown>>;
+export declare function readSkcShutdownAck(teamName: string, worker: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<Record<string, unknown> | null>;
+export declare function executeSkcTeamApiOperation(operation: string, input: Record<string, unknown>, cwd?: string, env?: NodeJS.ProcessEnv): Promise<unknown>;
+export declare function parseTeamLaunchArgs(argv: string[]): SkcTeamStartOptions;
+export {};

package/dist/types/skc-runtime/team-store.d.ts

@@ -0,0 +1,160 @@
+import type { SkcTeamConfig, SkcTeamMailboxMessage } from "./team-runtime";
+export type SkcTeamNotificationDeliveryState = "pending" | "sent" | "queued" | "deferred" | "failed" | "delivered" | "acknowledged";
+export type SkcTeamPaneAttemptResult = "sent" | "queued" | "deferred" | "failed";
+export type SkcTeamMailboxDeliveryTransportKind = "sdk" | "pane";
+export interface SkcTeamNotification {
+    id: string;
+    kind: "mailbox_message" | "worker_lifecycle" | "invalid_attempt";
+    team_name: string;
+    recipient: string;
+    source: {
+        type: "message" | "task" | "worker" | "event";
+        id: string;
+    };
+    idempotency_key?: string;
+    delivery_state: SkcTeamNotificationDeliveryState;
+    pane_attempt_result?: SkcTeamPaneAttemptResult;
+    pane_attempt_reason?: string;
+    pane_attempt_at?: string;
+    created_at: string;
+    updated_at: string;
+    replay_count: number;
+}
+export interface SkcTeamNotificationSummary {
+    total: number;
+    replay_eligible: number;
+    by_state: Record<SkcTeamNotificationDeliveryState, number>;
+}
+export interface SkcTeamMailboxDeliveryInput {
+    team_name: string;
+    state_dir: string;
+    config: SkcTeamConfig;
+    notification: SkcTeamNotification;
+    message: SkcTeamMailboxMessage;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}
+export type SkcTeamMailboxDeliveryResult = {
+    transport: "sdk";
+    state: SkcTeamNotificationDeliveryState;
+    reason?: string;
+} | {
+    transport: "pane";
+    state: SkcTeamPaneAttemptResult;
+    reason?: string;
+};
+export interface SkcTeamMailboxDeliveryTransport {
+    deliverMailboxMessage(input: SkcTeamMailboxDeliveryInput): Promise<SkcTeamMailboxDeliveryResult | null>;
+}
+export type SkcTeamTaskStatus = "pending" | "blocked" | "in_progress" | "completed" | "failed";
+export interface SkcTeamTaskClaim {
+    owner: string;
+    token: string;
+    leased_until: string;
+}
+export type SkcTeamTaskCompletionEvidenceKind = "command" | "inspection" | "artifact";
+export type SkcTeamTaskCompletionEvidenceStatus = "passed" | "failed" | "not_run" | "verified" | "rejected";
+export interface SkcTeamTaskCompletionEvidenceItem {
+    kind: SkcTeamTaskCompletionEvidenceKind;
+    status: SkcTeamTaskCompletionEvidenceStatus;
+    summary: string;
+    command?: string;
+    artifact?: string;
+    location?: string;
+    output?: string;
+}
+export interface SkcTeamTaskCompletionEvidence {
+    summary: string;
+    items: SkcTeamTaskCompletionEvidenceItem[];
+    files?: string[];
+    notes?: string;
+    recorded_by: string;
+    recorded_at: string;
+}
+export interface SkcTeamTask {
+    id: string;
+    subject: string;
+    description: string;
+    title: string;
+    objective: string;
+    status: SkcTeamTaskStatus;
+    assignee?: string;
+    owner?: string;
+    result?: string;
+    completion_evidence?: SkcTeamTaskCompletionEvidence;
+    error?: string;
+    blocked_by?: string[];
+    depends_on?: string[];
+    lane?: string;
+    required_role?: string;
+    allowed_roles?: string[];
+    version: number;
+    claim?: SkcTeamTaskClaim;
+    created_at: string;
+    updated_at: string;
+    completed_at?: string;
+}
+export type SkcTeamTaskMetadataInput = Partial<Pick<SkcTeamTask, "owner" | "lane" | "required_role" | "allowed_roles" | "depends_on" | "blocked_by">>;
+export interface SkcTeamTaskWorker {
+    id: string;
+    role: string;
+    agent_type: string;
+}
+export interface SkcTeamApiClaimResult {
+    ok: boolean;
+    task?: SkcTeamTask;
+    worker_id?: string;
+    claim_token?: string;
+    reason?: string;
+}
+type EventAppender = (event: {
+    type: string;
+    task_id?: string;
+    worker?: string;
+    message: string;
+    data?: Record<string, unknown>;
+}) => Promise<void>;
+/** The sole strict schema gate for persisted task and claim authority records. */
+export declare function isCanonicalPersistedSkcTeamTaskClaim(value: unknown): value is SkcTeamTaskClaim;
+export declare function isCanonicalPersistedSkcTeamTask(value: unknown, fileId?: string): value is SkcTeamTask;
+/**
+ * Serializes mutable team facts across processes. Callers must not re-enter this
+ * fence; use unlocked helpers when composing operations under one transaction.
+ */
+export declare function withSkcTeamMutationFence<T>(dir: string, fn: () => Promise<T>): Promise<T>;
+export declare function taskMetadataFromInput(input: Record<string, unknown>, includeOwner?: boolean): SkcTeamTaskMetadataInput;
+export declare function normalizeSkcTeamTask(raw: SkcTeamTask): SkcTeamTask;
+export declare function normalizeSkcTeamTaskCompletionEvidence(id: string, owner: string, input: unknown, recordedAt?: string): SkcTeamTaskCompletionEvidence;
+export declare function getSkcTeamTaskCompletionEvidenceFailure(task: SkcTeamTask): string | null;
+export declare const isSkcTeamTaskCompletionVerified: (task: SkcTeamTask) => boolean;
+export declare function readSkcTeamTasksFromDir(dir: string): Promise<SkcTeamTask[]>;
+declare const teamTaskMutationCapability: unique symbol;
+/**
+ * This is intentionally structural only: callers can invoke methods supplied by
+ * `withSkcTeamTaskMutation`, but cannot create an active capability. Each method
+ * closes over a private brand and is revoked when that callback settles.
+ */
+export interface SkcTeamTaskMutationCapability {
+    create(subject: string, description: string, options: SkcTeamTaskMetadataInput): Promise<SkcTeamTask>;
+    update(id: string, updates: Partial<Pick<SkcTeamTask, "subject" | "description" | "blocked_by" | "depends_on" | "lane" | "required_role" | "allowed_roles">>): Promise<SkcTeamTask>;
+    claim(worker: SkcTeamTaskWorker, id?: string): Promise<SkcTeamApiClaimResult>;
+    transition(id: string, status: SkcTeamTaskStatus, token?: string, workerId?: string, evidenceInput?: unknown): Promise<SkcTeamTask>;
+    release(id: string, token: string, workerId: string): Promise<SkcTeamTask>;
+    writeRecovered(task: SkcTeamTask): Promise<void>;
+}
+export declare function withSkcTeamTaskMutation<T>(store: SkcTeamTaskStore, fn: (capability: SkcTeamTaskMutationCapability) => Promise<T>): Promise<T>;
+export declare class SkcTeamTaskStore {
+    #private;
+    readonly dir: string;
+    readonly appendEvent: EventAppender;
+    constructor(dir: string, appendEvent: EventAppender);
+    withMutationCapability<T>(capabilityBrand: typeof teamTaskMutationCapability, fn: (capability: SkcTeamTaskMutationCapability) => Promise<T>): Promise<T>;
+    list(): Promise<SkcTeamTask[]>;
+    read(id: string): Promise<SkcTeamTask>;
+    create(subject: string, description: string, options: SkcTeamTaskMetadataInput): Promise<SkcTeamTask>;
+    update(id: string, updates: Partial<Pick<SkcTeamTask, "subject" | "description" | "blocked_by" | "depends_on" | "lane" | "required_role" | "allowed_roles">>): Promise<SkcTeamTask>;
+    claim(worker: SkcTeamTaskWorker, id?: string): Promise<SkcTeamApiClaimResult>;
+    transition(id: string, status: SkcTeamTaskStatus, token?: string, workerId?: string, evidenceInput?: unknown): Promise<SkcTeamTask>;
+    release(id: string, token: string, workerId: string): Promise<SkcTeamTask>;
+}
+export {};

package/dist/types/skc-runtime/team-workers.d.ts

@@ -0,0 +1,78 @@
+import type { SkcTeamConfig, SkcTeamLivenessRecoveryResult, SkcTeamPhase, SkcTeamShutdownMode, SkcTeamSnapshot, SkcTeamWorker, SkcTeamWorkerLifecycle, SkcTeamWorkerLifecycleState, SkcWorkerStatusState, WorkerHeartbeatFile, WorkerStatusFile } from "./team-runtime";
+import type { SkcTeamTask, SkcTeamTaskClaim, SkcTeamTaskMutationCapability } from "./team-store";
+export interface SkcTeamWorkerLifecycleContext {
+    config: SkcTeamConfig;
+    worker: SkcTeamWorker;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}
+export interface SkcTeamWorkerRuntime {
+    findTeamDir(teamName: string, cwd: string, env: NodeJS.ProcessEnv): Promise<string>;
+    readConfig(dir: string): Promise<SkcTeamConfig>;
+    assertKnownWorker(config: SkcTeamConfig, worker: string): void;
+    assertKnownParticipant(config: SkcTeamConfig, worker: string): void;
+    findKnownWorker(config: SkcTeamConfig, worker: string): SkcTeamWorker;
+    workerDir(dir: string, worker: string): string;
+    readJson<T>(filePath: string): Promise<T | null>;
+    writeJson(filePath: string, value: unknown): Promise<void>;
+    appendEvent(dir: string, event: {
+        type: string;
+        worker?: string;
+        task_id?: string;
+        message: string;
+        data?: Record<string, unknown>;
+    }): Promise<unknown>;
+    now(): string;
+    nowMs(): number;
+    stableHash(value: string): string;
+}
+export interface SkcTeamWorkerOrchestrationRuntime extends SkcTeamWorkerRuntime {
+    readTasks(dir: string): Promise<SkcTeamTask[]>;
+    withTaskMutation<T>(dir: string, fn: (capability: SkcTeamTaskMutationCapability) => Promise<T>): Promise<T>;
+    appendTelemetry(dir: string, event: {
+        type: string;
+        message: string;
+        data?: Record<string, unknown>;
+    }): Promise<unknown>;
+    paneBelongsToTeamTarget(config: SkcTeamConfig, paneId: string): boolean;
+    parseDurationEnv(env: NodeJS.ProcessEnv, name: string, fallback: number): number;
+    parseHeartbeatStaleMs(env: NodeJS.ProcessEnv): number;
+    killWorkerPanes(config: SkcTeamConfig): void;
+    removeCleanCreatedWorktrees(workers: SkcTeamWorker[]): Promise<void>;
+    readMonitorSnapshot(dir: string): Promise<unknown>;
+    hasPendingIntegration(dir: string, config: SkcTeamConfig, monitor: unknown): Promise<boolean>;
+    writePhase(dir: string, phase: SkcTeamPhase): Promise<void>;
+    readSnapshot(teamName: string, cwd: string, env: NodeJS.ProcessEnv): Promise<SkcTeamSnapshot>;
+}
+export declare function workerLifecycleContext(config: SkcTeamConfig, worker: SkcTeamWorker, cwd: string, env: NodeJS.ProcessEnv): SkcTeamWorkerLifecycleContext;
+export type SkcShutdownAuthority = {
+    state: "proven_absent";
+} | {
+    state: "valid_present";
+} | {
+    state: "invalid_or_unreadable";
+};
+export declare function isSkcShutdownRequestRecord(value: unknown): boolean;
+/** Distinguishes a missing shutdown record from a present JSON `null` or invalid record. */
+export declare function readSkcShutdownAuthority(runtime: SkcTeamWorkerRuntime, filePath: string): Promise<SkcShutdownAuthority>;
+export declare function parseSkcWorkerStatusState(value: unknown): SkcWorkerStatusState;
+export declare function lifecycleStateForWorkerStatus(status: SkcWorkerStatusState): SkcTeamWorkerLifecycleState;
+export declare function readWorkerStatusFile(runtime: SkcTeamWorkerRuntime, dir: string, worker: string): Promise<WorkerStatusFile>;
+export declare function readWorkerLifecycleRecord(runtime: SkcTeamWorkerRuntime, dir: string, worker: SkcTeamWorker): Promise<SkcTeamWorkerLifecycle>;
+export declare function readWorkerLifecycleById(runtime: SkcTeamWorkerRuntime, dir: string, config: SkcTeamConfig): Promise<Record<string, SkcTeamWorkerLifecycle>>;
+export declare function writeWorkerLifecycleRecord(runtime: SkcTeamWorkerRuntime, dir: string, worker: SkcTeamWorker, lifecycleState: SkcTeamWorkerLifecycleState, updates?: Partial<SkcTeamWorkerLifecycle>): Promise<SkcTeamWorkerLifecycle>;
+export declare function writeWorkerLifecycleForConfig(runtime: SkcTeamWorkerRuntime, dir: string, config: SkcTeamConfig, lifecycleState: SkcTeamWorkerLifecycleState, updatesFor?: (worker: SkcTeamWorker) => Partial<SkcTeamWorkerLifecycle>): Promise<Record<string, SkcTeamWorkerLifecycle>>;
+export declare function readSkcWorkerStatus(runtime: SkcTeamWorkerRuntime, teamName: string, worker: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<WorkerStatusFile>;
+export declare function updateSkcWorkerStatus(runtime: SkcTeamWorkerRuntime, teamName: string, worker: string, status: SkcWorkerStatusState, cwd?: string, env?: NodeJS.ProcessEnv, currentTaskId?: string, reason?: string): Promise<WorkerStatusFile>;
+export declare function readSkcWorkerHeartbeat(runtime: SkcTeamWorkerRuntime, teamName: string, worker: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<WorkerHeartbeatFile | null>;
+export declare function updateSkcWorkerHeartbeat(runtime: SkcTeamWorkerRuntime, teamName: string, worker: string, heartbeat: WorkerHeartbeatFile, cwd?: string, env?: NodeJS.ProcessEnv): Promise<WorkerHeartbeatFile>;
+export declare function writeSkcWorkerStartupAck(runtime: SkcTeamWorkerRuntime, teamName: string, worker: string, cwd: string, env: NodeJS.ProcessEnv, input: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function writeSkcShutdownRequest(runtime: SkcTeamWorkerRuntime, teamName: string, worker: string, requestedBy: string, cwd: string | undefined, env: NodeJS.ProcessEnv | undefined, requestId: string, mode?: SkcTeamShutdownMode, requestedAt?: string): Promise<Record<string, unknown>>;
+export declare function readSkcShutdownAck(runtime: SkcTeamWorkerRuntime, teamName: string, worker: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<Record<string, unknown> | null>;
+export declare const SKC_TEAM_CONTINUATION_PROMPT = "Continue only your current claimed SKC team task. Re-read current SKC team state; do not replay prior output; report status.";
+export declare function skcContinuationReservationDigest(reservation: Record<string, unknown>): string;
+export declare function isValidSkcContinuationReservation(value: unknown, incident: string, attempt: number, config: SkcTeamConfig, worker: string, task: SkcTeamTask, claim: SkcTeamTaskClaim, heartbeatAt: string, paneId: string): value is Record<string, unknown>;
+export declare function isValidSkcContinuationOutcome(value: unknown, reservation: Record<string, unknown>, incident: string, attempt: number): value is Record<string, unknown>;
+export declare function reconcileSkcTeamStaleClaims(runtime: SkcTeamWorkerOrchestrationRuntime, teamName: string, dir: string, config: SkcTeamConfig, env: NodeJS.ProcessEnv): Promise<SkcTeamLivenessRecoveryResult>;
+export declare function reconcileSkcTeamStaleClaimsUnlocked(runtime: SkcTeamWorkerOrchestrationRuntime, teamName: string, dir: string, config: SkcTeamConfig, env: NodeJS.ProcessEnv, capability: SkcTeamTaskMutationCapability): Promise<SkcTeamLivenessRecoveryResult>;
+export declare function shutdownSkcTeamWorkers(runtime: SkcTeamWorkerOrchestrationRuntime, teamName: string, cwd: string, env: NodeJS.ProcessEnv): Promise<SkcTeamSnapshot>;