@sayknow-cli/coding-agent 0.3.6 → 0.3.8

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

@@ -0,0 +1,355 @@
+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;
+};
+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;
+    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;
+}
+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>;
+}
+interface WorkerStatusFile {
+    state: SkcWorkerStatusState;
+    current_task_id?: string;
+    reason?: string;
+    updated_at: string;
+}
+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/tmux-common.d.ts

@@ -0,0 +1,104 @@
+import type { ResolvedTmuxBinary } from "./psmux-detect";
+export declare const SKC_DEFAULT_TMUX_SESSION = "sayknow_cli";
+export declare const SKC_TMUX_SESSION_PREFIX = "sayknow_cli_";
+export declare const SKC_TMUX_COMMAND_ENV = "SKC_TMUX_COMMAND";
+export declare const SKC_TMUX_PROFILE_ENV = "SKC_TMUX_PROFILE";
+export declare const SKC_TMUX_MOUSE_ENV = "SKC_MOUSE";
+export declare const SKC_TMUX_PROFILE_OPTION = "@skc-profile";
+export declare const SKC_TMUX_PROFILE_VALUE = "1";
+export declare const SKC_TMUX_BRANCH_OPTION = "@skc-branch";
+export declare const SKC_TMUX_BRANCH_SLUG_OPTION = "@skc-branch-slug";
+export declare const SKC_TMUX_PROJECT_OPTION = "@skc-project";
+export declare const SKC_TMUX_SESSION_ID_OPTION = "@skc-session-id";
+export declare const SKC_TMUX_SESSION_STATE_FILE_OPTION = "@skc-session-state-file";
+export declare const SKC_TMUX_VERSION_OPTION = "@skc-version";
+export declare const SKC_PSMUX_PROFILE_FORCE_ENV = "SKC_PSMUX_PROFILE_FORCE";
+export interface SkcTmuxProfileCommand {
+    description: string;
+    args: string[];
+}
+export interface TmuxCommandResult {
+    exitCode: number | null;
+    stdout?: string;
+    stderr?: string;
+    signalCode?: string | null;
+}
+export type TmuxCommandRunner = (args: string[]) => TmuxCommandResult;
+export declare function envDisabled(value: string | undefined): boolean;
+/**
+ * Resolve the tmux (or tmux-compatible multiplexer) command SKC should invoke.
+ *
+ * This is the shared entry point used by every SKC code path that needs to talk
+ * to a multiplexer: `skc --tmux` planning, `skc session ...`, `skc team ...`,
+ * the lifecycle controller, and the harness resident owner. Routing all of
+ * them through the same resolver means a single `SKC_TMUX_COMMAND` override or
+ * a single Windows psmux / pmux detection wins for the whole process — the
+ * failure mode where `skc --tmux` creates a psmux-backed session and then
+ * `skc session status` fails because it queries literal `tmux` is closed off.
+ *
+ * Explicit `SKC_TMUX_COMMAND` / `SKC_TEAM_TMUX_COMMAND` overrides are honored on
+ * every platform. On native Windows without an override the resolver walks
+ * `psmux`, then `pmux`, then `tmux` and uses the first binary present on PATH.
+ * On POSIX the resolver returns `tmux` (the historical default) and only
+ * falls through to the platform-aware walker if the caller opts in.
+ */
+export declare function resolveSkcTmuxCommand(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;
+export type { PsmuxProbe, ResolvedTmuxBinary, ResolveSkcTmuxBinaryOptions } from "./psmux-detect";
+export { clearPsmuxDetectionCache, detectPsmux, probePsmux, resolveSkcTmuxBinary } from "./psmux-detect";
+/**
+ * Build the exact-session target for tmux *option* commands
+ * (`show-options` / `set-option`) and `display-message -t`.
+ *
+ * Session-scoped commands such as `kill-session` / `attach-session` resolve a
+ * bare exact target (`=NAME`), but tmux 3.6a refuses to resolve a bare `=NAME`
+ * for option/display commands. Appending the empty window separator (`=NAME:`)
+ * keeps the exact-session match while giving tmux the window-qualified target
+ * those commands require. See sayknow-cli#580.
+ */
+export declare function buildSkcTmuxExactOptionTarget(sessionName: string, opts?: {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    binary?: ResolvedTmuxBinary;
+}): string;
+/**
+ * Build the exact-session target for tmux *session-scoped* commands such as
+ * `attach-session` and `kill-session`. Native tmux accepts `=NAME` for an
+ * exact session match, but Windows psmux 3.3.x rejects that target form for
+ * session commands even though the bare `NAME` resolves. Keep native tmux on
+ * exact targets and intentionally use the bare session name for psmux.
+ */
+export declare function buildSkcTmuxExactSessionTarget(sessionName: string, opts?: {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    binary?: ResolvedTmuxBinary;
+}): string;
+export declare const SKC_TMUX_UNTAGGED_REASON = "skc_tmux_session_untagged";
+export declare function buildSkcTmuxUntaggedSessionHint(tmuxCommand: string): string;
+export declare function buildSkcTmuxUntaggedSessionError(sessionName: string, tmuxCommand: string): string;
+export declare function sanitizeTmuxToken(value: string): string;
+export declare function buildSkcTmuxSessionSlug(value: string): string;
+export declare function buildSkcTmuxSessionName(env?: NodeJS.ProcessEnv, context?: {
+    branch?: string | null;
+    now?: number;
+    id?: string;
+}): string;
+export declare function buildSkcTmuxRequiredProfileCommands(target: string, metadata?: {
+    branch?: string | null;
+    branchSlug?: string | null;
+    project?: string | null;
+    sessionId?: string | null;
+    sessionStateFile?: string | null;
+    version?: string | null;
+}): SkcTmuxProfileCommand[];
+export declare function buildSkcTmuxProfileCommands(target: string, env?: NodeJS.ProcessEnv, metadata?: {
+    branch?: string | null;
+    branchSlug?: string | null;
+    project?: string | null;
+    sessionId?: string | null;
+    sessionStateFile?: string | null;
+    version?: string | null;
+}, opts?: {
+    platform?: NodeJS.Platform;
+    tmuxCommand?: string;
+}): SkcTmuxProfileCommand[];
+export declare function normalizeTmuxCreatedAt(raw: string): string;

package/dist/types/skc-runtime/tmux-gc.d.ts

@@ -0,0 +1,7 @@
+/**
+ * GC adapter for skc-tagged tmux sessions. Destructive cleanup is authorized
+ * only for detached pane-less sessions whose exact runtime marker revalidates a
+ * terminal state. Project/branch/orphan heuristics are discovery signals only.
+ */
+import type { GcStoreAdapter } from "./gc-runtime";
+export declare const tmuxSessionsGcAdapter: GcStoreAdapter;

package/dist/types/skc-runtime/tmux-sessions.d.ts

@@ -0,0 +1,62 @@
+export interface SkcTmuxSessionStatus {
+    name: string;
+    attached: boolean;
+    windows: number;
+    panes: number;
+    bindings: string;
+    createdAt: string;
+    branch?: string;
+    branchSlug?: string;
+    project?: string;
+    sessionId?: string;
+    sessionStateFile?: string;
+    version?: string;
+    panePids: number[];
+    profile?: string;
+}
+export interface SkcTmuxSessionTagsForGc {
+    profile?: string;
+    project?: string;
+    branch?: string;
+    branchSlug?: string;
+    sessionId?: string;
+    sessionStateFile?: string;
+    version?: string;
+    createdAt?: string;
+    attached?: boolean;
+    panePids?: number[];
+}
+export interface SkcTmuxSessionsForGc {
+    tagged: SkcTmuxSessionStatus[];
+    untagged: SkcTmuxSessionStatus[];
+}
+export declare function listSkcTmuxSessions(env?: NodeJS.ProcessEnv): SkcTmuxSessionStatus[];
+/** @internal */
+export declare function listTmuxSessionsForGc(env?: NodeJS.ProcessEnv): SkcTmuxSessionsForGc;
+export declare function findSkcTmuxSessionByBranch(branch: string, env?: NodeJS.ProcessEnv, project?: string | null): SkcTmuxSessionStatus | undefined;
+export declare function findSkcTmuxSessionByName(sessionName: string, env?: NodeJS.ProcessEnv): SkcTmuxSessionStatus | undefined;
+export declare function findSkcTmuxSessionByScope(project: string, branch: string | null | undefined, env?: NodeJS.ProcessEnv): SkcTmuxSessionStatus | undefined;
+export declare function statusSkcTmuxSession(sessionName: string, env?: NodeJS.ProcessEnv): SkcTmuxSessionStatus;
+export declare function createSkcTmuxSession(env?: NodeJS.ProcessEnv): SkcTmuxSessionStatus;
+/** @internal */
+export declare function readTmuxSessionTagsForGc(sessionName: string, env?: NodeJS.ProcessEnv): SkcTmuxSessionTagsForGc;
+export declare function removeSkcTmuxSession(sessionName: string, env?: NodeJS.ProcessEnv): SkcTmuxSessionStatus;
+/**
+ * Force-close a SKC-managed tmux session, even if a live pane is attached.
+ *
+ * This is the lifecycle-control counterpart to {@link removeSkcTmuxSession}: it
+ * intentionally does NOT refuse live/attached panes (hard-kill is the contract),
+ * but it keeps every safety check so it can only ever kill a genuinely
+ * SKC-managed session:
+ * - re-reads the exact tmux profile immediately before kill (never a non-SKC
+ *   session, even one that collides by name);
+ * - when `expectedSessionId` is given, requires the `@skc-session-id` tag match;
+ * - when `expectedStateFile` is given, requires the `@skc-session-state-file`
+ *   tag match.
+ *
+ * Returns the prior status (for audit). Throws a tagged error otherwise:
+ * `skc_tmux_session_not_found`, `skc_tmux_session_not_managed`,
+ * `skc_tmux_session_id_mismatch`, or `skc_tmux_session_state_file_mismatch`.
+ */
+export declare function forceCloseSkcTmuxSession(sessionName: string, env?: NodeJS.ProcessEnv, expectedSessionId?: string, expectedStateFile?: string): SkcTmuxSessionStatus;
+export declare function attachSkcTmuxSession(sessionName: string, env?: NodeJS.ProcessEnv): never;

package/dist/types/skc-runtime/ultragoal-guard.d.ts

@@ -0,0 +1,93 @@
+import { type UltragoalGoal, type UltragoalLedgerEvent, type UltragoalNudgeSurface, type UltragoalPlan, type UltragoalReceiptKind } from "./ultragoal-runtime";
+export type UltragoalGuardState = "inactive" | "unrelated_goal" | "active_verified_complete" | "active_missing_receipt" | "active_stale_receipt" | "active_missing_final_receipt" | "active_dirty_quality_gate" | "active_review_blocked_unrecorded" | "active_review_blocked_recorded" | "unreadable_fail_closed";
+export interface UltragoalGuardDiagnostic {
+    state: UltragoalGuardState;
+    message: string;
+    goalId?: string;
+}
+export interface UltragoalAskBlockDiagnostic {
+    active: boolean;
+    reason: string;
+    source: "absent" | "durable_state" | "durable_state_unreadable" | "ledger" | "goals_json";
+    goalsPath?: string;
+    ledgerPath?: string;
+    goalIds?: string[];
+    message: string;
+}
+export interface CurrentGoalLike {
+    objective: string;
+    status?: string;
+}
+export declare function validateCompletionReceipt(input: {
+    plan: UltragoalPlan;
+    ledger: readonly UltragoalLedgerEvent[];
+    goal: UltragoalGoal;
+    receiptKind: UltragoalReceiptKind;
+}): UltragoalGuardDiagnostic;
+export declare function readUltragoalVerificationState(input: {
+    cwd: string;
+    currentGoal?: CurrentGoalLike | null;
+    sessionId?: string | null;
+}): Promise<UltragoalGuardDiagnostic>;
+export declare function verifyUltragoalDurableCompletionState(input: {
+    cwd: string;
+    sessionId?: string | null;
+}): Promise<UltragoalGuardDiagnostic>;
+export declare function isUltragoalAskBlocked(cwd: string, options?: {
+    sessionId?: string | null;
+}): Promise<UltragoalAskBlockDiagnostic>;
+/**
+ * Escalating per-attempt refusal text. Deliberately avoids every
+ * `isUltragoalBypassPrompt` trigger: no `update_goal(`, no "skip/weaken verification",
+ * no "mark ... complete", no "--status complete", and the word "complete" never
+ * appears (so the `goal` ... `complete` proximity rule cannot match).
+ */
+export declare function formatUltragoalNudgeMessage(input: {
+    surface: UltragoalNudgeSurface;
+    attempt: number;
+    budget: number;
+    goalId: string;
+}): string;
+/**
+ * Assert-path entry for the `ask` surface (the ask guard lives in another module).
+ * Resolves the active (leader) Ultragoal session so subagent/headless asks consume
+ * the leader run's budget rather than a fresh child ledger.
+ */
+export declare function consumeUltragoalAskNudge(cwd: string, sessionId?: string | null): Promise<{
+    nudged: true;
+    message: string;
+} | {
+    nudged: false;
+}>;
+export declare function assertCanCompleteCurrentGoal(input: {
+    cwd: string;
+    currentGoal?: CurrentGoalLike | null;
+    sessionId?: string | null;
+}): Promise<void>;
+export declare function isUltragoalBypassPrompt(prompt: string): boolean;
+export interface UltragoalPauseBlockDiagnostic {
+    blocked: boolean;
+    reason: string;
+}
+/**
+ * While an Ultragoal run is active, `goal({"op":"pause"})` is only allowed when the
+ * current durable Ultragoal state is readable and the latest durable ledger event
+ * classifies the current blocker as `human_blocked`. Resolvable blockers must be
+ * worked, not parked. Reads fail closed so unreadable durable state or ledger data
+ * blocks pause rather than silently allowing a give-up.
+ */
+export declare function isUltragoalPauseBlocked(cwd: string): Promise<UltragoalPauseBlockDiagnostic>;
+export declare function assertUltragoalPauseAllowed(cwd: string): Promise<void>;
+/**
+ * Guard `goal({"op":"drop"})` during an active Ultragoal run. A *real give-up* (an
+ * aggregate run still mid-flight with incomplete required stories) is nudged while
+ * budget remains; once exhausted it falls through to today's drop behavior. Legitimate
+ * aggregate-reset drops — no durable run, unrelated goal, an already dropped/stale
+ * aggregate, or an all-stories-complete run — are never nudged. If durable state
+ * exists but cannot be read to classify the drop, fail closed.
+ */
+export declare function assertUltragoalDropAllowed(input: {
+    cwd: string;
+    currentGoal?: CurrentGoalLike | null;
+    sessionId?: string | null;
+}): Promise<void>;

package/dist/types/skc-runtime/ultragoal-receipt-freshness.d.ts

@@ -0,0 +1,42 @@
+import type { UltragoalCompletionVerification, UltragoalGoal, UltragoalGoalStatus, UltragoalLedgerEvent, UltragoalPlan, UltragoalReceiptKind } from "./ultragoal-runtime";
+export type UltragoalReceiptFreshnessDiagnostic = {
+    state: "inactive" | "unrelated_goal" | "active_verified_complete" | "active_missing_receipt" | "active_stale_receipt" | "active_missing_final_receipt" | "active_dirty_quality_gate" | "active_review_blocked_unrecorded" | "active_review_blocked_recorded" | "unreadable_fail_closed";
+    message: string;
+    goalId?: string;
+};
+export declare function requiredUltragoalGoals(plan: UltragoalPlan): UltragoalGoal[];
+export declare function receiptRelevantGoals(plan: UltragoalPlan, goal: UltragoalGoal, receiptKind: UltragoalReceiptKind): UltragoalGoal[];
+export declare function computeUltragoalPlanGeneration(input: {
+    plan: UltragoalPlan;
+    ledger: readonly UltragoalLedgerEvent[];
+    goal: UltragoalGoal;
+    receiptKind: UltragoalReceiptKind;
+    beforeStatus: UltragoalGoalStatus;
+    excludeEventId?: string;
+    targetGoalUpdatedAt?: string;
+}): {
+    planGeneration: string;
+    basis: UltragoalCompletionVerification["basis"];
+};
+export declare function findLedgerReceiptEvent(ledger: readonly UltragoalLedgerEvent[], receipt: UltragoalCompletionVerification): UltragoalLedgerEvent | null;
+export declare function validateReceiptFreshBase(input: {
+    plan: UltragoalPlan;
+    ledger: readonly UltragoalLedgerEvent[];
+    goal: UltragoalGoal;
+    receipt: UltragoalCompletionVerification;
+    receiptKind: UltragoalReceiptKind;
+}): UltragoalReceiptFreshnessDiagnostic | null;
+export declare function findFreshBatchCloseReceipt(input: {
+    plan: UltragoalPlan;
+    ledger: readonly UltragoalLedgerEvent[];
+    deferredGoal: UltragoalGoal;
+    deferredReceipt: UltragoalCompletionVerification;
+}): UltragoalCompletionVerification | null;
+export declare function validateDeferredMemberReceiptFresh(input: {
+    plan: UltragoalPlan;
+    ledger: readonly UltragoalLedgerEvent[];
+    goal: UltragoalGoal;
+    receipt: UltragoalCompletionVerification;
+    receiptKind: UltragoalReceiptKind;
+    requireClose: boolean;
+}): UltragoalReceiptFreshnessDiagnostic;