@sayknow-cli/coding-agent 0.2.4 → 0.2.5

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

@@ -84,6 +84,8 @@ export declare function ensureDeepInterviewStateShape(value: unknown): DeepInter
 export declare function projectCompactState(value: unknown, options?: {
     lastN?: number;
 }): DeepInterviewCompactState;
+/** Refresh the best-effort HUD cache from persisted deep-interview state. */
+export declare function syncDeepInterviewRecorderHud(cwd: string, statePath: string, sessionId: string | undefined): Promise<void>;
 /** Record an `answered` shell for one round (append-or-merge by durable key). */
 export declare function appendOrMergeDeepInterviewRound(cwd: string, statePath: string, input: DeepInterviewAnswerInput, options?: {
     sessionId?: string;

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

@@ -13,12 +13,12 @@ export interface DeepInterviewCommandResult {
     stdout?: string;
     stderr?: string;
 }
-export declare function deepInterviewStatePath(cwd: string, sessionId: string | undefined): string;
+export declare function deepInterviewStatePath(cwd: string, sessionId?: string): string;
 export interface ResolvedDeepInterviewSpecWriteArgs {
     stage: "final";
     slug: string;
     spec: string;
-    sessionId?: string;
+    sessionId: string;
     json: boolean;
     deliberate: boolean;
     handoff?: "ralplan";

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

@@ -30,7 +30,7 @@ export type CurrentSessionGoalModeWriteResult = {
     sessionFile: string;
 };
 export declare function isUltragoalCreateGoalsInvocation(args: readonly string[]): boolean;
-export declare function readUltragoalSkcObjective(cwd: string): Promise<{
+export declare function readUltragoalSkcObjective(cwd: string, sessionId?: string | null): Promise<{
     objective: string;
     goalsPath: string;
 }>;

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/state-graph.d.ts

@@ -1,4 +1,4 @@
-import type { CanonicalSkcWorkflowSkill } from "../skill-state/active-state";
+import { type CanonicalSkcWorkflowSkill } from "../skill-state/canonical-skills";
 export type StateGraphSkill = CanonicalSkcWorkflowSkill | "all";
 export type StateGraphFormat = "ascii" | "mermaid" | "dot";
 export declare function renderStateGraph(skill: StateGraphSkill, format?: string): string;

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

@@ -2,9 +2,9 @@ import { type CanonicalSkcWorkflowSkill } from "../skill-state/active-state";
 /**
  * Native implementation of the `skc state read|write|clear` command surface.
  *
- * Simple file-receipt operations against `.skc/state/[sessions/<id>/]<mode>-state.json` and
- * `.skc/state/[sessions/<id>/]skill-active-state.json`. This is the sanctioned CLI mediator for
- * the mutation-guarded `.skc/state` ACL — agents call it instead of editing those files directly.
+ * Simple file-receipt operations against session-scoped state under
+ * `.skc/_session-{id}/state/`. This is the sanctioned CLI mediator for
+ * mutation-guarded SKC state — agents call it instead of editing those files directly.
  */
 export interface StateCommandResult {
     status: number;
@@ -24,12 +24,13 @@ export interface StateCommandResult {
 export declare function reconcileWorkflowSkillState(options: {
     cwd: string;
     mode: CanonicalSkcWorkflowSkill;
-    sessionId: string | undefined;
+    sessionId?: string;
     threadId?: string;
     turnId?: string;
     active: boolean;
     phase: string;
     payload: Record<string, unknown>;
+    sourceRevision?: number;
 }): Promise<{
     stateFile: string;
 }>;

package/dist/types/skc-runtime/state-schema.d.ts

@@ -84,6 +84,7 @@ export declare const WorkflowStateEnvelopeSchema: z.ZodObject<{
             computed_at: z.ZodString;
         }, z.core.$loose>>;
     }, z.core.$loose>>;
+    state_revision: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>;
 /**
  * Strict receipt required on WRITE (post checksum-stamping). Anchored to the
@@ -164,6 +165,7 @@ export declare const RequiredOnWriteEnvelopeSchema: z.ZodObject<{
             computed_at: z.ZodString;
         }, z.core.$loose>;
     }, z.core.$loose>;
+    state_revision: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>;
 /** Per-skill mode state consumed by hooks / the mutation guard. */
 export declare const ModeStateSchema: z.ZodObject<{

package/dist/types/skc-runtime/state-writer.d.ts

@@ -11,7 +11,7 @@ import { type AuditEntry, type CanonicalSkcWorkflowSkill, type WorkflowStateMuta
  * supplied mutation context. No lockfiles are used; isolation is by atomic rename,
  * append, O_EXCL creates, conditional deletes, per-entry active-state files,
  * and derived active-state snapshots.
- * Transaction journals are per mutation id under `.skc/state/transactions/`;
+ * Transaction journals are per mutation id under the session state transactions directory;
  * they are recovery evidence only, never global locks or waiters, so stale
  * journals do not block unrelated state reads or writes.
  */
@@ -24,9 +24,14 @@ export interface StateWriterReceiptContext {
     sessionId?: string;
     mutationId?: string;
     nowIso?: string;
+    verb?: string;
+    fromPhase?: string;
+    toPhase?: string;
+    forced?: boolean;
 }
 export interface StateWriterAuditContext {
     cwd?: string;
+    sessionId?: string;
     category: WriterCategory;
     verb: string;
     owner: WorkflowStateMutationOwner;
@@ -52,10 +57,25 @@ export interface WorkflowTransactionJournal {
     paths: string[];
     steps: string[];
 }
+export type StateWritePolicy = "source" | "cache";
+export interface GuardedStateWriterOptions extends StateWriterOptions {
+    policy: StateWritePolicy;
+    expectedRevision?: number;
+    sourceRevision?: number;
+}
+export type GuardedWriteResult = {
+    path: string;
+    written: true;
+} | {
+    path: string;
+    written: false;
+    reason: "stale-skip";
+};
 export interface StateWriterOptions {
     cwd?: string;
     receipt?: StateWriterReceiptContext;
     audit?: StateWriterAuditContext;
+    sourceRevision?: number;
     /**
      * Cross-process lock tuning for read-modify-write paths that route through
      * `withWorkflowStateLock` / `updateJsonAtomic`. Omit for the hardened
@@ -63,6 +83,12 @@ export interface StateWriterOptions {
      */
     lock?: FileLockOptions;
 }
+export declare class StateWriteConflictError extends Error {
+    readonly path: string;
+    readonly expectedRevision: number;
+    readonly persistedRevision: number;
+    constructor(path: string, expectedRevision: number, persistedRevision: number);
+}
 export interface DeleteIfOwnedOptions extends StateWriterOptions {
     predicate?: (current: unknown) => boolean | Promise<boolean>;
 }
@@ -113,6 +139,9 @@ export declare function readExistingStateForMutation(filePath: string): Promise<
 export declare function workflowEnvelopeContentSha256(value: unknown): string;
 export declare function stampWorkflowEnvelopeChecksum<T>(value: T, filePath: string, computedAt?: string): T;
 export declare function detectWorkflowEnvelopeIntegrityMismatch(filePath: string): Promise<WorkflowEnvelopeIntegrityMismatch | undefined>;
+export declare function persistedStateRevision(value: unknown): number;
+export declare function writeGuardedJsonAtomic(targetPath: string, value: unknown, options: GuardedStateWriterOptions): Promise<GuardedWriteResult>;
+export declare function writeGuardedWorkflowEnvelopeAtomic(targetPath: string, value: unknown, options: GuardedStateWriterOptions): Promise<GuardedWriteResult>;
 export declare function writeJsonAtomic(targetPath: string, value: unknown, options?: StateWriterOptions): Promise<string>;
 export declare function writeWorkflowEnvelopeAtomic(targetPath: string, value: unknown, options?: StateWriterOptions): Promise<string>;
 export declare function writeTextAtomic(targetPath: string, text: string, options?: StateWriterOptions): Promise<string>;
@@ -178,8 +207,7 @@ export declare function createJsonNoClobber(targetPath: string, value: unknown,
 export declare function deleteIfOwned(targetPath: string, predicateOrOptions?: ((current: unknown) => boolean | Promise<boolean>) | DeleteIfOwnedOptions): Promise<DeleteResult>;
 export declare function removeFileAudited(targetPath: string, options?: StateWriterOptions): Promise<DeleteResult>;
 /**
- * Active entry files under `.skc/state/active/<skill>.json` and
- * `.skc/state/sessions/<id>/active/<skill>.json` are authoritative. The
+ * Active entry files under `.skc/_session-{id}/state/active/<skill>.json` are authoritative. The
  * adjacent `skill-active-state.json` file is only a derived cache rebuilt from
  * those entries, so concurrent snapshot rebuilds can race without losing any
  * writer's per-skill state.
@@ -196,14 +224,15 @@ export declare function softDelete(targetPath: string, meta: Record<string, unkn
 export declare function hardPruneJson(targetPaths: readonly string[], selector: HardPruneSelector, options?: StateWriterOptions): Promise<string[]>;
 export declare function hardPrune(targets: readonly GenericHardPruneTarget[], selector: GenericHardPruneSelector, options?: StateWriterOptions): Promise<string[]>;
 export declare function forceOverwrite(targetPath: string, rawValue: unknown, options?: ForceOverwriteOptions): Promise<string>;
-export declare function appendAuditEntry(cwd: string, entry: AuditEntry): Promise<string>;
-export declare function readWorkflowTransactionJournal(cwd: string, mutationId: string): Promise<WorkflowTransactionJournal | undefined>;
+export declare function appendAuditEntry(cwd: string, sessionIdOrEntry: string | AuditEntry, maybeEntry?: AuditEntry): Promise<string>;
+export declare function readWorkflowTransactionJournal(cwd: string, sessionId: string, mutationId: string): Promise<WorkflowTransactionJournal | undefined>;
 export declare function beginWorkflowTransactionJournal(input: {
     cwd: string;
+    sessionId: string;
     mutationId: string;
     caller?: CanonicalSkcWorkflowSkill;
     callee?: CanonicalSkcWorkflowSkill;
     paths: string[];
 }): Promise<string>;
-export declare function updateWorkflowTransactionJournal(cwd: string, mutationId: string, patch: Partial<WorkflowTransactionJournal>): Promise<string>;
-export declare function completeWorkflowTransactionJournal(cwd: string, mutationId: string): Promise<void>;
+export declare function updateWorkflowTransactionJournal(cwd: string, sessionId: string, mutationId: string, patch: Partial<WorkflowTransactionJournal>): Promise<string>;
+export declare function completeWorkflowTransactionJournal(cwd: string, sessionId: string, mutationId: string): Promise<void>;

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

@@ -32,6 +32,8 @@ export declare function listSkcTmuxSessions(env?: NodeJS.ProcessEnv): SkcTmuxSes
 /** @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 */

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

@@ -23,6 +23,7 @@ export interface UltragoalPlan {
     goals: UltragoalGoal[];
     createdAt: string;
     updatedAt: string;
+    [key: string]: unknown;
 }
 export type UltragoalReceiptKind = "per-goal" | "final-aggregate";
 export interface UltragoalCompletionVerification {
@@ -79,8 +80,8 @@ interface JsonObject {
     [key: string]: unknown;
 }
 export declare function hashStructuredValue(value: unknown): string;
-export declare function getUltragoalPaths(cwd: string): UltragoalPaths;
-export declare function readUltragoalLedger(cwd: string): Promise<UltragoalLedgerEvent[]>;
+export declare function getUltragoalPaths(cwd: string, sessionId?: string | null): UltragoalPaths;
+export declare function readUltragoalLedger(cwd: string, sessionId?: string | null): Promise<UltragoalLedgerEvent[]>;
 export declare function computeUltragoalPlanGeneration(input: {
     plan: UltragoalPlan;
     ledger: readonly UltragoalLedgerEvent[];
@@ -93,13 +94,14 @@ export declare function computeUltragoalPlanGeneration(input: {
     planGeneration: string;
     basis: UltragoalCompletionVerification["basis"];
 };
-export declare function readUltragoalPlan(cwd: string): Promise<UltragoalPlan | null>;
-export declare function getUltragoalStatus(cwd: string): Promise<UltragoalStatusSummary>;
+export declare function readUltragoalPlan(cwd: string, sessionId?: string | null): Promise<UltragoalPlan | null>;
+export declare function getUltragoalStatus(cwd: string, sessionId?: string | null): Promise<UltragoalStatusSummary>;
 export declare function buildUltragoalHudSummary(summary: UltragoalStatusSummary, latestLedger?: UltragoalLedgerEvent): WorkflowHudSummary;
 export declare function createUltragoalPlan(input: {
     cwd: string;
     brief: string;
     skcGoalMode?: UltragoalSkcGoalMode;
+    sessionId?: string | null;
 }): Promise<UltragoalPlan>;
 export interface UltragoalRunCompletionState {
     requiredGoals: UltragoalGoal[];
@@ -115,6 +117,7 @@ export declare function getUltragoalRunCompletionState(plan: UltragoalPlan, opti
 export declare function startNextUltragoalGoal(input: {
     cwd: string;
     retryFailed?: boolean;
+    sessionId?: string | null;
 }): Promise<{
     plan: UltragoalPlan;
     goal?: UltragoalGoal;

package/dist/types/skc-runtime/workflow-command-ref.d.ts

@@ -1,4 +1,4 @@
-import type { CanonicalSkcWorkflowSkill } from "../skill-state/active-state";
+import { type CanonicalSkcWorkflowSkill } from "../skill-state/canonical-skills";
 export type CommandRefVisibility = "public" | "hidden" | "planned";
 export type CommandRefIncludeWhen = "implemented-only" | "planned";
 export interface CommandRefCommand {

package/dist/types/skc-runtime/workflow-manifest.d.ts

@@ -3,7 +3,7 @@
  * Any JSON manifest projection is derived from this module and must never be
  * hand-edited.
  */
-import type { CanonicalSkcWorkflowSkill } from "../skill-state/active-state";
+import { type CanonicalSkcWorkflowSkill } from "../skill-state/canonical-skills";
 export interface WorkflowState {
     id: string;
     initial?: boolean;

package/dist/types/skill-state/active-state.d.ts

@@ -1,7 +1,7 @@
+import { CANONICAL_SKC_WORKFLOW_SKILLS, type CanonicalSkcWorkflowSkill } from "./canonical-skills";
 import type { WorkflowStateReceipt } from "./workflow-state-contract";
 export declare const SKILL_ACTIVE_STATE_FILE = "skill-active-state.json";
-export declare const CANONICAL_SKC_WORKFLOW_SKILLS: readonly ["deep-interview", "ralplan", "ultragoal", "team"];
-export type CanonicalSkcWorkflowSkill = (typeof CANONICAL_SKC_WORKFLOW_SKILLS)[number];
+export { CANONICAL_SKC_WORKFLOW_SKILLS, type CanonicalSkcWorkflowSkill };
 export type WorkflowHudSeverity = "info" | "warning" | "blocked" | "error" | "success";
 export interface WorkflowHudChip {
     label: string;
@@ -44,6 +44,7 @@ export interface SkillActiveEntry {
     handoff_to?: string;
     handoff_at?: string;
     active_subskills?: ActiveSubskillEntry[];
+    source_state_revision?: number;
 }
 export interface SkillActiveState {
     version?: number;
@@ -65,7 +66,7 @@ export interface SkillActiveState {
 }
 export interface SkillActiveStatePaths {
     rootPath: string;
-    sessionPath?: string;
+    sessionPath: string;
 }
 export interface SyncSkillActiveStateOptions {
     cwd: string;
@@ -83,6 +84,7 @@ export interface SyncSkillActiveStateOptions {
     handoff_to?: string;
     handoff_at?: string;
     active_subskills?: ActiveSubskillEntry[];
+    sourceRevision?: number;
 }
 export declare function normalizeWorkflowHudSummary(raw: unknown): WorkflowHudSummary | undefined;
 export declare function isCanonicalSkcWorkflowSkill(skill: string): skill is CanonicalSkcWorkflowSkill;
@@ -102,13 +104,6 @@ export interface ApplyHandoffOptions {
     strict?: boolean;
 }
 /**
- * Atomically apply a workflow-skill handoff to both the session-scoped and
- * root `skill-active-state.json` files in a single write per file.
- *
- * Write order: **session first, root last**. The session file is the
- * source of truth for HUD; the root aggregate must never lead the session
- * during a handoff window. Each file is rewritten once with caller demoted
- * to `active:false` (preserving `handoff_to`/`handoff_at` lineage) and
- * callee promoted to `active:true` (with `handoff_from`/`handoff_at`).
+ * Atomically apply a workflow-skill handoff to the session-scoped active state.
  */
 export declare function applyHandoffToActiveState(options: ApplyHandoffOptions): Promise<void>;

package/dist/types/skill-state/canonical-skills.d.ts

@@ -0,0 +1,3 @@
+/** Native-free canonical SKC workflow skill identifiers. */
+export declare const CANONICAL_SKC_WORKFLOW_SKILLS: readonly ["deep-interview", "ralplan", "ultragoal", "team"];
+export type CanonicalSkcWorkflowSkill = (typeof CANONICAL_SKC_WORKFLOW_SKILLS)[number];

package/dist/types/skill-state/deep-interview-mutation-guard.d.ts

@@ -1,6 +1,8 @@
 import type { AgentTool } from "@sayknow-cli/agent-core";
 export declare const DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE = "Deep-interview phase boundary: continue gathering context/questions/risks and emit a handoff/spec before code edits. Mutation tools and patch execution are blocked while deep-interview is active; finalize specs through `skc deep-interview --write --stage final` or hand off to an execution phase.";
 export declare const WORKFLOW_STATE_MUTATION_BLOCK_MESSAGE = ".skc workflow state and artifacts are runtime-owned. Agent mutation tools cannot edit `.skc/**`; use the sanctioned `skc` CLI instead.";
+export declare const RALPLAN_MUTATION_BLOCK_MESSAGE = "Ralplan planning phase boundary: keep refining the consensus plan and persist plan artifacts through `skc ralplan --write` (stage scratch files under a temp dir if needed). Product-code mutation tools and patch execution are blocked while ralplan is active; mutate only after the plan is approved and execution begins.";
+export declare const ULTRAGOAL_GOAL_PLANNING_MUTATION_BLOCK_MESSAGE = "Ultragoal goal-planning phase boundary: finish goal planning and record goals through `skc ultragoal` before editing code. Product-code mutation tools and patch execution are blocked until goal planning completes and execution begins.";
 type ToolWithEditMode = AgentTool & {
     mode?: unknown;
     customWireName?: unknown;
@@ -30,4 +32,7 @@ export declare function assertDeepInterviewMutationRawPathsAllowed(input: {
 }): Promise<void>;
 export declare function getDeepInterviewMutationDecision(input: DeepInterviewMutationGuardInput): Promise<DeepInterviewMutationDecision>;
 export declare function assertDeepInterviewMutationAllowed(input: DeepInterviewMutationGuardInput): Promise<void>;
+export declare const getWorkflowMutationDecision: typeof getDeepInterviewMutationDecision;
+export declare const assertWorkflowMutationAllowed: typeof assertDeepInterviewMutationAllowed;
+export declare const assertWorkflowMutationRawPathsAllowed: typeof assertDeepInterviewMutationRawPathsAllowed;
 export {};

package/dist/types/skill-state/workflow-hud.d.ts

@@ -39,6 +39,8 @@ interface UltragoalHudState extends WorkflowGateHudState {
         event?: string;
         goalId?: string;
         timestamp?: string;
+        kind?: string;
+        evidence?: string;
     };
     updatedAt?: string;
 }

package/dist/types/task/spawn-gate.d.ts

@@ -1,6 +1,6 @@
 /** The hard, locked batch threshold enforced by the runtime gate. */
 export declare const DEFAULT_SPAWN_THRESHOLD = 4;
-/** The justification a large batch or reviewer-spawned explorer must supply to pass the hard gate. */
+/** The justification a large batch must supply to pass the hard gate. */
 export interface SpawnPlanReceipt {
     whyParallel: string;
     whyNotLocal: string;
@@ -14,14 +14,6 @@ export interface SpawnGateRequest {
     /** The spawn-plan receipt, when provided. */
     plan?: SpawnPlanReceipt;
 }
-export interface ReviewerExploreGateRequest {
-    /** Agent type/name doing the spawning, when known. */
-    spawningAgentType?: string | null;
-    /** Target agent type/name requested by the task call. */
-    targetAgent: string;
-    /** The spawn-plan receipt, when provided. */
-    plan?: SpawnPlanReceipt;
-}
 export type SpawnGateOutcome = "allowed" | "rejected";
 export interface SpawnGateDecision {
     outcome: SpawnGateOutcome;
@@ -35,4 +27,3 @@ export interface SpawnGateDecision {
 export declare function findMissingPlanFields(plan: SpawnPlanReceipt | undefined): string[];
 export declare function decide(childCount: number, threshold: number, plan: SpawnPlanReceipt | undefined): SpawnGateDecision;
 export declare function evaluateSpawnGate(request: SpawnGateRequest): SpawnGateDecision;
-export declare function evaluateReviewerExploreGate(request: ReviewerExploreGateRequest): SpawnGateDecision;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/coding-agent",
-	"version": "0.2.4",
+	"version": "0.2.5",
 	"description": "Sayknow-CLI CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/jaybeyond/Sayknow_CLI",
 	"author": "jaybeyond",
@@ -51,12 +51,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@sayknow-cli/stats": "0.2.4",
-		"@sayknow-cli/agent-core": "0.2.4",
-		"@sayknow-cli/ai": "0.2.4",
-		"@sayknow-cli/natives": "0.2.4",
-		"@sayknow-cli/tui": "0.2.4",
-		"@sayknow-cli/utils": "0.2.4",
+		"@sayknow-cli/stats": "0.2.5",
+		"@sayknow-cli/agent-core": "0.2.5",
+		"@sayknow-cli/ai": "0.2.5",
+		"@sayknow-cli/natives": "0.2.5",
+		"@sayknow-cli/tui": "0.2.5",
+		"@sayknow-cli/utils": "0.2.5",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/scripts/build-binary.ts

@@ -5,12 +5,6 @@ import * as path from "node:path";
 const packageDir = path.join(import.meta.dir, "..");
 const outputPath = path.join(packageDir, "dist", "skc");
 const nativeDir = path.join(packageDir, "..", "natives", "native");
-// Lazy native tokenizer entrypoint. `agent-core/compaction` loads this from
-// the explicit native entrypoint instead of a package-name dynamic require of
-// `@sayknow-cli/natives`, because those fail inside Bun standalone `$bunfs`.
-// Listing the module here makes the absolute target path exist in the compiled
-// bunfs.
-const nativeTokenizerEntrypoint = "../natives/native/index.js";
 
 function shouldAdhocSignDarwinBinary(): boolean {
 	return process.platform === "darwin";
@@ -72,7 +66,6 @@ async function main(): Promise<void> {
 					"../stats/src/sync-worker.ts",
 					"./src/tools/browser/tab-worker-entry.ts",
 					"./src/eval/js/worker-entry.ts",
-					nativeTokenizerEntrypoint,
 					"--outfile",
 					"dist/skc",
 				],

package/src/cli/migrate-cli.ts

@@ -0,0 +1,106 @@
+/**
+ * `skc migrate` — import MCP servers and skills from other coding agents.
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+import { getAgentDir, getMCPConfigPath, getProjectAgentDir, getProjectDir } from "@sayknow-cli/utils";
+import { planMigration } from "../migrate/action-planner";
+import { getAdapter } from "../migrate/adapters/index";
+import { executeActions } from "../migrate/executor";
+import { buildReport, renderHuman } from "../migrate/report";
+import {
+	type AdapterResult,
+	CANONICAL_SOURCE_ORDER,
+	MIGRATE_SOURCES,
+	type MigrateDestinations,
+	type MigrateReport,
+	type MigrateSource,
+} from "../migrate/types";
+
+export interface MigrateCommandArgs {
+	from: string[];
+	project: boolean;
+	force: boolean;
+	dryRun: boolean;
+	json: boolean;
+	/** Test seam: override home dir for source discovery. */
+	homeDir?: string;
+	/** Test seam: override cwd for project-scope destinations. */
+	cwd?: string;
+}
+
+export class MigrateArgsError extends Error {}
+
+/** Expand `all`/repeated `--from`, validate, and return sources in canonical order. */
+export function resolveSources(from: string[]): MigrateSource[] {
+	if (from.length === 0) {
+		throw new MigrateArgsError("No source selected. Use --from <claude-code|codex|opencode|all> (repeatable).");
+	}
+	const selected = new Set<MigrateSource>();
+	for (const raw of from) {
+		const value = raw.trim().toLowerCase();
+		if (value === "all") {
+			for (const s of MIGRATE_SOURCES) selected.add(s);
+			continue;
+		}
+		if (!(MIGRATE_SOURCES as readonly string[]).includes(value)) {
+			throw new MigrateArgsError(`Unknown source "${raw}". Valid: ${MIGRATE_SOURCES.join(", ")}, all.`);
+		}
+		selected.add(value as MigrateSource);
+	}
+	return CANONICAL_SOURCE_ORDER.filter(s => selected.has(s));
+}
+
+function resolveDestinations(project: boolean, cwd: string): MigrateDestinations {
+	const scope = project ? "project" : "user";
+	const skillsDir = project ? path.join(getProjectAgentDir(cwd), "skills") : path.join(getAgentDir(), "skills");
+	return { mcpConfigPath: getMCPConfigPath(scope, cwd), skillsDir };
+}
+
+/** Run the migration and return the report (does not set process.exitCode). */
+export async function runMigrate(args: MigrateCommandArgs): Promise<MigrateReport> {
+	const sources = resolveSources(args.from);
+	const cwd = args.cwd ?? getProjectDir();
+	const homeDir = args.homeDir ?? os.homedir();
+	const destinations = resolveDestinations(args.project, cwd);
+
+	const results: AdapterResult[] = [];
+	for (const source of sources) {
+		results.push(await getAdapter(source).collect({ homeDir }));
+	}
+
+	const { actions, warnings } = await planMigration({ results, destinations, force: args.force });
+	const finalActions = args.dryRun ? actions : await executeActions(actions);
+
+	return buildReport({
+		actions: finalActions,
+		warnings,
+		sources,
+		destinations,
+		dryRun: args.dryRun,
+		project: args.project,
+		force: args.force,
+	});
+}
+
+/** CLI entry: run, render, and set the process exit code. */
+export async function runMigrateCommand(args: MigrateCommandArgs): Promise<void> {
+	let report: MigrateReport;
+	try {
+		report = await runMigrate(args);
+	} catch (error) {
+		if (error instanceof MigrateArgsError) {
+			process.stderr.write(`${error.message}\n`);
+			process.exitCode = 2;
+			return;
+		}
+		throw error;
+	}
+
+	if (args.json) {
+		process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+	} else {
+		process.stdout.write(`${renderHuman(report)}\n`);
+	}
+	process.exitCode = report.ok ? 0 : 1;
+}