@sayknow-cli/coding-agent 0.4.1 → 0.4.3

package/dist/types/skc-runtime/deep-interview-state.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Pure, dependency-free foundation for deep-interview state shape.
+ *
+ * Ownership boundary (per the approved consensus plan): this leaf module owns the
+ * canonical persisted shape (interview data nested under `state`), durable round
+ * identity/hashing, lossless legacy normalization, and the deep-interview-specific
+ * envelope/round merge used by every writer (`deep-interview-recorder`,
+ * `state-runtime` write/reconcile, seed, and handoff). It MUST NOT import the
+ * active-state, state-writer, CLI runtime, or filesystem so it stays cycle-free and
+ * trivially testable.
+ */
+export type DeepInterviewRoundLifecycle = "answered" | "pending_scoring" | "scored";
+export type DeepInterviewTriggerKind = "A" | "B" | "C" | "D";
+/** `active` triggers must satisfy the bidirectional invariant; disputed/unresolved are exempt with rationale. */
+export type DeepInterviewTriggerStatus = "active" | "disputed" | "unresolved";
+export interface DeepInterviewEstablishedFact {
+    id: string;
+    statement: string;
+    round: number;
+    component?: string;
+    dimension?: string;
+    evidence?: string;
+    disputed: boolean;
+    /**
+     * Resolution pointer for a disputed fact: the id of the fact that replaced it
+     * after the user confirmed a pivot. A disputed fact without `superseded_by`
+     * keeps the deterministic ambiguity floor elevated; setting it releases the
+     * pressure while preserving the contradicted fact for audit.
+     */
+    superseded_by?: string;
+}
+export interface DeepInterviewTriggerMetadata {
+    kind: DeepInterviewTriggerKind;
+    name: string;
+    status: DeepInterviewTriggerStatus;
+    component: string;
+    dimension: string;
+    priorDimensionScore?: number;
+    newDimensionScore?: number;
+    priorAmbiguity?: number;
+    newAmbiguity?: number;
+    evidence?: string;
+    contradictedFactId?: string;
+    /** Required when status is `disputed` or `unresolved` to exempt the invariant. */
+    rationale?: string;
+}
+export interface DeepInterviewRoundRecord {
+    round_key: string;
+    round_id?: string;
+    round: number;
+    question_id?: string;
+    question_text?: string;
+    question_hash: string;
+    answer_hash: string;
+    selected_options?: string[];
+    custom_input?: string;
+    component?: string;
+    dimension?: string;
+    ambiguity_at_ask?: number;
+    lifecycle: DeepInterviewRoundLifecycle;
+    answered_at: string;
+    scored_at?: string;
+    scores?: Record<string, number>;
+    /** Effective ambiguity after the deterministic floor clamp (`max(reported, floor)`). */
+    ambiguity?: number;
+    /** Original LLM-reported ambiguity, preserved for audit when the floor clamped it. */
+    reported_ambiguity?: number;
+    /** Deterministic floor in effect when this round was scored, when it clamped. */
+    ambiguity_floor?: number;
+    triggers?: DeepInterviewTriggerMetadata[];
+}
+export interface DeepInterviewStateEnvelope {
+    threshold?: number;
+    threshold_source?: string;
+    state?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export declare function hashContent(value: string): string;
+export declare function questionHash(questionText: string): string;
+export declare function answerHash(selectedOptions: string[] | undefined, customInput: string | undefined): string;
+/**
+ * Durable round identity. Prefer `interview_id + round_id`; fall back to
+ * `interview_id + round + question.id` when no caller-supplied `round_id` exists.
+ */
+export declare function deriveRoundKey(interviewId: string | undefined, input: {
+    round_id?: string;
+    round: number;
+    questionId?: string;
+}): string;
+/**
+ * Canonicalize a deep-interview envelope: interview data nested under `state`,
+ * legacy flattened fields hoisted in losslessly, transcript duplicates removed
+ * from the top level, and `rounds`/`established_facts` guaranteed to be arrays.
+ *
+ * Idempotent: a canonical envelope is returned unchanged in shape. Preserves all
+ * unknown envelope and nested fields except the envelope-reserved keys that leak
+ * into `state` (see `ENVELOPE_RESERVED_STATE_KEYS`), which are stripped so a
+ * malformed envelope-in-state write cannot permanently nest state. Never mutates
+ * the input.
+ */
+export declare function normalizeDeepInterviewEnvelope(value: unknown): DeepInterviewStateEnvelope;
+/**
+ * Lossless, idempotent merge of two round arrays.
+ *
+ * - Records sharing a durable key (`round_key`, or synthesized from
+ *   `round_id`/`question_id`) merge into one, preferring scored over answered.
+ * - Records without any durable identity are preserved verbatim; an exact
+ *   duplicate is skipped so repeated writes stay idempotent, but distinct records
+ *   are never collapsed.
+ *
+ * Deliberate refinement of the approved plan: rather than mutating opaque legacy
+ * records with synthetic `legacy:<index>` keys, they are preserved verbatim with
+ * exact-duplicate dedupe. This satisfies the plan's intent (lossless, idempotent,
+ * never collapse distinct rounds) without rewriting user-supplied round objects,
+ * and keeps free-form extension preservation intact. Recorder-produced records
+ * always carry a `round_key`, so the synthetic path is unnecessary in practice.
+ */
+export declare function mergeDeepInterviewRounds(existing: readonly Record<string, unknown>[], incoming: readonly Record<string, unknown>[]): Record<string, unknown>[];
+/**
+ * Deep-interview-specific envelope merge. Unlike the generic shallow null-delete
+ * merge, this keeps interview data nested under `state`, never deletes `state`,
+ * and merges `rounds` losslessly by durable key so a partial write (e.g. a
+ * scoring update) cannot drop recorder-written transcript history.
+ */
+export declare function mergeDeepInterviewEnvelope(existing: unknown, incoming: unknown, options?: {
+    replace?: boolean;
+}): DeepInterviewStateEnvelope;
+export declare const DEEP_INTERVIEW_INTENT_CATEGORIES: readonly ["artifact", "surface", "integration", "constraint"];
+export type DeepInterviewIntentCategory = (typeof DEEP_INTERVIEW_INTENT_CATEGORIES)[number];
+/**
+ * User-input fields that legitimately carry prose (goals, prompts, descriptions,
+ * answers). Shell metacharacters (`;`, `|`, `&`, backticks, `$()`) are valid prose
+ * here and must NOT be rejected as structural injection. Structural fields (ids,
+ * categories, hashes) stay strictly validated by their own guards.
+ */
+export declare const DEEP_INTERVIEW_FREETEXT_FIELDS: ReadonlySet<string>;
+/** DoS-prevention character-count caps, matching ask-schema string-length semantics. */
+export declare const MAX_INITIAL_CONTEXT_LENGTH = 50000;
+export declare const MAX_USER_RESPONSE_LENGTH = 10000;
+/** Maximum serialized JavaScript-string length for one LLM-produced structured response. */
+export declare const MAX_DEEP_INTERVIEW_STRUCTURED_RESPONSE_LENGTH = 100000;
+/** Count Unicode code points without allocating an intermediate character array. */
+export declare function deepInterviewCharacterCount(value: string): number;
+export declare function isDeepInterviewFreeTextField(name: string): boolean;
+/**
+ * Assert that one structured deep-interview response is JSON-serializable and
+ * bounded by JavaScript string length. This deliberately does not measure or
+ * cap accumulated persisted interview state.
+ */
+export declare function assertDeepInterviewStructuredResponseWithinLimit(value: unknown): void;
+/**
+ * Assert a free-text input is within its size cap. Never inspects content for shell
+ * metacharacters — free-text fields accept prose verbatim; this only bounds length.
+ */
+export declare function assertDeepInterviewInputWithinLimit(value: string, max: number, fieldName?: string): void;
+/** Validate user-supplied deep-interview prose before an envelope is persisted. */
+export declare function assertDeepInterviewEnvelopeInputLimits(envelope: Record<string, unknown>): void;
+export interface DeepInterviewIntentItem {
+    id: string;
+    category: DeepInterviewIntentCategory;
+    statement: string;
+}
+export interface DeepInterviewIntentManifest {
+    version: 1;
+    items: DeepInterviewIntentItem[];
+    digest: string;
+    confirmation_round: 0;
+    confirmation_answer_hash: string;
+    confirmation_evidence: string;
+}
+export interface DeepInterviewIntentSubstitution {
+    removed_id: string;
+    replacement_ids: string[];
+    rationale: string;
+}
+export interface DeepInterviewIntentReview {
+    version: 1;
+    status: "not_required" | "pending" | "approved";
+    locked_digest: string;
+    observed_digest: string;
+    removed_locked_ids: string[];
+    supporting_substitutions: DeepInterviewIntentSubstitution[];
+    approval_round?: number;
+    answer_hash?: string;
+    user_answer_evidence?: string;
+}
+export declare function isCanonicalDeepInterviewAnswerHash(value: unknown): value is string;
+export declare function deepInterviewIntentManifestDigest(items: readonly DeepInterviewIntentItem[]): string;
+export declare function deepInterviewObservedIntentDigest(ids: readonly string[]): string;
+export declare function createDeepInterviewIntentManifest(items: readonly DeepInterviewIntentItem[], confirmation: {
+    round: 0;
+    answer_hash: string;
+}): DeepInterviewIntentManifest;
+export declare function assertDeepInterviewIntentManifest(value: unknown): asserts value is DeepInterviewIntentManifest;
+export declare function reviewDeepInterviewIntent(locked: DeepInterviewIntentManifest, observedItems: readonly DeepInterviewIntentItem[], input: Omit<DeepInterviewIntentReview, "version" | "locked_digest" | "observed_digest" | "removed_locked_ids">): DeepInterviewIntentReview;
+export declare function assertDeepInterviewIntentReview(value: unknown, locked: DeepInterviewIntentManifest, observedIds: readonly string[], recordedAnswers: readonly {
+    round: unknown;
+    answer_hash: unknown;
+}[]): asserts value is DeepInterviewIntentReview;

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

@@ -0,0 +1,6 @@
+/**
+ * Text rendering for `skc gc` reports. JSON output is produced directly in
+ * `gc-runtime.ts`; this module owns the human-readable grouped report.
+ */
+import type { GcReport } from "./gc-runtime";
+export declare function buildGcReportText(report: GcReport): string;

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

@@ -0,0 +1,143 @@
+/**
+ * `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 GcSessionIndexHealth {
+    status: "healthy" | "corrupt" | "repaired" | "unsupported" | "repair_failed";
+    valid_prefix_seq: number;
+    snapshot_seq?: number;
+    reason?: string;
+    quarantine_path?: string;
+}
+export interface GcReport {
+    dry_run: boolean;
+    operation?: "dry_run" | "prune" | "repair_session_index";
+    stores: Record<GcStore, GcRecord[]>;
+    counts: GcCounts;
+    errors: GcError[];
+    session_index?: GcSessionIndexHealth;
+}
+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,63 @@
+import { type Goal, type GoalProvenance } 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;
+    provenance: Extract<GoalProvenance, {
+        source: "ultragoal";
+    }>;
+    /**
+     * 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;
+    provenance: Extract<GoalProvenance, {
+        source: "ultragoal";
+    }>;
+}>;
+export declare function writePendingGoalModeRequest(input: {
+    cwd: string;
+    objective: string;
+    goalsPath?: string;
+    sessionId?: string | null;
+    provenance?: Extract<GoalProvenance, {
+        source: "ultragoal";
+    }>;
+}): Promise<PendingGoalModeRequest>;
+export declare function writeCurrentSessionGoalModeState(input: {
+    sessionFile?: string | null;
+    objective: string;
+    provenance?: Goal["provenance"];
+}): 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,48 @@
+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";
+/** Result of {@link prepareLaunchWorktree}: the effective working directory, remaining args, and resolved worktree plan. */
+export interface PreparedLaunchWorktree {
+    cwd: string;
+    args: string[];
+    worktree: SkcLaunchWorktreeResult | {
+        enabled: false;
+    };
+}
+export declare function prepareLaunchWorktree(cwd: string, args: string[]): PreparedLaunchWorktree;

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/linux-proc.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared helpers for reading Linux `/proc/<pid>/stat` process start time.
+ *
+ * The `comm` field (field 2, wrapped in parentheses) may itself contain spaces
+ * and parentheses, so the only robust anchor is the *last* `)` in the stat
+ * string. Field 22 (the process start time in clock ticks since boot) is the
+ * 20th whitespace-separated token after that closing paren (index 19).
+ *
+ * Every caller previously parsed this format independently, with subtly
+ * different failure handling. This module fails closed: any malformed input
+ * (missing `)`, non-numeric field 22, unreadable `/proc` file, non-Linux
+ * platform) yields `null` rather than an inconsistent sentinel.
+ */
+/**
+ * Parse field 22 (process start time, in clock ticks since boot) from one
+ * `/proc/<pid>/stat` record. Returns the raw numeric token, or `null` when the
+ * record shape is malformed or field 22 is absent/non-numeric.
+ */
+export declare function parseLinuxProcStartTime(stat: string | null | undefined): string | null;
+/**
+ * Read `/proc/<pid>/stat` synchronously and return the parsed start time.
+ * Returns `null` on non-Linux platforms, unreadable files, or malformed input.
+ */
+export declare function readLinuxProcStartTimeSync(pid: number): string | null;
+/**
+ * Read `/proc/<pid>/stat` asynchronously and return the parsed start time.
+ * Returns `null` on non-Linux platforms, unreadable files, or malformed input.
+ */
+export declare function readLinuxProcStartTime(pid: number): Promise<string | null>;