trekoon 0.4.2 → 0.4.3

package/src/board/assets/state/store.js

@@ -400,6 +400,9 @@ export function createStore(initialSnapshot, options = {}) {
 
   const boardStateMemo = createBoardStateMemo(deriveBoardState);
 
+  // Direct `model.store` mutations must manually invalidate this memo before
+  // rerendering. Current direct-mutation fields: snapshot, notice, isMutating,
+  // dragFeedback.
   function notify() {
     boardStateMemo.invalidate();
     for (const listener of listeners) {

package/src/board/event-bus.ts

@@ -18,7 +18,9 @@ export type BoardEventListener = (event: BoardEvent) => void;
 
 export interface BoardEventBus {
   publishSnapshotDelta(snapshotDelta: Record<string, unknown>): BoardDeltaEvent;
+  markInProcessWrite(timestamp?: number): void;
   subscribe(listener: BoardEventListener): () => void;
+  readonly lastInProcessWriteAt: number;
   readonly subscriberCount: number;
   close(): void;
 }
@@ -27,6 +29,7 @@ export function createBoardEventBus(): BoardEventBus {
   const listeners = new Set<BoardEventListener>();
   let nextId = 1;
   let closed = false;
+  let lastInProcessWriteAt = 0;
 
   return {
     publishSnapshotDelta(snapshotDelta: Record<string, unknown>): BoardDeltaEvent {
@@ -51,6 +54,9 @@ export function createBoardEventBus(): BoardEventBus {
 
       return event;
     },
+    markInProcessWrite(timestamp = Date.now()): void {
+      lastInProcessWriteAt = timestamp;
+    },
     subscribe(listener: BoardEventListener): () => void {
       if (closed) {
         return () => {};
@@ -64,6 +70,9 @@ export function createBoardEventBus(): BoardEventBus {
     get subscriberCount(): number {
       return listeners.size;
     },
+    get lastInProcessWriteAt(): number {
+      return lastInProcessWriteAt;
+    },
     close(): void {
       closed = true;
       listeners.clear();

package/src/board/routes.ts

@@ -84,7 +84,7 @@ function readCookieToken(request: Request): string | null {
   return null;
 }
 
-function extractToken(request: Request, url: URL): string | null {
+function extractHeaderOrCookieToken(request: Request): string | null {
   const authorization: string | null = request.headers.get("authorization");
   if (authorization?.startsWith("Bearer ")) {
     return authorization.slice("Bearer ".length).trim();
@@ -95,11 +95,6 @@ function extractToken(request: Request, url: URL): string | null {
     return headerToken.trim();
   }
 
-  const queryToken: string | null = url.searchParams.get("token");
-  if (queryToken && queryToken.trim().length > 0) {
-    return queryToken.trim();
-  }
-
   return readCookieToken(request);
 }
 
@@ -108,17 +103,34 @@ function isSqliteBusyMessage(message: string): boolean {
   return normalized.includes("database is locked") || normalized.includes("database schema is locked");
 }
 
-function redactDetailLeaves(value: unknown): unknown {
+const REDACT_DETAILS_MAX_DEPTH = 16;
+
+export function redactDetailLeaves(
+  value: unknown,
+  seen: WeakSet<object> = new WeakSet<object>(),
+  depth = 0,
+): unknown {
   if (typeof value === "string") {
     return redactSensitive(value);
   }
+  if (depth >= REDACT_DETAILS_MAX_DEPTH) {
+    return "[MaxDepth]";
+  }
   if (Array.isArray(value)) {
-    return value.map((item) => redactDetailLeaves(item));
+    if (seen.has(value)) {
+      return "[Circular]";
+    }
+    seen.add(value);
+    return value.map((item) => redactDetailLeaves(item, seen, depth + 1));
   }
   if (value !== null && typeof value === "object") {
+    if (seen.has(value)) {
+      return "[Circular]";
+    }
+    seen.add(value);
     const out: Record<string, unknown> = {};
     for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
-      out[key] = redactDetailLeaves(child);
+      out[redactSensitive(key)] = redactDetailLeaves(child, seen, depth + 1);
     }
     return out;
   }
@@ -202,6 +214,7 @@ function publishSnapshotDeltaIfPresent(
   const delta = readSnapshotDelta(data);
   if (delta) {
     eventBus.publishSnapshotDelta(delta);
+    eventBus.markInProcessWrite();
   }
 }
 
@@ -212,14 +225,10 @@ function formatSseEvent(eventName: string, data: unknown, id?: number): string {
 
 // SSE backpressure thresholds (P1 finding 5).
 // A client that connects but never reads can otherwise grow the per-stream
-// queue without bound — every snapshotDelta the bus publishes is encoded
-// and pushed, retaining the bytes in `controller`'s internal queue. We
-// guard against OOM by tracking unflushed bytes and the time since the
-// consumer last pulled, and tearing the connection down once either limit
-// is exceeded.
-const SSE_MAX_QUEUED_BYTES = 1_000_000; // 1 MB hard cap → drop connection.
-const SSE_COALESCE_BYTES = 256_000;     // 256 KB soft cap → coalesce deltas.
-const SSE_STALL_MS = 30_000;            // 30 s without consumption → drop.
+// queue without bound. The stream controller already exposes queue pressure
+// through `desiredSize`; once it goes negative we stop enqueueing sparse
+// deltas and retain one pending full-snapshot frame for the next drain.
+const SSE_STALL_MS = 30_000; // 30 s without consumption under pressure → drop.
 const SSE_BACKPRESSURE_CHECK_MS = 1_000;
 
 function openSnapshotStream(
@@ -243,19 +252,16 @@ function openSnapshotStream(
   let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
   let backpressureTimer: ReturnType<typeof setInterval> | null = null;
 
-  // Bytes enqueued but not yet consumed via `pull`. Each enqueue adds the
-  // chunk's byte length; each `pull` decrements by the next pending chunk's
-  // size (FIFO; we don't peek into the controller's internal queue).
-  let queuedBytes = 0;
-  const pendingChunkSizes: number[] = [];
   let lastConsumeAt = Date.now();
   let closed = false;
-  // When over the soft threshold we coalesce snapshotDeltas: only the latest
-  // is retained, dropping superseded deltas. The cached delta is flushed
-  // once the queue drains below the soft limit on the next `pull`.
-  let pendingDelta: { id: number; snapshotDelta: Record<string, unknown> } | null = null;
+  let pendingFrame: string | null = null;
+  let onAbort: (() => void) | null = null;
 
   const cleanupTimers = (): void => {
+    if (onAbort) {
+      request.signal.removeEventListener("abort", onAbort);
+      onAbort = null;
+    }
     if (unsubscribe) {
       unsubscribe();
       unsubscribe = null;
@@ -277,22 +283,29 @@ function openSnapshotStream(
           return;
         }
         try {
-          const bytes = encoder.encode(chunk);
-          controller.enqueue(bytes);
-          queuedBytes += bytes.byteLength;
-          pendingChunkSizes.push(bytes.byteLength);
+          controller.enqueue(encoder.encode(chunk));
         } catch {
           // Controller closed; cleanup happens via cancel.
         }
       };
 
-      const flushPendingDelta = (): void => {
-        if (!pendingDelta || closed) {
+      const isBackpressured = (): boolean => (controller.desiredSize ?? 1) < 0;
+
+      const queueFullSnapshot = (id: number): void => {
+        // Sparse per-mutation deltas are not cumulative, so merging them can
+        // silently drop changes. Under backpressure, retain a fresh full
+        // snapshot frame instead; EventSource clients can converge from it
+        // without relying on every skipped delta.
+        pendingFrame = formatSseEvent("snapshot", { snapshot: buildBoardSnapshot(domain) }, id);
+      };
+
+      const flushPendingFrame = (): void => {
+        if (!pendingFrame || closed || isBackpressured()) {
           return;
         }
-        const delta = pendingDelta;
-        pendingDelta = null;
-        enqueueRaw(formatSseEvent("snapshotDelta", { snapshotDelta: delta.snapshotDelta }, delta.id));
+        const frame = pendingFrame;
+        pendingFrame = null;
+        enqueueRaw(frame);
       };
 
       const closeWithError = (reason: string): void => {
@@ -318,22 +331,15 @@ function openSnapshotStream(
         if (closed) {
           return;
         }
-        if (queuedBytes >= SSE_MAX_QUEUED_BYTES) {
-          closeWithError("queued bytes exceeded 1MB hard limit");
+        if (isBackpressured()) {
+          queueFullSnapshot(id);
           return;
         }
-        if (queuedBytes >= SSE_COALESCE_BYTES) {
-          // Slow consumer: coalesce. The board snapshot is cumulative; the
-          // newest delta carries the freshest causally-ordered state for
-          // every entity it touches, so dropping superseded deltas is safe.
-          pendingDelta = { id, snapshotDelta };
+        flushPendingFrame();
+        if (isBackpressured()) {
+          queueFullSnapshot(id);
           return;
         }
-        // Fast path: flush any coalesced delta first to preserve ordering,
-        // then enqueue the new one.
-        if (pendingDelta) {
-          flushPendingDelta();
-        }
         enqueueRaw(formatSseEvent("snapshotDelta", { snapshotDelta }, id));
       };
 
@@ -348,27 +354,26 @@ function openSnapshotStream(
 
       // Heartbeats keep proxies and stale-connection detectors happy.
       heartbeatTimer = setInterval(() => {
+        if ((controller.desiredSize ?? 1) < 0) {
+          return;
+        }
         enqueueRaw(": heartbeat\n\n");
       }, 15000);
 
       // Backpressure watchdog: if the consumer has not pulled within
-      // SSE_STALL_MS while pending data is sitting in the queue, treat the
-      // client as dead and drop the connection so we don't pin memory.
+      // SSE_STALL_MS while the stream is under pressure, close with an
+      // error frame so EventSource reconnects and receives a fresh snapshot.
       backpressureTimer = setInterval(() => {
         if (closed) {
           return;
         }
-        if (queuedBytes >= SSE_MAX_QUEUED_BYTES) {
-          closeWithError("queued bytes exceeded 1MB hard limit");
-          return;
-        }
-        const stalled = queuedBytes > 0 && Date.now() - lastConsumeAt > SSE_STALL_MS;
+        const stalled = (controller.desiredSize ?? 1) < 0 && Date.now() - lastConsumeAt > SSE_STALL_MS;
         if (stalled) {
           closeWithError(`no consumer pull within ${SSE_STALL_MS}ms`);
         }
       }, SSE_BACKPRESSURE_CHECK_MS);
 
-      const onAbort = (): void => {
+      onAbort = (): void => {
         if (closed) {
           return;
         }
@@ -387,17 +392,17 @@ function openSnapshotStream(
       }
       request.signal.addEventListener("abort", onAbort);
     },
-    pull(): void {
-      // A pull means the consumer drained the next chunk from the queue.
-      const consumed = pendingChunkSizes.shift();
-      if (typeof consumed === "number") {
-        queuedBytes = Math.max(0, queuedBytes - consumed);
-      }
+    pull(controller): void {
       lastConsumeAt = Date.now();
-      // Outer-scope flush: re-walk via enqueueRaw on the active controller is
-      // unnecessary because the controller is only valid inside start();
-      // instead the next snapshotDelta arrival will see queuedBytes below the
-      // soft limit and flush pendingDelta automatically.
+      if (pendingFrame && !closed && (controller.desiredSize ?? 1) >= 0) {
+        const frame = pendingFrame;
+        pendingFrame = null;
+        try {
+          controller.enqueue(encoder.encode(frame));
+        } catch {
+          // Controller closed.
+        }
+      }
     },
     cancel(): void {
       closed = true;
@@ -565,35 +570,30 @@ function parseIfMatchHeader(request: Request): number | null {
 
   // RFC 7232 §3.1 allows a strong ETag (`"<value>"`) or a weak ETag
   // (`W/"<value>"`). Trekoon does not differentiate strong from weak
-  // semantics — a millisecond updatedAt is exact either way — so we
+  // semantics — the entity version token is exact either way — so we
   // accept both shapes. The wildcard `*` is intentionally NOT supported:
   // it would mean "any current representation matches" and would defeat
   // the whole purpose of the optimistic-concurrency check, so we surface
   // it as 400 invalid_input below rather than treating it as a no-op.
   const stripped = raw.trim().replace(/^W\//iu, "");
   const trimmed = stripped.replace(/^"+|"+$/g, "");
-  if (trimmed.length === 0) {
-    return null;
-  }
-
-  const parsed = Number(trimmed);
-  if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
+  if (!/^(0|[1-9]\d*)$/u.test(trimmed)) {
     throw new DomainError({
       code: "invalid_input",
       message:
-        "If-Match header must be an integer updatedAt millisecond timestamp (RFC 7232 strong or W/-prefixed weak ETag); the `*` wildcard is not supported",
+        "If-Match header must be a non-negative integer version token (RFC 7232 strong or W/-prefixed weak ETag); the `*` wildcard is not supported",
       details: { header: "If-Match", value: raw },
     });
   }
 
-  return parsed;
+  return Number(trimmed);
 }
 
 interface PreconditionFailedDetails {
   readonly entityKind: "epic" | "task" | "subtask";
   readonly entityId: string;
-  readonly currentUpdatedAt: number;
-  readonly providedUpdatedAt: number;
+  readonly currentVersion: number;
+  readonly providedVersion: number;
 }
 
 function preconditionFailedResponse(details: PreconditionFailedDetails): Response {
@@ -601,12 +601,12 @@ function preconditionFailedResponse(details: PreconditionFailedDetails): Respons
     ok: false,
     error: {
       code: "precondition_failed",
-      message: "If-Match version does not match current updatedAt",
+      message: "If-Match version does not match current version",
       details: {
         entityKind: details.entityKind,
         entityId: details.entityId,
-        currentUpdatedAt: details.currentUpdatedAt,
-        providedUpdatedAt: details.providedUpdatedAt,
+        currentVersion: details.currentVersion,
+        providedVersion: details.providedVersion,
       },
     },
   });
@@ -630,7 +630,18 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
   return async (request: Request): Promise<Response> => {
     const url = new URL(request.url);
     const requestLabel = `${request.method} ${url.pathname}`;
-    const requestToken = extractToken(request, url);
+    if (url.searchParams.has("token")) {
+      return jsonResponse(401, {
+        ok: false,
+        error: {
+          code: "unauthorized",
+          message: "Board API requests must authenticate with the session cookie or authorization header",
+        },
+      });
+    }
+    const requestToken = url.pathname === "/api/snapshot/stream"
+      ? readCookieToken(request)
+      : extractHeaderOrCookieToken(request);
     // Plain `!==` instead of a constant-time compare is a deliberate choice
     // (System Hardening 0.4.2, finding 32). The board server only binds to
     // 127.0.0.1, the session token is a 256-bit cryptographically-random
@@ -1007,14 +1018,14 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
       });
     } catch (error: unknown) {
       // PreconditionFailedError is a typed signal from the *WithIfMatch
-      // CAS variants. It carries the freshly-fetched currentUpdatedAt so
+      // CAS variants. It carries the freshly-fetched currentVersion so
       // the 409 payload is always consistent with the post-rollback state.
       if (error instanceof PreconditionFailedError) {
         return preconditionFailedResponse({
           entityKind: error.entityKind,
           entityId: error.entityId,
-          currentUpdatedAt: error.currentUpdatedAt,
-          providedUpdatedAt: error.providedUpdatedAt,
+          currentVersion: error.currentVersion,
+          providedVersion: error.providedVersion,
         });
       }
 

package/src/board/server.ts

@@ -90,7 +90,7 @@ function isUnavailablePortError(error: unknown): boolean {
 }
 
 function buildBoardSessionCookie(token: string): string {
-  return `trekoon_board_session=${encodeURIComponent(token)}; Path=/; SameSite=Strict; HttpOnly`;
+  return `trekoon_board_session=${encodeURIComponent(token)}; Path=/; Max-Age=86400; SameSite=Strict; HttpOnly`;
 }
 
 function readBoardSessionCookie(request: Request): string | null {
@@ -122,6 +122,13 @@ function isAuthenticatedBoardRequest(request: Request, url: URL, token: string):
   return cookieToken !== null && cookieToken === token;
 }
 
+function buildTokenStrippedLocation(url: URL): string {
+  const redirectUrl = new URL(url);
+  redirectUrl.searchParams.delete("token");
+  const pathname = `/${redirectUrl.pathname.replace(/^\/+/u, "")}`;
+  return `${pathname}${redirectUrl.search}${redirectUrl.hash}`;
+}
+
 function serializeInlineJson(value: unknown): string {
   return JSON.stringify(value)
     .replace(/</g, "\\u003c")
@@ -156,7 +163,7 @@ export function startBoardServer(options: StartBoardServerOptions = {}): BoardSe
   const paths = resolveStoragePaths(cwd);
   const boardRoot: string = paths.boardDir;
   const stateFile: string = resolve(paths.storageDir, BOARD_SERVER_STATE_FILENAME);
-  const token: string = options.token ?? randomBytes(18).toString("hex");
+  const token: string = options.token ?? randomBytes(32).toString("hex");
   const eventBus: BoardEventBus = createBoardEventBus();
   const walWatcher: WalWatcher = startWalWatcher({
     db: database.db,
@@ -195,15 +202,15 @@ export function startBoardServer(options: StartBoardServerOptions = {}): BoardSe
           // and Referer headers free of the secret on the very first
           // navigation, severing the leakage surface that an open URL bar
           // would otherwise expose. The cookie carries auth from here on.
-          const redirectUrl = new URL(url);
-          redirectUrl.searchParams.delete("token");
-          // Preserve the relative location so the redirect works regardless
-          // of how the client reached us (loopback IP vs. localhost name).
-          const location = `${redirectUrl.pathname}${redirectUrl.search}${redirectUrl.hash}`;
+          // Preserve a single-slash relative location so the redirect works
+          // regardless of how the client reached us, without creating a
+          // scheme-relative `//host` Location for odd incoming paths.
+          const location = buildTokenStrippedLocation(url);
           return new Response(null, {
             status: 302,
             headers: {
               ...responseHeaders,
+              "referrer-policy": "no-referrer",
               location: location.length > 0 ? location : "/",
             },
           });

package/src/board/snapshot.ts

@@ -34,6 +34,7 @@ interface BoardSnapshotSubtask {
   readonly owner: string | null;
   readonly createdAt: number;
   readonly updatedAt: number;
+  readonly version: number;
   readonly blockedBy: readonly string[];
   readonly blocks: readonly string[];
   readonly dependencyIds: readonly string[];
@@ -51,6 +52,7 @@ interface BoardSnapshotTask {
   readonly owner: string | null;
   readonly createdAt: number;
   readonly updatedAt: number;
+  readonly version: number;
   readonly blockedBy: readonly string[];
   readonly blocks: readonly string[];
   readonly dependencyIds: readonly string[];
@@ -66,6 +68,7 @@ interface BoardSnapshotEpic {
   readonly status: string;
   readonly createdAt: number;
   readonly updatedAt: number;
+  readonly version: number;
   readonly taskIds: readonly string[];
   readonly counts: FlatCounts;
   readonly searchText: string;
@@ -169,6 +172,7 @@ function mapSnapshotSubtask(subtask: SubtaskRecord, indexes: ReturnType<typeof b
     owner: subtask.owner ?? null,
     createdAt: subtask.createdAt,
     updatedAt: subtask.updatedAt,
+    version: subtask.version,
     blockedBy: indexes.blockedByIdsBySource.get(subtask.id) ?? [],
     blocks: indexes.blocksByTarget.get(subtask.id) ?? [],
     dependencyIds: indexes.dependencyIdsBySource.get(subtask.id) ?? [],
@@ -188,6 +192,7 @@ function mapSnapshotTask(task: TaskRecord, taskSubtasks: readonly BoardSnapshotS
     owner: task.owner ?? null,
     createdAt: task.createdAt,
     updatedAt: task.updatedAt,
+    version: task.version,
     blockedBy: indexes.blockedByIdsBySource.get(task.id) ?? [],
     blocks: indexes.blocksByTarget.get(task.id) ?? [],
     dependencyIds: indexes.dependencyIdsBySource.get(task.id) ?? [],
@@ -205,6 +210,7 @@ function mapSnapshotEpic(epic: EpicRecord, epicTasks: readonly BoardSnapshotTask
     status: epic.status,
     createdAt: epic.createdAt,
     updatedAt: epic.updatedAt,
+    version: epic.version,
     taskIds: epicTasks.map((task) => task.id),
     counts: deriveFlatCounts(epicTasks),
     searchText: [epic.title, epic.description, ...epicTasks.map((task) => task.searchText)].join(" ").toLowerCase(),

package/src/board/wal-watcher.ts

@@ -22,6 +22,8 @@ import { TrackerDomain } from "../domain/tracker-domain";
 import { type BoardEventBus } from "./event-bus";
 import { buildBoardSnapshot, type BoardSnapshot } from "./snapshot";
 
+const IN_PROCESS_WAL_SUPPRESS_MS = 500;
+
 interface CollectionDiff {
   readonly upserted: unknown[];
   readonly deletedIds: string[];
@@ -104,6 +106,17 @@ function diffById(previous: readonly unknown[] | undefined, current: readonly un
   return { upserted, deletedIds };
 }
 
+function readMtime(path: string): number {
+  if (!existsSync(path)) {
+    return 0;
+  }
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
 export interface WalWatcherOptions {
   readonly db: Database;
   readonly databaseFile: string;
@@ -168,11 +181,20 @@ export function startWalWatcher(options: WalWatcherOptions): WalWatcher {
   let debounceTimer: ReturnType<typeof setTimeout> | null = null;
   let closed = false;
   let failures = 0;
+  let lastSuppressedInProcessWriteAt = 0;
 
   function reconcile(): void {
     if (closed) {
       return;
     }
+    const inProcessWriteAt = options.eventBus.lastInProcessWriteAt;
+    if (
+      inProcessWriteAt > lastSuppressedInProcessWriteAt &&
+      Date.now() - inProcessWriteAt <= IN_PROCESS_WAL_SUPPRESS_MS
+    ) {
+      lastSuppressedInProcessWriteAt = inProcessWriteAt;
+      return;
+    }
 
     try {
       const fresh = buildSnapshot(domain);
@@ -235,17 +257,6 @@ export function startWalWatcher(options: WalWatcherOptions): WalWatcher {
   // than spurious watcher fires (e.g. atime-only updates on some filesystems).
   let lastWalMtime: number = readMtime(walFile);
 
-  function readMtime(path: string): number {
-    if (!existsSync(path)) {
-      return 0;
-    }
-    try {
-      return statSync(path).mtimeMs;
-    } catch {
-      return 0;
-    }
-  }
-
   function maybeScheduleReconcile(): void {
     const currentMtime = readMtime(walFile);
     // mtime can equal 0 when the WAL was just checkpointed and removed; treat

package/src/commands/help.ts

@@ -115,13 +115,13 @@ const EPIC_HELP = [
   "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete|progress|export> [options]",
   "",
   "Create:",
-  "  trekoon epic create --title \"...\" --description \"...\" [--status <status>]",
-  "  trekoon epic create --title \"...\" --description \"...\" [--task <spec>] [--subtask <spec>] [--dep <spec>]",
+  "  trekoon --toon epic create --title \"...\" --description \"...\" [--status <status>]",
+  "  trekoon --toon epic create --title \"...\" --description \"...\" [--task <spec>] [--subtask <spec>] [--dep <spec>]",
   "  When the full tree is known, the second form creates everything in one shot",
   "  and returns mappings/counts. Same compact spec grammar as epic expand.",
   "",
   "Expand:",
-  "  trekoon epic expand <epic-id> [--task <spec>] [--subtask <spec>] [--dep <spec>]",
+  "  trekoon --toon epic expand <epic-id> [--task <spec>] [--subtask <spec>] [--dep <spec>]",
   "  --task <temp-key>|<title>|<description>|<status>",
   `  --subtask <parent-ref>|<temp-key>|<title>|<description>|<status>  (${"@"}<temp-key> for new parents)`,
   `  --dep <source-ref>|<depends-on-ref>  (refs can be IDs or ${"@"}<temp-key>)`,
@@ -441,8 +441,8 @@ const SUGGEST_HELP = [
 
 const SKILLS_HELP = [
   "Usage:",
-  "  trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]",
-  "  trekoon skills install -g|--global [--editor opencode|claude|pi]",
+  "  trekoon skills install [--link --editor opencode|claude|codex|pi] [--to <path>] [--allow-outside-repo]",
+  "  trekoon skills install -g|--global [--editor opencode|claude|codex|pi]",
   "  trekoon skills update",
   "",
   "Installs or refreshes the Trekoon skill so AI agents can plan and execute.",
@@ -451,7 +451,7 @@ const SKILLS_HELP = [
   "  Creates a symlink at .agents/skills/trekoon pointing to the bundled source,",
   "  so the skill always matches the installed CLI version.",
   "  --link            Also create an editor symlink named 'trekoon'.",
-  "  --editor <name>   Required with --link (opencode|claude|pi).",
+  "  --editor <name>   Required with --link (opencode|claude|codex|pi).",
   "  --to <path>       Override the symlink root for --link only.",
   "  --allow-outside-repo  Allow links outside the repo (requires --link).",
   "",

package/src/commands/skills.ts

@@ -10,11 +10,11 @@ import { type CliContext, type CliResult } from "../runtime/command-types";
 
 const SKILLS_USAGE = [
   "Usage:",
-  "  trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]",
-  "  trekoon skills install -g|--global [--editor opencode|claude|pi]",
+  "  trekoon skills install [--link --editor opencode|claude|codex|pi] [--to <path>] [--allow-outside-repo]",
+  "  trekoon skills install -g|--global [--editor opencode|claude|codex|pi]",
   "  trekoon skills update",
 ].join("\n");
-const EDITOR_NAMES = ["opencode", "claude", "pi"] as const;
+const EDITOR_NAMES = ["opencode", "claude", "codex", "pi"] as const;
 const ALLOW_OUTSIDE_REPO_FLAG = "allow-outside-repo";
 
 type EditorName = (typeof EDITOR_NAMES)[number];
@@ -88,6 +88,10 @@ function resolveLinkRoot(cwd: string, editor: EditorName, toOverride: string | u
     return join(cwd, ".claude", "skills");
   }
 
+  if (editor === "codex") {
+    return join(cwd, ".codex", "skills");
+  }
+
   return join(cwd, ".pi", "skills");
 }
 
@@ -222,6 +226,10 @@ function resolveEditorConfigDir(cwd: string, editor: EditorName): string {
     return join(cwd, ".claude");
   }
 
+  if (editor === "codex") {
+    return join(cwd, ".codex");
+  }
+
   return join(cwd, ".pi");
 }
 
@@ -235,6 +243,10 @@ function resolveGlobalEditorSkillsDir(editor: EditorName): string {
     return join(home, ".claude", "skills");
   }
 
+  if (editor === "codex") {
+    return join(home, ".codex", "skills");
+  }
+
   return join(home, ".pi", "skills");
 }
 
@@ -542,7 +554,7 @@ function runSkillsInstall(context: CliContext): CliResult {
 
   // Validate editor early (shared by both modes).
   if (rawEditor !== undefined && !EDITOR_NAMES.includes(rawEditor as EditorName)) {
-    return invalidInput("skills.install", "Invalid --editor value. Use: opencode, claude, pi", {
+    return invalidInput("skills.install", "Invalid --editor value. Use: opencode, claude, codex, pi", {
       editor: rawEditor,
       allowedEditors: EDITOR_NAMES,
     });
@@ -588,7 +600,7 @@ function runSkillsInstall(context: CliContext): CliResult {
   }
 
   if (wantsLink && rawEditor === undefined) {
-    return invalidArgs("skills install --link requires --editor opencode|claude|pi.");
+    return invalidArgs("skills install --link requires --editor opencode|claude|codex|pi.");
   }
 
   const editor: EditorName | undefined = rawEditor as EditorName | undefined;