@gajae-code/coding-agent 0.6.3 → 0.6.5

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 ## [Unreleased]
 
+## [0.6.5] - 2026-06-21
+
+### Changed
+
+- Scoped all GJC workflow state by session ID: skill state, plans, specs, and ledgers now live under per-session `.gjc/_session-{id}/` directories, so concurrent or resumed sessions no longer collide on shared workflow state.
+- Hardened skill-state hooks with a writer revision policy, a force-ask on Stop, HUD reconciliation, and an fd-duplication guard; forced/authoritative state writes now survive corrupt prior state (#950).
+- Migrated the global debug shortcut into the keybinding registry and added `pasteImage` as a single source of truth with default-collision diagnostics (#925, #939).
+- Added safe import of custom skills and MCP servers via `migrate` (#944).
+- Trimmed the bundled agent roster to the four canonical role agents: planner, architect, critic, and executor (#922).
+- Added a research-plan ledger spike (#933).
+
+### Fixed
+
+- Stopped including `bash` in the planning-phase mutation guard. The phase-boundary block (and the always-on `.gjc/**` runtime-owned block) now apply only to the fully-pathed `write`/`edit`/`ast_edit` tools; `bash` is never blocked by any workflow skill (`deep-interview`, `ralplan`, `ultragoal` goal-planning), so read-only shell commands run freely during planning. This reverts the `bash` parity added in 0.6.2; product-code and `.gjc/**` mutation are still gated through the dedicated edit tools (#951).
+- Rejected counterexample-only claims in research-plan regardless of `dropCondition` wording (#942).
+- Bounded computer-use screenshot inline images to avoid oversized payloads.
+- Tolerated missing session env in guard reads (#930).
+
+### Documentation
+
+- Documented standalone MCP boundaries (#923).
+
+## [0.6.4] - 2026-06-20
+
+### Changed
+
+- Added `startup.welcomeBannerMode = "square"` for a square-corner Unicode welcome-logo fallback, and stopped treating Windows Terminal (`WT_SESSION`) as an automatic ASCII downgrade; `auto` now preserves the rounded Unicode logo while `unicode`, `square`, and `ascii` remain explicit overrides.
+
+- Improved image input discoverability by adding an interactive `#paste-image` prompt action and clearer clipboard fallback guidance when no image is available.
+
+- Improved skill migration guidance for users moving custom skills onto the current skill system (#899).
+
+### Fixed
+
+- Fixed native Windows tmux launch and hardened Windows tmux root launch, and resolved follow-up Windows tmux launch and input regressions (#884, #895, #906).
+- Fixed `EXDEV` failures when moving session artifacts across filesystems (cross-device session artifact moves) (#886).
+- Excluded user context files from the project prompt so file-level context filtering no longer leaks user-scoped files into project context (#885).
+- Fixed a bash cancellation descendant-cleanup race so cancellation now waits for child-process cleanup within a bounded stall prompt (#893).
+- Fixed the TUI dropping the first `/goal set <objective>` command from input history: the typed command is now recorded whenever args are supplied, regardless of prior goal-mode state (#910).
+- Fixed Ctrl+Enter/Ctrl+Shift+Enter newline handling in the editor: idle Ctrl+Enter now falls through to newline insertion while keeping Ctrl+Enter as the busy-session follow-up shortcut, and Ctrl+Shift+Enter inserts a newline (#911).
+- Fixed parsing of psmux modified-enter key sequences in the TUI (#918).
+
+### Documentation
+
+- Documented Windows Terminal welcome-logo troubleshooting with Cascadia Mono / Cascadia Mono Nerd Font and the profile `fontFace` setting.
+- Documented CLI `@image` attachments and interactive TUI clipboard image paste fallbacks in the root README.
+
+- Documented lifecycle notification hooks (#903).
+- Added a routed GJC session guide for Clawhip/Hermes/OpenClaw visible routed sessions and linked it from the Hermes docs and operator instructions.
+
 ## [0.6.3] - 2026-06-19
 
 ### Fixed

package/README.md

@@ -11,9 +11,69 @@ Package-specific references:
 - [DEVELOPMENT](./DEVELOPMENT.md)
 - [RenderMermaid guide](../../docs/render-mermaid.md)
 
+## External lifecycle notifications
+
+GJC already exposes public lifecycle events through the extension/hook event contract. External notification integrations for Discord, Hermes, clawhip, or similar channels should be opt-in and subscribe to these events instead of scraping transcripts or logs:
+
+- `turn_end` — a model/tool turn finished. The public payload is `{ type: "turn_end", turnIndex, message, toolResults }`.
+- `agent_end` — the agent loop for a submitted prompt reached a terminal boundary. The public payload is `{ type: "agent_end", messages }`.
+
+Recommended external mapping:
+
+| Notification | Public event | Status guidance |
+|---|---|---|
+| Turn finished | `turn_end` | Use the handler's own sanitized status such as `"finished"`. |
+| Agent stopped/finished | `agent_end` | Treat as terminal for the prompt. |
+| Waiting/blocked/failed | `agent_end` plus a caller-supplied safe summary | Current lifecycle events do not expose a separate structured waiting/blocked reason; inspect only public-safe, integration-owned state. |
+
+Forward only a minimal, caller-sanitized payload. Do not include raw prompts, assistant transcripts, hidden prompts, tool outputs, raw logs, host paths, private config, webhook URLs, channel IDs, tokens, or secrets. A safe notification payload should be built by the extension/hook itself, for example:
+
+```ts
+import type { ExtensionAPI } from "@gajae-code/coding-agent";
+
+type PublicLifecycleNotification = {
+	type: "turn_end" | "agent_end";
+	status: "finished" | "stopped" | "failed" | "blocked" | "waiting";
+	turnIndex?: number;
+	timestamp: string;
+	summary: string;
+};
+
+export default function lifecycleNotifier(pi: ExtensionAPI) {
+	const enabled = process.env.GJC_LIFECYCLE_NOTIFY === "1";
+	if (!enabled) return;
+
+	const send = async (payload: PublicLifecycleNotification) => {
+		// POST to Discord/Hermes/clawhip here. Keep target URLs and channel IDs in
+		// private config or environment variables; never include them in payloads.
+	};
+
+	pi.on("turn_end", event =>
+		send({
+			type: "turn_end",
+			status: "finished",
+			turnIndex: event.turnIndex,
+			timestamp: new Date().toISOString(),
+			summary: "GJC turn finished",
+		}),
+	);
+
+	pi.on("agent_end", () =>
+		send({
+			type: "agent_end",
+			status: "stopped",
+			timestamp: new Date().toISOString(),
+			summary: "GJC prompt reached a terminal lifecycle boundary",
+		}),
+	);
+}
+```
+
+This is the supported repo-native lifecycle notification path. It is not Claude Code hook compatibility, and it remains disabled unless the user configures an extension/hook handler and private delivery target.
+
 ## Memory backends
 
-The agent supports three mutually-exclusive memory backends, selected via the `memory.backend` setting (Settings → Memory tab, or `~/.gjc/config.yml`):
+The agent supports three mutually-exclusive memory backends, selected via the `memory.backend` setting (Settings → Memory tab, or `~/.gjc/agent/config.yml`):
 
 - `off` (default) — no memory subsystem runs.
 - `local` — existing rollout-summarisation pipeline; writes `memory_summary.md` and consolidated artifacts under the agent dir.
@@ -35,3 +95,15 @@ Switching backends mid-session is honoured on the next system-prompt rebuild and
 ## Red-claw TUI theme
 
 The interactive TUI defaults to the bundled `red-claw` crustacean theme for dark terminals and the bundled `blue-crab` theme for light-appearance terminals, with matching welcome/icon assets. Three additional bundled migration themes — `claude-code`, `codex`, and `opencode` — mirror the look of those tools for easy eye-migration and are selectable from Settings or `/theme`. Explicit user theme settings still win; set `theme.dark: red-claw` and `theme.light: blue-crab` in `~/.gjc/agent/config.yml` to pin them.
+
+### Welcome banner fonts on Windows Terminal
+
+The startup logo defaults to rounded Unicode box drawing. Windows Terminal can render it correctly when the selected profile font has the needed box-drawing glyphs; recommended choices are `Cascadia Mono` or `Cascadia Mono Nerd Font`. In Windows Terminal Settings, set the profile font face to one of those fonts, or add it to the profile JSON:
+
+```json
+"font": {
+  "face": "Cascadia Mono"
+}
+```
+
+For terminals or fonts with broken rounded corners, set `startup.welcomeBannerMode` in `~/.gjc/agent/config.yml` to one of `unicode`, `square`, or `ascii`. `square` keeps a Unicode-looking logo using square corners (`┌ ┐ └ ┘`) while `ascii` uses only `+`, `-`, and `|`.

package/dist/types/cli/migrate-cli.d.ts

@@ -0,0 +1,20 @@
+import { 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 declare class MigrateArgsError extends Error {
+}
+/** Expand `all`/repeated `--from`, validate, and return sources in canonical order. */
+export declare function resolveSources(from: string[]): MigrateSource[];
+/** Run the migration and return the report (does not set process.exitCode). */
+export declare function runMigrate(args: MigrateCommandArgs): Promise<MigrateReport>;
+/** CLI entry: run, render, and set the process exit code. */
+export declare function runMigrateCommand(args: MigrateCommandArgs): Promise<void>;

package/dist/types/commands/migrate.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Import MCP servers and skills from other coding agents into GJC.
+ */
+import { Command } from "@gajae-code/utils/cli";
+export default class Migrate extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        from: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            multiple: true;
+            required: true;
+        };
+        project: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
+        force: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
+        "dry-run": import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
+        json: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            char: string;
+            description: string;
+            default: boolean;
+        };
+    };
+    run(): Promise<void>;
+}

package/dist/types/config/keybindings.d.ts

@@ -173,6 +173,10 @@ export declare const KEYBINDINGS: {
         readonly defaultKeys: ["escape", "ctrl+c"];
         readonly description: "Cancel selection";
     };
+    readonly "tui.global.debug": {
+        readonly defaultKeys: "shift+ctrl+d";
+        readonly description: "Toggle debug overlay";
+    };
     readonly "app.interrupt": {
         readonly defaultKeys: "escape";
         readonly description: "Interrupt current operation";

package/dist/types/config/settings-schema.d.ts

@@ -1195,6 +1195,33 @@ export declare const SETTINGS_SCHEMA: {
             readonly description: "Skip welcome screen and startup status messages";
         };
     };
+    readonly "startup.welcomeBannerMode": {
+        readonly type: "enum";
+        readonly values: readonly ["auto", "unicode", "square", "ascii"];
+        readonly default: "auto";
+        readonly ui: {
+            readonly tab: "interaction";
+            readonly label: "Welcome Banner Mode";
+            readonly description: "Logo style for the startup welcome screen";
+            readonly options: readonly [{
+                readonly value: "auto";
+                readonly label: "Auto";
+                readonly description: "Use the rounded Unicode logo";
+            }, {
+                readonly value: "unicode";
+                readonly label: "Unicode";
+                readonly description: "Force the rounded Unicode logo";
+            }, {
+                readonly value: "square";
+                readonly label: "Square Unicode";
+                readonly description: "Force the square-corner Unicode fallback";
+            }, {
+                readonly value: "ascii";
+                readonly label: "ASCII";
+                readonly description: "Force the ASCII-safe logo";
+            }];
+        };
+    };
     readonly "startup.checkUpdate": {
         readonly type: "boolean";
         readonly default: true;

package/dist/types/gjc-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/gjc-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/gjc-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 readUltragoalGjcObjective(cwd: string): Promise<{
+export declare function readUltragoalGjcObjective(cwd: string, sessionId?: string | null): Promise<{
     objective: string;
     goalsPath: string;
 }>;

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

@@ -0,0 +1,59 @@
+export declare const GJC_DIR = ".gjc";
+export declare const GJC_SESSION_PREFIX = "_session-";
+export declare const GJC_SESSION_ACTIVITY_FILE = ".session-activity.json";
+/** Source that produced a resolved GJC session id, for audit/diagnostics. */
+export type GjcSessionSource = "flag" | "payload" | "env" | "latest";
+export interface GjcSessionContext {
+    gjcSessionId: string;
+    sessionRoot: string;
+    source: GjcSessionSource;
+}
+/**
+ * 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 assertNonEmptyGjcSessionId(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 `.gjc/` root (holds shared config; never session-scoped). */
+export declare function gjcRoot(cwd: string): string;
+/** The per-session root directory: `<cwd>/.gjc/_session-{encodedId}`. */
+export declare function sessionRoot(cwd: string, gjcSessionId: string): string;
+/** Directory name (no path) for a session id, e.g. `_session-abc`. */
+export declare function sessionDirName(gjcSessionId: 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, gjcSessionId: string): string;
+export declare function sessionStateDir(cwd: string, gjcSessionId: string): string;
+export declare function sessionSpecsDir(cwd: string, gjcSessionId: string): string;
+export declare function sessionPlansDir(cwd: string, gjcSessionId: string): string;
+export declare function sessionUltragoalDir(cwd: string, gjcSessionId: string): string;
+export declare function sessionAuditDir(cwd: string, gjcSessionId: string): string;
+export declare function sessionReportsDir(cwd: string, gjcSessionId: string): string;
+export declare function sessionLogsDir(cwd: string, gjcSessionId: string): string;
+export declare function sessionRuntimeDir(cwd: string, gjcSessionId: string): string;
+export declare function sessionRlmDir(cwd: string, gjcSessionId: string): string;
+export declare function activeStateDir(cwd: string, gjcSessionId: string): string;
+export declare function activeSnapshotPath(cwd: string, gjcSessionId: string): string;
+export declare function activeEntryPath(cwd: string, gjcSessionId: string, skill: string): string;
+export declare function modeStatePath(cwd: string, gjcSessionId: string, mode: string): string;
+export declare function auditPath(cwd: string, gjcSessionId: string): string;
+export declare function transactionJournalPath(cwd: string, gjcSessionId: string, mutationId: string): string;
+export declare function teamStateRoot(cwd: string, gjcSessionId: string): string;
+export declare function workflowGatePath(cwd: string, gjcSessionId: string, gateId: string): string;
+export declare function harnessStateRoot(cwd: string, gjcSessionId: string): string;
+export declare function coordinatorMcpStateRoot(cwd: string, gjcSessionId: string): string;
+export declare function tmuxRuntimeSessionPath(cwd: string, gjcSessionId: string, slug: string): string;
+export declare function rlmArtifactRoot(cwd: string, gjcSessionId: string, rlmSessionId: string): string;

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

@@ -0,0 +1,47 @@
+import { type GjcSessionContext, type GjcSessionSource } 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 {
+    gjcSessionId: string;
+    source: GjcSessionSource;
+}
+/**
+ * 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 resolveGjcSessionForWrite(cwd: string, sources: SessionIdSources): GjcSessionContext;
+/**
+ * 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 resolveGjcSessionForRead(cwd: string, sources: SessionIdSources): Promise<GjcSessionContext>;
+/**
+ * Scan `.gjc/_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<GjcSessionContext>;
+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, gjcSessionId: string, info: ActivityMarkerInfo): Promise<void>;
+export {};

package/dist/types/gjc-runtime/state-graph.d.ts

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

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

@@ -2,9 +2,9 @@ import { type CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
 /**
  * Native implementation of the `gjc state read|write|clear` command surface.
  *
- * Simple file-receipt operations against `.gjc/state/[sessions/<id>/]<mode>-state.json` and
- * `.gjc/state/[sessions/<id>/]skill-active-state.json`. This is the sanctioned CLI mediator for
- * the mutation-guarded `.gjc/state` ACL — agents call it instead of editing those files directly.
+ * Simple file-receipt operations against session-scoped state under
+ * `.gjc/_session-{id}/state/`. This is the sanctioned CLI mediator for
+ * mutation-guarded GJC 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: CanonicalGjcWorkflowSkill;
-    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/gjc-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/gjc-runtime/state-writer.d.ts

@@ -11,7 +11,7 @@ import { type AuditEntry, type CanonicalGjcWorkflowSkill, 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 `.gjc/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 `.gjc/state/active/<skill>.json` and
- * `.gjc/state/sessions/<id>/active/<skill>.json` are authoritative. The
+ * Active entry files under `.gjc/_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?: CanonicalGjcWorkflowSkill;
     callee?: CanonicalGjcWorkflowSkill;
     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/gjc-runtime/tmux-sessions.d.ts

@@ -32,6 +32,8 @@ export declare function listGjcTmuxSessions(env?: NodeJS.ProcessEnv): GjcTmuxSes
 /** @internal */
 export declare function listTmuxSessionsForGc(env?: NodeJS.ProcessEnv): GjcTmuxSessionsForGc;
 export declare function findGjcTmuxSessionByBranch(branch: string, env?: NodeJS.ProcessEnv, project?: string | null): GjcTmuxSessionStatus | undefined;
+export declare function findGjcTmuxSessionByName(sessionName: string, env?: NodeJS.ProcessEnv): GjcTmuxSessionStatus | undefined;
+export declare function findGjcTmuxSessionByScope(project: string, branch: string | null | undefined, env?: NodeJS.ProcessEnv): GjcTmuxSessionStatus | undefined;
 export declare function statusGjcTmuxSession(sessionName: string, env?: NodeJS.ProcessEnv): GjcTmuxSessionStatus;
 export declare function createGjcTmuxSession(env?: NodeJS.ProcessEnv): GjcTmuxSessionStatus;
 /** @internal */

package/dist/types/gjc-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;
     gjcGoalMode?: UltragoalGjcGoalMode;
+    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/gjc-runtime/workflow-command-ref.d.ts

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

package/dist/types/gjc-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 { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+import { type CanonicalGjcWorkflowSkill } from "../skill-state/canonical-skills";
 export interface WorkflowState {
     id: string;
     initial?: boolean;

package/dist/types/harness-control-plane/storage.d.ts

@@ -29,11 +29,12 @@ export declare class StorageError extends Error {
     readonly code: string;
     constructor(message: string, code: string);
 }
-/** Resolve the harness state root from explicit value, env, or cwd default. */
+/** Resolve the harness state root from explicit value, env, or cwd/session default. */
 export declare function resolveHarnessRoot(opts?: {
     root?: string;
     cwd?: string;
     env?: NodeJS.ProcessEnv;
+    gjcSessionId?: string;
 }): string;
 export declare function assertSafeSessionId(id: string): void;
 export declare function generateSessionId(prefix?: string): string;