@sayknow-cli/coding-agent 0.3.13 → 0.3.16

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

@@ -0,0 +1,134 @@
+/**
+ * `skc gc` runtime — a global, liveness-only, dry-run-by-default garbage
+ * collector for stale SKC session/PID records.
+ *
+ * Design (see .skc/plans/ralplan/2026-06-13-1347-954f/pending-approval.md):
+ * - This module is an ORCHESTRATOR only. It owns the shared PID probe, the
+ *   report/exit-code policy, and text/JSON rendering. It must NOT parse private
+ *   store layouts directly; every store is reached through an injectable
+ *   `GcStoreAdapter` that lives next to its store owner.
+ * - Liveness-only and fail-closed: only `ESRCH` (no such process) is `dead`
+ *   (removable). `process.kill(pid, 0)` success, `EPERM`, and any unknown probe
+ *   error all mean KEEP — a live process is never signalled or killed.
+ * - Dry-run by default: nothing is deleted unless `--prune`/`--force`.
+ */
+export type GcStore = "harness_leases" | "team_workers" | "file_locks" | "tmux_sessions" | "registry_entries";
+export declare const GC_STORES: readonly GcStore[];
+/** Why a probed pid is kept instead of treated as dead. */
+export type GcPidKeepReason = "alive" | "eperm" | "unknown";
+export interface GcPidProbeResult {
+    /** `dead` only on ESRCH; `keep` for alive/eperm/unknown (fail-closed). */
+    status: "dead" | "keep";
+    reason?: GcPidKeepReason;
+    error?: string;
+}
+/** Single shared liveness contract threaded through every classifier + prune path. */
+export type GcPidProbe = (pid: number) => GcPidProbeResult;
+export type GcPidStatus = "dead" | "alive" | "eperm" | "unknown" | "none";
+export type GcAction = "none" | "would_remove" | "removed" | "remove_failed" | "skipped";
+export interface GcRecord {
+    store: GcStore;
+    /** Stable identifier: session id, lock dir path, worker id, tmux name, registry session id. */
+    id: string;
+    path?: string;
+    root?: string;
+    pid?: number;
+    pid_status?: GcPidStatus;
+    /** Store-specific classification label (e.g. "dead", "live", "unclassified", "terminal_lifecycle"). */
+    status: string;
+    stale: boolean;
+    removable: boolean;
+    action: GcAction;
+    reason: string;
+    detail?: string;
+    error?: string;
+    removed?: boolean;
+}
+export interface GcError {
+    store: GcStore;
+    scope: string;
+    message: string;
+}
+export interface GcCollectResult {
+    records: GcRecord[];
+    errors: GcError[];
+}
+export interface GcPruneOutcome {
+    removed: boolean;
+    error?: string;
+    /** Set when a removable record was skipped at prune time (e.g. TOCTOU became live). */
+    skipped?: string;
+}
+export interface GcContext {
+    probe: GcPidProbe;
+    force: boolean;
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+}
+/**
+ * A store-owned GC adapter. `collect` discovers + classifies (using the shared
+ * probe) without mutating anything. `prune` removes a single record, and MUST
+ * re-validate / re-probe immediately before any destructive action.
+ */
+export interface GcStoreAdapter {
+    store: GcStore;
+    collect(ctx: GcContext): Promise<GcCollectResult>;
+    prune(record: GcRecord, ctx: GcContext): Promise<GcPruneOutcome>;
+}
+export interface GcCounts {
+    discovered: number;
+    stale: number;
+    alive: number;
+    eperm: number;
+    unknown: number;
+    terminal_lifecycle: number;
+    unclassified: number;
+    would_remove: number;
+    removed: number;
+    failed: number;
+    errors: number;
+    by_store: Record<GcStore, {
+        discovered: number;
+        stale: number;
+        would_remove: number;
+        removed: number;
+        failed: number;
+    }>;
+}
+export interface GcReport {
+    dry_run: boolean;
+    stores: Record<GcStore, GcRecord[]>;
+    counts: GcCounts;
+    errors: GcError[];
+}
+export interface GcRunResult {
+    stdout: string;
+    stderr: string;
+    status: number;
+}
+/**
+ * The shared, fail-closed PID probe. ESRCH => dead/removable; success => alive;
+ * EPERM => kept (owned by another user); any other error => kept as unknown.
+ */
+export declare const gcPidProbe: GcPidProbe;
+/** Map a `GcPidProbe` onto the harness lease probe shape (`"alive"|"dead"|"eperm"`). */
+export declare function gcProbeToLeasePidStatus(probe: GcPidProbe): (pid: number) => "alive" | "dead" | "eperm";
+/** Translate a probe result into a record-friendly pid status label. */
+export declare function gcPidStatusLabel(result: GcPidProbeResult): Exclude<GcPidStatus, "none">;
+/**
+ * Collect every store's records (catching hard discovery errors per adapter),
+ * then optionally prune removable records with per-record revalidation.
+ */
+export declare function collectGcReport(adapters: GcStoreAdapter[], ctx: GcContext, prune: boolean): Promise<GcReport>;
+/**
+ * Exit-code policy:
+ * - usage/parse error => 2
+ * - hard discovery errors => 1 (both modes)
+ * - prune mode with a failed intended removal => 1
+ * - otherwise => 0
+ */
+export declare function computeExitCode(report: GcReport): number;
+export declare function runSkcGcCommand(argv: string[], cwd?: string, env?: NodeJS.ProcessEnv, adapters?: GcStoreAdapter[]): Promise<GcRunResult>;
+export declare function gcHelpText(): string;
+/** Lazily assemble the real store adapters (kept lazy to avoid import cycles). */
+export declare function defaultGcAdapters(): Promise<GcStoreAdapter[]>;

package/dist/types/skc-runtime/goal-mode-request.d.ts

@@ -0,0 +1,53 @@
+import { type Goal } from "../goals/state";
+export declare const SKC_SESSION_FILE_ENV = "SKC_SESSION_FILE";
+export declare const SKC_SESSION_ID_ENV = "SKC_SESSION_ID";
+export declare const SKC_SESSION_CWD_ENV = "SKC_SESSION_CWD";
+declare const REQUEST_VERSION = 1;
+export declare const DEFAULT_ULTRAGOAL_OBJECTIVE = "Complete the durable ultragoal plan in .skc/ultragoal/goals.json, including later accepted/appended stories, under the original brief constraints; use .skc/ultragoal/ledger.jsonl as the audit trail.";
+export interface PendingGoalModeRequest {
+    version: typeof REQUEST_VERSION;
+    kind: "goal_mode_request";
+    source: "ultragoal";
+    objective: string;
+    createdAt: string;
+    goalsPath?: string;
+    /**
+     * Session id that produced this request (from SKC_SESSION_ID). When present,
+     * only the originating session may consume it, so concurrent sessions sharing
+     * the same `.skc` project state never auto-run each other's ultragoal.
+     */
+    sessionId?: string;
+}
+export type CurrentSessionGoalModeWriteResult = {
+    status: "unavailable";
+    reason: "missing_session_file" | "empty_session_file";
+} | {
+    status: "existing_goal";
+    goal: Goal;
+} | {
+    status: "updated";
+    goal: Goal;
+    sessionFile: string;
+};
+export declare function isUltragoalCreateGoalsInvocation(args: readonly string[]): boolean;
+export declare function readUltragoalSkcObjective(cwd: string, sessionId?: string | null): Promise<{
+    objective: string;
+    goalsPath: string;
+}>;
+export declare function writePendingGoalModeRequest(input: {
+    cwd: string;
+    objective: string;
+    goalsPath?: string;
+    sessionId?: string | null;
+}): Promise<PendingGoalModeRequest>;
+export declare function writeCurrentSessionGoalModeState(input: {
+    sessionFile?: string | null;
+    objective: string;
+}): Promise<CurrentSessionGoalModeWriteResult>;
+export declare function consumePendingGoalModeRequest(cwd: string, currentSessionId?: string | null): Promise<PendingGoalModeRequest | null>;
+export declare function buildSkcRuntimeSessionEnv(input: {
+    sessionFile?: string | null;
+    sessionId?: string | null;
+    cwd?: string | null;
+}): Record<string, string>;
+export {};

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

@@ -0,0 +1,78 @@
+import type { Args } from "../cli/args";
+import { buildSkcTmuxExactSessionTarget, buildSkcTmuxProfileCommands, SKC_DEFAULT_TMUX_SESSION, SKC_TMUX_COMMAND_ENV, SKC_TMUX_MOUSE_ENV, SKC_TMUX_PROFILE_ENV, SKC_TMUX_SESSION_PREFIX, type SkcTmuxProfileCommand } from "./tmux-common";
+export { buildSkcTmuxExactSessionTarget, buildSkcTmuxProfileCommands, SKC_DEFAULT_TMUX_SESSION, SKC_TMUX_COMMAND_ENV, SKC_TMUX_MOUSE_ENV, SKC_TMUX_PROFILE_ENV, SKC_TMUX_SESSION_PREFIX, };
+export declare const SKC_TMUX_LAUNCHED_ENV = "SKC_TMUX_LAUNCHED";
+export declare const SKC_LAUNCH_POLICY_ENV = "SKC_LAUNCH_POLICY";
+export declare const SKC_TMUX_WINDOW_LABEL_MAX_WIDTH = 48;
+export declare const SKC_PSMUX_PROFILE_FORCE_ENV = "SKC_PSMUX_PROFILE_FORCE";
+interface TtyState {
+    stdin: boolean;
+    stdout: boolean;
+}
+export interface TmuxLaunchContext {
+    parsed: Args;
+    rawArgs: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    argv?: string[];
+    execPath?: string;
+    platform?: NodeJS.Platform;
+    tty?: TtyState;
+    spawnSync?: TmuxSpawnSync;
+    tmuxAvailable?: boolean;
+    worktreeBranch?: string | null;
+    currentBranch?: string | null;
+    existingBranchSessionName?: string | null;
+    project?: string | null;
+    diagnosticWriter?: (message: string) => void;
+}
+export interface TmuxSpawnResult {
+    exitCode: number | null;
+    signalCode?: string | null;
+    stderr?: string;
+}
+export type TmuxSpawnSync = (command: string, args: string[], options: TmuxSpawnOptions) => TmuxSpawnResult;
+export interface TmuxSpawnOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    stdin: "inherit";
+    stdout: "inherit";
+    stderr: "inherit";
+}
+export interface TmuxLaunchPlan {
+    tmuxCommand: string;
+    sessionName: string;
+    cwd: string;
+    innerCommand: string;
+    newSessionArgs: string[];
+    branch?: string | null;
+    attachSessionName?: string;
+    project?: string | null;
+    sessionId?: string | null;
+    sessionStateFile?: string | null;
+}
+export interface SkcTmuxProfileResult {
+    skipped: boolean;
+    commands: SkcTmuxProfileCommand[];
+    failures: Array<{
+        command: SkcTmuxProfileCommand;
+        stderr?: string;
+    }>;
+}
+export interface SkcTmuxProfileContext {
+    tmuxCommand: string;
+    target: string;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    spawnSync?: TmuxSpawnSync;
+    branch?: string | null;
+    branchSlug?: string | null;
+    project?: string | null;
+    sessionId?: string | null;
+    sessionStateFile?: string | null;
+    version?: string | null;
+}
+export declare function applySkcTmuxProfile(context: SkcTmuxProfileContext): SkcTmuxProfileResult;
+export declare function buildSkcTmuxWindowTitle(cwd: string, branch: string | null | undefined): string;
+export declare function buildDefaultTmuxLaunchPlan(context: TmuxLaunchContext): TmuxLaunchPlan | undefined;
+export declare function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean;

package/dist/types/skc-runtime/launch-worktree.d.ts

@@ -0,0 +1,46 @@
+export type SkcLaunchWorktreeMode = {
+    enabled: false;
+} | {
+    enabled: true;
+    detached: true;
+    name: null;
+} | {
+    enabled: true;
+    detached: false;
+    name: string;
+};
+export interface ParsedLaunchWorktreeMode {
+    mode: SkcLaunchWorktreeMode;
+    remainingArgs: string[];
+}
+export interface SkcLaunchWorktreePlan {
+    enabled: true;
+    repoRoot: string;
+    worktreePath: string;
+    detached: boolean;
+    baseRef: string;
+    branchName: string | null;
+}
+export interface SkcLaunchWorktreeResult extends SkcLaunchWorktreePlan {
+    created: boolean;
+    reused: boolean;
+    createdBranch: boolean;
+    dirty?: boolean;
+}
+export declare function parseLaunchWorktreeMode(args: string[]): ParsedLaunchWorktreeMode;
+export declare function planLaunchWorktree(cwd: string, mode: SkcLaunchWorktreeMode): SkcLaunchWorktreePlan | {
+    enabled: false;
+};
+export declare function ensureLaunchWorktree(plan: SkcLaunchWorktreePlan | {
+    enabled: false;
+}): SkcLaunchWorktreeResult | {
+    enabled: false;
+};
+export declare function ensureReusableNodeModules(sourceRoot: string, worktreePath: string): "symlink" | "present" | "missing";
+export declare function prepareLaunchWorktree(cwd: string, args: string[]): {
+    cwd: string;
+    args: string[];
+    worktree: SkcLaunchWorktreeResult | {
+        enabled: false;
+    };
+};

package/dist/types/skc-runtime/ledger-event-renderer.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Pure parse + summarize for ledger-backed skill observability.
+ *
+ * Workflow progress for ultragoal/ralplan cannot be observed via subagent tool
+ * events (those skills persist through `bash`-backed `skc` CLI calls whose tool
+ * `details` carry no structured payload). The durable source of truth is the
+ * append-only ledgers:
+ *   - ultragoal: `.skc/ultragoal/ledger.jsonl`
+ *   - ralplan:   `.skc/plans/ralplan/<run-id>/index.jsonl`
+ *
+ * This module is I/O-free: callers read the files and pass lines or already-parsed
+ * rows. It feeds the compact HUD chip builders in `skill-state/workflow-hud.ts`
+ * via the runtime sync paths. Display-string helpers stay theme-free.
+ */
+/** Minimal projection of an ultragoal ledger row used for the HUD chip. */
+export interface UltragoalLedgerEventLite {
+    /** Normalized from the row's `event` field, or `type` for reconcile rows. */
+    event: string;
+    goalId?: string;
+    status?: string;
+    timestamp?: string;
+}
+/**
+ * Coerce an already-parsed ledger row into the lite shape. Accepts both the
+ * `event`-keyed vocabulary (plan_created, goal_started, goal_checkpointed,
+ * steering_accepted/rejected, review_blockers_recorded) and the `type`-keyed
+ * reconcile-failure row (`type: "reconcile_failed"`). Returns undefined when no
+ * event/type discriminator is present.
+ */
+export declare function coerceUltragoalLedgerEvent(row: Record<string, unknown>): UltragoalLedgerEventLite | undefined;
+/** Parse a single ultragoal ledger JSONL line; undefined for blank/malformed lines. */
+export declare function parseUltragoalLedgerLine(line: string): UltragoalLedgerEventLite | undefined;
+/** The most recent event, or undefined when the ledger is empty. */
+export declare function latestUltragoalLedgerEvent(events: readonly UltragoalLedgerEventLite[]): UltragoalLedgerEventLite | undefined;
+/**
+ * Best-effort latest event from raw ledger text: parses line-by-line and skips
+ * blank/malformed rows so a torn or hand-edited ledger never throws on the HUD
+ * path. Strict receipt consumers should keep using the validating reader.
+ */
+export declare function latestUltragoalLedgerEventFromText(text: string): UltragoalLedgerEventLite | undefined;
+/** Minimal projection of a ralplan `index.jsonl` row. */
+export interface RalplanIndexRow {
+    stage: string;
+    stageN?: number;
+}
+/** Parse a single ralplan index JSONL line; undefined for blank/malformed lines. */
+export declare function parseRalplanIndexLine(line: string): RalplanIndexRow | undefined;
+export interface RalplanIndexSummary {
+    /** Number of consensus iterations (planner/revision boundaries), >= 0. */
+    iteration: number;
+    /** Stage names present in the current (latest) iteration, in append order. */
+    currentStages: string[];
+}
+/**
+ * Derive iteration count and current-iteration stage presence from index rows.
+ *
+ * `stage_n` is NOT used as the iteration key: it is stored verbatim per row and a
+ * single planner/architect/critic pass can span multiple stage_n values. Instead,
+ * a `planner` or `revision` row opens a new iteration and subsequent rows attach
+ * to it. No verdict is derived here (index rows carry none).
+ */
+export declare function summarizeRalplanIndex(rows: readonly RalplanIndexRow[]): RalplanIndexSummary;
+/**
+ * Compact, theme-free presence string for the ralplan `stages` chip, e.g.
+ * `P·A·C`. Collapses past `cap` with a "… N more" suffix. Returns undefined when
+ * there are no stages.
+ */
+export declare function formatRalplanStagePresence(stages: readonly string[], cap?: number): string | undefined;

package/dist/types/skc-runtime/psmux-detect.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Windows psmux detection and tmux-binary resolution.
+ *
+ * Recent psmux releases (see docs/compatibility.md in the psmux repo) close
+ * the round-trip gap for set-option / show-options user options and the
+ * set-window-option profile values skc emits, which is what unblocks the
+ * native Windows skc --tmux path. This module detects that capability so skc
+ * can pick psmux when tmux is missing on Windows, and so callers can decide
+ * whether to treat a given tmux binary as psmux (affecting e.g. the untagged
+ * diagnostic wording and namespace handling).
+ *
+ * The probe is intentionally lightweight: it runs a single tmux -V (or
+ * --version) once per process and caches the verdict. Cache invalidation
+ * knobs:
+ *   - force: true re-probes on every call (used by tests).
+ *   - SKC_PSMUX_FORCE_DETECT=1 re-probes each call.
+ *   - SKC_PSMUX_DETECTION=off skips probing entirely.
+ */
+export declare const SKC_PSMUX_COMMAND_ENV = "SKC_PSMUX_COMMAND";
+export declare const SKC_PSMUX_DETECTION_ENV = "SKC_PSMUX_DETECTION";
+export declare const SKC_PSMUX_FORCE_DETECT_ENV = "SKC_PSMUX_FORCE_DETECT";
+/** Names that psmux installs as the canonical executable / alias. */
+export declare const PSMUX_BINARY_NAMES: readonly ["psmux", "pmux", "tmux"];
+export type PsmuxSpawnRunner = (command: string, args: string[]) => {
+    exitCode: number | null;
+    stdout?: string;
+    stderr?: string;
+};
+/**
+ * Resolves a tmux-class binary name (e.g. "psmux", "tmux") to an absolute
+ * filesystem path or returns null when the binary cannot be located. The
+ * default implementation uses `Bun.which`; production callers leave it
+ * alone and unit tests inject a stub via `__setBinaryResolverForTests`
+ * so the version-banner probe can be exercised hermetically.
+ */
+export type BinaryResolver = (candidate: string) => string | null;
+/** @internal Test-only seam; production code never calls this. */
+export declare function __setBinaryResolverForTests(resolver: BinaryResolver | null): void;
+export declare function envDisabled(value: string | undefined): boolean;
+/**
+ * Decide whether command resolves to a psmux binary by probing its version
+ * output. The result is cached per process unless force is set or
+ * SKC_PSMUX_FORCE_DETECT=1.
+ */
+export declare function detectPsmux(command: string, options?: {
+    force?: boolean;
+    env?: NodeJS.ProcessEnv;
+    runner?: PsmuxSpawnRunner;
+}): boolean;
+export interface ResolveSkcTmuxBinaryOptions {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    runner?: PsmuxSpawnRunner;
+}
+export interface ResolvedTmuxBinary {
+    command: string;
+    isPsmux: boolean;
+    viaExplicitOverride: boolean;
+}
+/**
+ * Resolve the tmux command SKC should invoke. Honors the existing
+ * SKC_TMUX_COMMAND / SKC_TEAM_TMUX_COMMAND overrides; on Windows when no
+ * override is set, psmux (installed as psmux, pmux, or tmux) is picked
+ * automatically so the default skc --tmux flow lands on a real multiplexer.
+ */
+export declare function resolveSkcTmuxBinary(options?: ResolveSkcTmuxBinaryOptions): ResolvedTmuxBinary;
+/** Test-only helper: drop the in-process detection cache. */
+export declare function clearPsmuxDetectionCache(): void;
+export interface PsmuxProbe {
+    command: string;
+    versionOutput: string;
+    isPsmux: boolean;
+}
+export declare function probePsmux(command: string, options?: {
+    env?: NodeJS.ProcessEnv;
+    runner?: PsmuxSpawnRunner;
+    force?: boolean;
+}): PsmuxProbe;

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

@@ -0,0 +1,26 @@
+/**
+ * Native implementation of `skc ralplan`.
+ *
+ * Two invocation shapes are handled natively:
+ *
+ * 1. **Consensus handoff**: `skc ralplan [--interactive] [--deliberate] [--architect <kind>]
+ *    [--critic <kind>] [--session-id <id>] "<task>"` validates the documented flag surface,
+ *    seeds `.skc/state/ralplan-state.json`, and updates the shared HUD rail via
+ *    `syncSkillActiveState`. The CLI never *runs* the Planner / Architect / Critic loop itself —
+ *    that lives in the bundled `/skill:ralplan` skill — but it accepts every documented flag so
+ *    scripted users see a useful response and the active run is visible to the TUI.
+ *
+ * 2. **Artifact write**: `skc ralplan --write --stage <type> --stage_n <N>
+ *    (--artifact <path-or-string> | --artifact-env SKC_RALPLAN_ARTIFACT)
+ *    [--run-id <id>] [--session-id <id>] [--json]` persists Planner / Architect
+ *    / Critic / revision / post-interview / ADR / final markdown under `.skc/plans/ralplan/<run-id>/`, maintains
+ *    an `index.jsonl` audit log, copies `final` stages to `pending-approval.md`, and advances
+ *    the HUD chip to reflect the latest persisted stage.
+ */
+export interface RalplanCommandResult {
+    status: number;
+    stdout?: string;
+    stderr?: string;
+}
+export declare function isRalplanArtifactWriteInvocation(args: readonly string[]): boolean;
+export declare function runNativeRalplanCommand(args: string[], cwd?: string): Promise<RalplanCommandResult>;

package/dist/types/skc-runtime/restricted-role-agent-bash.d.ts

@@ -0,0 +1,3 @@
+export declare const SKC_RESTRICTED_ROLE_AGENT_BASH_ENV = "SKC_RESTRICTED_ROLE_AGENT_BASH";
+export declare const SKC_RALPLAN_ARTIFACT_ENV = "SKC_RALPLAN_ARTIFACT";
+export declare function isRestrictedRoleAgentBash(): boolean;

package/dist/types/skc-runtime/session-layout.d.ts

@@ -0,0 +1,59 @@
+export declare const SKC_DIR = ".skc";
+export declare const SKC_SESSION_PREFIX = "_session-";
+export declare const SKC_SESSION_ACTIVITY_FILE = ".session-activity.json";
+/** Source that produced a resolved SKC session id, for audit/diagnostics. */
+export type SkcSessionSource = "flag" | "payload" | "env" | "latest";
+export interface SkcSessionContext {
+    skcSessionId: string;
+    sessionRoot: string;
+    source: SkcSessionSource;
+}
+/**
+ * Encode a session id into a single safe path segment. Matches the historical
+ * encoding used across the runtimes so ids round-trip identically:
+ * `encodeURIComponent` plus dot-escaping (dots are legal in filenames but we
+ * avoid `.`/`..` traversal ambiguity).
+ */
+export declare function encodeSessionSegment(value: string): string;
+/** Inverse of {@link encodeSessionSegment}. */
+export declare function decodeSessionSegment(segment: string): string;
+/** Throw when a session id is missing or blank; never let blank suppress callers. */
+export declare function assertNonEmptySkcSessionId(value: string | undefined, source: string): asserts value is string;
+/**
+ * Assert a value is safe to use as a single path segment: non-blank and free of
+ * path separators or `.`/`..` traversal. Use for already-safe identifiers
+ * (skill modes, slugs) where we want identical filenames but fail closed on
+ * traversal rather than silently normalizing out of the intended directory.
+ */
+export declare function assertSafePathComponent(value: string, label: string): void;
+/** The shared `.skc/` root (holds shared config; never session-scoped). */
+export declare function skcRoot(cwd: string): string;
+/** The per-session root directory: `<cwd>/.skc/_session-{encodedId}`. */
+export declare function sessionRoot(cwd: string, skcSessionId: string): string;
+/** Directory name (no path) for a session id, e.g. `_session-abc`. */
+export declare function sessionDirName(skcSessionId: string): string;
+/** Return the decoded session id for a `_session-*` directory name, else undefined. */
+export declare function sessionIdFromDirName(name: string): string | undefined;
+/** Authoritative per-session activity marker path. */
+export declare function sessionActivityPath(cwd: string, skcSessionId: string): string;
+export declare function sessionStateDir(cwd: string, skcSessionId: string): string;
+export declare function sessionSpecsDir(cwd: string, skcSessionId: string): string;
+export declare function sessionPlansDir(cwd: string, skcSessionId: string): string;
+export declare function sessionUltragoalDir(cwd: string, skcSessionId: string): string;
+export declare function sessionAuditDir(cwd: string, skcSessionId: string): string;
+export declare function sessionReportsDir(cwd: string, skcSessionId: string): string;
+export declare function sessionLogsDir(cwd: string, skcSessionId: string): string;
+export declare function sessionRuntimeDir(cwd: string, skcSessionId: string): string;
+export declare function sessionRlmDir(cwd: string, skcSessionId: string): string;
+export declare function activeStateDir(cwd: string, skcSessionId: string): string;
+export declare function activeSnapshotPath(cwd: string, skcSessionId: string): string;
+export declare function activeEntryPath(cwd: string, skcSessionId: string, skill: string): string;
+export declare function modeStatePath(cwd: string, skcSessionId: string, mode: string): string;
+export declare function auditPath(cwd: string, skcSessionId: string): string;
+export declare function transactionJournalPath(cwd: string, skcSessionId: string, mutationId: string): string;
+export declare function teamStateRoot(cwd: string, skcSessionId: string): string;
+export declare function workflowGatePath(cwd: string, skcSessionId: string, gateId: string): string;
+export declare function harnessStateRoot(cwd: string, skcSessionId: string): string;
+export declare function coordinatorMcpStateRoot(cwd: string, skcSessionId: string): string;
+export declare function tmuxRuntimeSessionPath(cwd: string, skcSessionId: string, slug: string): string;
+export declare function rlmArtifactRoot(cwd: string, skcSessionId: string, rlmSessionId: string): string;

package/dist/types/skc-runtime/session-resolution.d.ts

@@ -0,0 +1,47 @@
+import { type SkcSessionContext, type SkcSessionSource } from "./session-layout";
+/** Window within which two activity timestamps are treated as an ambiguous tie. */
+export declare const LATEST_SESSION_TIE_WINDOW_MS = 1000;
+export interface SessionIdSources {
+    /** Raw `--session-id` value: `undefined` = flag absent; `""` = present-but-blank (invalid). */
+    flagValue?: string | undefined;
+    payloadSessionId?: unknown;
+    envSessionId?: string | undefined;
+}
+export declare class SessionResolutionError extends Error {
+    readonly code: "blank_flag" | "no_session" | "ambiguous" | "missing_for_write";
+    constructor(message: string, code: "blank_flag" | "no_session" | "ambiguous" | "missing_for_write");
+}
+interface ResolvedFromSources {
+    skcSessionId: string;
+    source: SkcSessionSource;
+}
+/**
+ * Resolve a session id from explicit sources only (flag -> payload -> env).
+ * Returns `undefined` when none is present. A blank explicit flag throws.
+ */
+export declare function resolveSessionIdFromSources(sources: SessionIdSources): ResolvedFromSources | undefined;
+/** Resolve session context for a WRITE command. Errors when no explicit id is present. */
+export declare function resolveSkcSessionForWrite(cwd: string, sources: SessionIdSources): SkcSessionContext;
+/**
+ * Resolve session context for a READ/STATUS/CLEAR command. Falls back to the
+ * latest active session by activity marker when no explicit id is present.
+ */
+export declare function resolveSkcSessionForRead(cwd: string, sources: SessionIdSources): Promise<SkcSessionContext>;
+/**
+ * Scan `.skc/_session-*` directories and select the most-recently-active one by
+ * its activity marker. Never uses raw directory mtime. Throws on zero candidates
+ * or an ambiguous tie.
+ */
+export declare function detectLatestSession(cwd: string): Promise<SkcSessionContext>;
+export interface ActivityMarkerInfo {
+    writer: string;
+    /** Relative generated path that was just written, for diagnostics. */
+    path?: string;
+}
+/**
+ * Best-effort write of the per-session activity marker. State-command callers
+ * MUST treat a thrown error as a command failure (auto-detect depends on it);
+ * non-critical writers may swallow it.
+ */
+export declare function writeSessionActivityMarker(cwd: string, skcSessionId: string, info: ActivityMarkerInfo): Promise<void>;
+export {};

package/dist/types/skc-runtime/session-state-sidecar.d.ts

@@ -0,0 +1,70 @@
+import { postmortem } from "@sayknow-cli/utils";
+/** Managed tmux owner provenance propagated only to the launched child process. */
+export declare const SKC_TMUX_OWNER_GENERATION_ENV = "SKC_TMUX_OWNER_GENERATION";
+export declare const SKC_TMUX_OWNER_STATE_DIR_ENV = "SKC_TMUX_OWNER_STATE_DIR";
+export declare const SKC_TMUX_OWNER_SERVER_KEY_ENV = "SKC_TMUX_OWNER_SERVER_KEY";
+export declare const SKC_COORDINATOR_SESSION_STATE_FILE_ENV = "SKC_COORDINATOR_SESSION_STATE_FILE";
+export declare const SKC_COORDINATOR_SESSION_ID_ENV = "SKC_COORDINATOR_SESSION_ID";
+export declare const SKC_COORDINATOR_SESSION_BRANCH_ENV = "SKC_COORDINATOR_SESSION_BRANCH";
+export declare const SKC_COORDINATOR_SESSION_LAUNCH_ID_ENV = "SKC_COORDINATOR_SESSION_LAUNCH_ID";
+export declare const SKC_COORDINATOR_SESSION_READINESS_FILE_ENV = "SKC_COORDINATOR_SESSION_READINESS_FILE";
+export type RuntimeInputReadyMarker = Readonly<{
+    schema_version: 1;
+    session_id: string;
+    launch_id: string;
+    state: "ready_for_input";
+    event: "interactive_input_ready";
+    source: "skc_interactive_runtime";
+    ready_for_input: true;
+    created_at: string;
+}>;
+export type RuntimeState = "ready_for_input" | "running" | "needs_user_input" | "completed" | "errored";
+/** Test-only counters for runtime sidecar hot-path assertions. */
+export declare const __sessionStateSidecarPerfCounters: {
+    persistFromEventCalls: number;
+    reset(): void;
+};
+interface RuntimeStateEvent {
+    type: string;
+    messages?: unknown[];
+}
+export interface OwnerTerminalContext {
+    generation: string;
+    stateDir: string;
+    socketKey: string;
+    scope?: string | null;
+    ownerPid?: number | null;
+    ownerName?: string | null;
+    operatorDispatchId?: string | null;
+}
+export interface RuntimeStateContext {
+    sessionId: string;
+    cwd: string;
+    sessionFile?: string | null;
+    branch?: string | null;
+    /** Public-safe owner metadata used to persist the canonical terminal verdict. */
+    ownerTerminal?: OwnerTerminalContext | null;
+    /** Internal fail-closed marker set only when managed owner metadata is malformed or missing. */
+    ownerTerminalMetadataInvalid?: boolean;
+}
+export type TerminalRuntimeStateStatus = {
+    terminal: true;
+    state: "completed" | "errored";
+} | {
+    terminal: false;
+    reason: "missing_state_file" | "invalid_json" | "invalid_state_marker" | "session_id_mismatch" | "cwd_mismatch" | "session_file_mismatch" | "non_terminal_state";
+};
+export declare function persistCoordinatorRuntimeInputReady(): Promise<RuntimeInputReadyMarker | null>;
+export declare function readTerminalRuntimeStateMarker(input: {
+    stateFile?: string | null;
+    sessionId?: string | null;
+    cwd?: string | null;
+    sessionFile?: string | null;
+}): Promise<TerminalRuntimeStateStatus>;
+export declare function stateForEvent(event: RuntimeStateEvent): RuntimeState | null;
+export declare function eventAffectsCoordinatorRuntimeState(event: RuntimeStateEvent): boolean;
+export declare function persistCoordinatorRuntimeStateFromEvent(event: RuntimeStateEvent, context: RuntimeStateContext): Promise<void>;
+export declare function ownerTerminalContextFromEnvironment(): OwnerTerminalContext | "invalid" | null;
+export declare function persistCoordinatorRuntimeStateFromPostmortem(reason: postmortem.Reason, context: RuntimeStateContext): Promise<void>;
+export declare function registerCoordinatorRuntimeStateFinalizer(context: RuntimeStateContext): () => void;
+export {};