@jskit-ai/jskit-cli 0.2.78 → 0.2.80

package/src/server/core/argParser.js

@@ -143,7 +143,7 @@ function parseArgs(argv, { createCliError } = {}) {
       } else {
         const hasNextStringToken = typeof args[0] === "string";
         const nextToken = hasNextStringToken ? String(args[0]) : "";
-        if (hasNextStringToken && !nextToken.startsWith("-")) {
+        if (hasNextStringToken && (!nextToken.startsWith("-") || nextToken === "-")) {
           optionValueRaw = args.shift();
         }
       }
@@ -153,7 +153,7 @@ function parseArgs(argv, { createCliError } = {}) {
       }
       if (typeof optionValueRaw === "string") {
         const optionValue = optionValueRaw.trim();
-        if (!hasInlineValue && optionValue.startsWith("-")) {
+        if (!hasInlineValue && optionValue.startsWith("-") && optionValue !== "-") {
           throw createCliError(`--${optionName} requires a value.`, { showUsage: true });
         }
         options.inlineOptions[optionName] = optionValue;

package/src/server/core/commandCatalog.js

@@ -198,6 +198,89 @@ const COMMAND_DESCRIPTORS = Object.freeze({
     allowedValueOptionNames: Object.freeze([]),
     canDelegateInlineOptions: (positional = []) => Array.isArray(positional) && positional.length > 0
   }),
+  session: Object.freeze({
+    command: "session",
+    aliases: Object.freeze([]),
+    showInOverview: true,
+    summary: "Run file-backed JSKIT issue sessions.",
+    minimalUse: "jskit session create",
+    parameters: Object.freeze([
+      Object.freeze({
+        name: "create | <sessionId>",
+        description: "Create a session, inspect a session, or run a session subcommand."
+      }),
+      Object.freeze({
+        name: "[step|abandon|adopt-codex-thread]",
+        description: "Run the next step, abandon a session, or attach a Codex thread id."
+      })
+    ]),
+    defaults: Object.freeze([
+      "Active session state lives in .jskit/sessions/active/<session_id> under the current target app.",
+      "Session worktrees live in .jskit/sessions/worktrees/<session_id>.",
+      "The session id is timestamp-based and is the primary key.",
+      "Use --json for the stable machine-readable contract consumed by JSKIT AI Studio.",
+      "Use --issue - to read approved issue text from stdin."
+    ]),
+    examples: Object.freeze([
+      Object.freeze({
+        label: "Manual CLI flow",
+        lines: Object.freeze([
+          "jskit session create",
+          "jskit session 2026-05-11_21-42-08 step",
+          "jskit session 2026-05-11_21-42-08 step --prompt \"Fix the customer filters\"",
+          "jskit session 2026-05-11_21-42-08 step --issue -"
+        ])
+      })
+    ]),
+    fullUse:
+      "jskit session [create|<sessionId>] [step|abandon|adopt-codex-thread] [--prompt <text>] [--issue <text>|--issue-file <path>] [--user-check <passed|failed>] [--codex-thread-id <id>] [--json]",
+    showHelpOnBareInvocation: false,
+    handlerName: "commandSession",
+    allowedFlagKeys: Object.freeze(["json"]),
+    inlineOptionMode: "delegate",
+    allowedValueOptionNames: Object.freeze([]),
+    canDelegateInlineOptions: (positional = []) => Array.isArray(positional) && positional.length > 0
+  }),
+  blueprint: Object.freeze({
+    command: "blueprint",
+    aliases: Object.freeze([]),
+    showInOverview: true,
+    summary: "Read, prompt, or set the app-level JSKIT blueprint.",
+    minimalUse: "jskit blueprint",
+    parameters: Object.freeze([
+      Object.freeze({
+        name: "[prompt|set]",
+        description: "Without a subcommand, prints the saved app blueprint. prompt renders the AI prompt; set writes the approved blueprint."
+      })
+    ]),
+    defaults: Object.freeze([
+      "The app blueprint is product-level app state, not a feature-session step.",
+      "The saved blueprint lives at .jskit/APP_BLUEPRINT.md in the current target app.",
+      "Project prompt overrides live at .jskit/prompts/app_blueprint.md.",
+      "Use --json for a stable machine-readable response."
+    ]),
+    examples: Object.freeze([
+      Object.freeze({
+        label: "Manual blueprint flow",
+        lines: Object.freeze([
+          "jskit blueprint prompt --brief \"A field app for customer visits\"",
+          "jskit blueprint set --blueprint -",
+          "jskit blueprint --json"
+        ])
+      })
+    ]),
+    fullUse:
+      "jskit blueprint [prompt|set] [--brief <text>|--brief-file <path>] [--blueprint <text>|--blueprint-file <path>] [--json]",
+    showHelpOnBareInvocation: false,
+    handlerName: "commandBlueprint",
+    allowedFlagKeys: Object.freeze(["json"]),
+    inlineOptionMode: "delegate",
+    allowedValueOptionNames: Object.freeze([]),
+    canDelegateInlineOptions: (positional = []) => {
+      const subcommand = String(Array.isArray(positional) ? positional[0] || "" : "").trim();
+      return subcommand === "prompt" || subcommand === "set";
+    }
+  }),
   add: Object.freeze({
     command: "add",
     aliases: Object.freeze([]),

package/src/server/core/createCommandHandlers.js

@@ -6,6 +6,8 @@ import { createAppCommands } from "../commandHandlers/app.js";
 import { createMobileCommands } from "../commandHandlers/mobile.js";
 import { createHealthCommands } from "../commandHandlers/health.js";
 import { createCompletionCommands } from "../commandHandlers/completion.js";
+import { createSessionCommands } from "../commandHandlers/session.js";
+import { createBlueprintCommands } from "../commandHandlers/blueprint.js";
 
 function createCommandHandlers(deps = {}) {
   const shared = createCommandHandlerShared(deps);
@@ -29,6 +31,8 @@ function createCommandHandlers(deps = {}) {
   const { commandMobile } = createMobileCommands(commandContext, { commandAdd });
   const { commandDoctor, commandLintDescriptors } = createHealthCommands(commandContext);
   const { commandCompletion } = createCompletionCommands(commandContext);
+  const { commandSession } = createSessionCommands(commandContext);
+  const { commandBlueprint } = createBlueprintCommands(commandContext);
 
   return {
     commandList,
@@ -46,7 +50,9 @@ function createCommandHandlers(deps = {}) {
     commandUpdate,
     commandRemove,
     commandDoctor,
-    commandLintDescriptors
+    commandLintDescriptors,
+    commandSession,
+    commandBlueprint
   };
 }
 

package/src/server/index.js

@@ -1 +1,3 @@
 export { runCli } from "./core/createCliRunner.js";
+export * from "./sessionRuntime.js";
+export * from "./appBlueprint.js";

package/src/server/sessionRuntime/constants.js

@@ -0,0 +1,296 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SESSION_STATUS = Object.freeze({
+  ABANDONED: "abandoned",
+  BLOCKED: "blocked",
+  FAILED: "failed",
+  FINISHED: "finished",
+  PENDING: "pending",
+  RUNNING: "running",
+  WAITING_FOR_USER: "waiting_for_user"
+});
+
+const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}(?:-[a-z0-9]{4})?$/u;
+const SESSION_STATE_RELATIVE_PATH = ".jskit/sessions";
+const PROMPT_DIRECTORY = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "prompts");
+
+const INPUT_NONE = Object.freeze({ type: "none" });
+const ISSUE_TEXT_INPUT = Object.freeze({
+  extract: "issue_text",
+  formatHint: "markdown",
+  label: "Approved issue text",
+  multiline: true,
+  name: "issue",
+  required: true,
+  type: "text"
+});
+const USER_CHECK_INPUT = Object.freeze({
+  label: "User check result",
+  name: "userCheck",
+  options: Object.freeze([
+    Object.freeze({ label: "Passed", value: "passed" }),
+    Object.freeze({ label: "Failed", value: "failed" })
+  ]),
+  required: true,
+  type: "choice"
+});
+const CODEX_WORKTREE_OUTPUT = Object.freeze({
+  field: "worktree",
+  formatHint: "git_changes"
+});
+
+function codexHandoff(expectedOutput) {
+  return Object.freeze({
+    expectedOutput,
+    mode: "inject_prompt",
+    promptField: "prompt"
+  });
+}
+
+function defineStep({
+  buttonLabel,
+  codex = undefined,
+  description,
+  id,
+  input = INPUT_NONE,
+  kind = "automatic",
+  label,
+  nextCommandTemplate = "jskit session {{session_id}} step",
+  preconditions = []
+}) {
+  return Object.freeze({
+    buttonLabel,
+    codex,
+    description,
+    id,
+    input,
+    kind,
+    label,
+    nextCommandTemplate,
+    preconditions: Object.freeze([...preconditions])
+  });
+}
+
+const STEP_DEFINITIONS = Object.freeze([
+  defineStep({
+    buttonLabel: "Create session",
+    description: "Create the filesystem-backed session state.",
+    id: "session_created",
+    label: "Session created"
+  }),
+  defineStep({
+    buttonLabel: "Create worktree",
+    description: "Create the isolated session worktree and branch.",
+    id: "worktree_created",
+    label: "Worktree created",
+    preconditions: ["session_exists", "git_repository", "git_current_branch"]
+  }),
+  defineStep({
+    buttonLabel: "Render issue prompt",
+    description: "Render the prompt Codex should use to draft the GitHub issue.",
+    id: "issue_prompt_rendered",
+    input: Object.freeze({
+      label: "What should change?",
+      multiline: true,
+      name: "prompt",
+      placeholder: "Describe the feature, bug, or change request.",
+      required: true,
+      type: "text"
+    }),
+    kind: "human_input",
+    label: "Issue prompt rendered",
+    nextCommandTemplate: "jskit session {{session_id}} step --prompt \"<what should change>\"",
+    preconditions: ["session_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Save issue text",
+    codex: codexHandoff(Object.freeze({
+      extract: "issue_text",
+      field: "issue",
+      formatHint: "markdown"
+    })),
+    description: "Save the approved issue text produced by Codex.",
+    id: "issue_drafted",
+    input: ISSUE_TEXT_INPUT,
+    kind: "codex_output",
+    label: "Issue drafted",
+    nextCommandTemplate: "jskit session {{session_id}} step --issue -",
+    preconditions: ["session_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Create GitHub issue",
+    description: "Create the GitHub issue with gh.",
+    id: "issue_created",
+    label: "Issue created",
+    preconditions: ["session_exists", "issue_text_exists", "github_auth", "github_origin"]
+  }),
+  defineStep({
+    buttonLabel: "Render implementation prompt",
+    description: "Render the prompt Codex should use to implement the approved issue.",
+    id: "implementation_prompt_rendered",
+    kind: "codex_prompt",
+    label: "Implementation prompt rendered",
+    preconditions: ["session_exists", "issue_artifacts"]
+  }),
+  defineStep({
+    buttonLabel: "Detect implementation changes",
+    codex: codexHandoff(CODEX_WORKTREE_OUTPUT),
+    description: "Confirm that Codex changed files in the session worktree.",
+    id: "implementation_changes_detected",
+    kind: "codex_output",
+    label: "Changes detected",
+    preconditions: ["session_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Commit implementation",
+    description: "Commit the implementation changes in the session worktree.",
+    id: "implementation_changes_committed",
+    label: "Changes committed",
+    preconditions: ["session_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Render review prompt 1",
+    description: "Render the first Codex review prompt for the committed changes.",
+    id: "initial_review_prompt_rendered",
+    kind: "codex_prompt",
+    label: "Review prompt rendered 1",
+    preconditions: ["session_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Detect review changes 1",
+    codex: codexHandoff(CODEX_WORKTREE_OUTPUT),
+    description: "Commit any changes Codex made after the first review pass.",
+    id: "initial_review_changes_detected",
+    kind: "codex_output",
+    label: "Review changes detected 1",
+    preconditions: ["session_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Save user check 1",
+    description: "Record whether the first user check passed.",
+    id: "initial_user_check_completed",
+    input: USER_CHECK_INPUT,
+    kind: "user_check",
+    label: "User check 1",
+    nextCommandTemplate: "jskit session {{session_id}} step --user-check passed",
+    preconditions: ["session_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Render review prompt 2",
+    description: "Render the second Codex review prompt for the committed changes.",
+    id: "followup_review_prompt_rendered",
+    kind: "codex_prompt",
+    label: "Review prompt rendered 2",
+    preconditions: ["session_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Detect review changes 2",
+    codex: codexHandoff(CODEX_WORKTREE_OUTPUT),
+    description: "Commit any changes Codex made after the second review pass.",
+    id: "followup_review_changes_detected",
+    kind: "codex_output",
+    label: "Review changes detected 2",
+    preconditions: ["session_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Save user check 2",
+    description: "Record whether the second user check passed.",
+    id: "followup_user_check_completed",
+    input: USER_CHECK_INPUT,
+    kind: "user_check",
+    label: "User check 2",
+    nextCommandTemplate: "jskit session {{session_id}} step --user-check passed",
+    preconditions: ["session_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Render final review prompt",
+    description: "Render the final Codex review prompt before verification and PR.",
+    id: "final_review_prompt_rendered",
+    kind: "codex_prompt",
+    label: "Review prompt rendered 3",
+    preconditions: ["session_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Detect final review changes",
+    codex: codexHandoff(CODEX_WORKTREE_OUTPUT),
+    description: "Commit any changes Codex made after the final review pass.",
+    id: "final_review_changes_detected",
+    kind: "codex_output",
+    label: "Review changes detected 3",
+    preconditions: ["session_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Save final user check",
+    description: "Record whether the final user check passed.",
+    id: "final_user_check_completed",
+    input: USER_CHECK_INPUT,
+    kind: "user_check",
+    label: "User check 3",
+    nextCommandTemplate: "jskit session {{session_id}} step --user-check passed",
+    preconditions: ["session_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Run verification",
+    description: "Run the project verification command in the session worktree.",
+    id: "doctor_run",
+    label: "Doctor run",
+    preconditions: ["session_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Push branch",
+    description: "Push the session branch to origin.",
+    id: "branch_pushed",
+    label: "Branch pushed",
+    preconditions: ["session_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Create PR",
+    description: "Create a GitHub pull request for the session branch.",
+    id: "pr_created",
+    label: "PR created",
+    preconditions: ["session_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Merge PR",
+    description: "Merge the pull request and close the GitHub issue.",
+    id: "pr_merged",
+    label: "PR merged",
+    preconditions: ["session_exists", "pr_url_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Remove worktree",
+    description: "Remove the session worktree after the PR has merged.",
+    id: "worktree_removed",
+    label: "Worktree removed",
+    preconditions: ["session_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Finish session",
+    description: "Write the final receipt and archive the completed session.",
+    id: "session_finished",
+    label: "Session finished",
+    preconditions: ["session_exists"]
+  })
+]);
+
+const STEP_IDS = Object.freeze(STEP_DEFINITIONS.map((step) => step.id));
+const STEP_LABEL_BY_ID = Object.freeze(Object.fromEntries(STEP_DEFINITIONS.map((step) => [step.id, step.label])));
+const STEP_DEFINITION_BY_ID = Object.freeze(Object.fromEntries(STEP_DEFINITIONS.map((step) => [step.id, step])));
+const STEP_PRECONDITION_NAMES = Object.freeze(Object.fromEntries(
+  STEP_DEFINITIONS
+    .filter((step) => step.id !== "session_created")
+    .map((step) => [step.id, step.preconditions])
+));
+
+export {
+  PROMPT_DIRECTORY,
+  SESSION_ID_PATTERN,
+  SESSION_STATUS,
+  STEP_DEFINITION_BY_ID,
+  STEP_DEFINITIONS,
+  STEP_IDS,
+  STEP_LABEL_BY_ID,
+  STEP_PRECONDITION_NAMES,
+  SESSION_STATE_RELATIVE_PATH
+};

package/src/server/sessionRuntime/io.js

@@ -0,0 +1,97 @@
+import { execFile } from "node:child_process";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+function normalizeText(value) {
+  return String(value || "").trim();
+}
+
+function timestampForReceipt(now = new Date()) {
+  return now.toISOString();
+}
+
+async function fileExists(filePath) {
+  try {
+    await access(filePath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readTextIfExists(filePath) {
+  if (!filePath || !(await fileExists(filePath))) {
+    return "";
+  }
+  return readFile(filePath, "utf8");
+}
+
+async function readTrimmedFile(filePath) {
+  return normalizeText(await readTextIfExists(filePath));
+}
+
+async function writeTextFile(filePath, value) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${String(value || "").replace(/\s*$/u, "")}\n`, "utf8");
+}
+
+async function runCommand(command, args = [], { cwd, env = {}, timeout = 30000 } = {}) {
+  try {
+    const result = await execFileAsync(command, args, {
+      cwd,
+      env: {
+        ...process.env,
+        ...env
+      },
+      maxBuffer: 1024 * 1024 * 10,
+      timeout
+    });
+    return {
+      exitCode: 0,
+      ok: true,
+      output: String([result.stdout, result.stderr].filter(Boolean).join("\n")).trim(),
+      stderr: String(result.stderr || "").trim(),
+      stdout: String(result.stdout || "").trim()
+    };
+  } catch (error) {
+    const stdout = String(error?.stdout || "").trim();
+    const stderr = String(error?.stderr || "").trim();
+    return {
+      exitCode: typeof error?.code === "number" ? error.code : 1,
+      ok: false,
+      output: String(error?.message || [stdout, stderr].filter(Boolean).join("\n")).trim(),
+      stderr,
+      stdout
+    };
+  }
+}
+
+async function runGit(targetRoot, args = [], options = {}) {
+  return runCommand("git", args, {
+    cwd: targetRoot,
+    ...options
+  });
+}
+
+async function runGitInWorktree(worktree, args = [], options = {}) {
+  return runCommand("git", args, {
+    cwd: worktree,
+    ...options
+  });
+}
+
+export {
+  fileExists,
+  normalizeText,
+  readTextIfExists,
+  readTrimmedFile,
+  runCommand,
+  runGit,
+  runGitInWorktree,
+  timestampForReceipt,
+  writeTextFile
+};

package/src/server/sessionRuntime/paths.js

@@ -0,0 +1,165 @@
+import { mkdir, rename } from "node:fs/promises";
+import path from "node:path";
+import {
+  SESSION_ID_PATTERN,
+  SESSION_STATE_RELATIVE_PATH
+} from "./constants.js";
+import {
+  fileExists,
+  normalizeText
+} from "./io.js";
+
+function formatDatePart(value) {
+  return String(value).padStart(2, "0");
+}
+
+function createSessionId(now = new Date()) {
+  const year = now.getFullYear();
+  const month = formatDatePart(now.getMonth() + 1);
+  const day = formatDatePart(now.getDate());
+  const hour = formatDatePart(now.getHours());
+  const minute = formatDatePart(now.getMinutes());
+  const second = formatDatePart(now.getSeconds());
+  return `${year}-${month}-${day}_${hour}-${minute}-${second}`;
+}
+
+async function createAvailableSessionId(targetRoot, now = new Date()) {
+  const baseSessionId = createSessionId(now);
+  const basePaths = resolveSessionPaths({ targetRoot, sessionId: baseSessionId });
+  if (
+    !(await fileExists(basePaths.sessionRoot)) &&
+    !(await fileExists(basePaths.completedSessionRoot)) &&
+    !(await fileExists(basePaths.abandonedSessionRoot))
+  ) {
+    return baseSessionId;
+  }
+
+  for (let index = 1; index <= 36 ** 4 - 1; index += 1) {
+    const suffix = index.toString(36).padStart(4, "0");
+    const candidate = `${baseSessionId}-${suffix}`;
+    const candidatePaths = resolveSessionPaths({ targetRoot, sessionId: candidate });
+    if (
+      !(await fileExists(candidatePaths.sessionRoot)) &&
+      !(await fileExists(candidatePaths.completedSessionRoot)) &&
+      !(await fileExists(candidatePaths.abandonedSessionRoot))
+    ) {
+      return candidate;
+    }
+  }
+
+  throw new Error(`No available session id found for timestamp ${baseSessionId}.`);
+}
+
+function isValidSessionId(sessionId = "") {
+  return SESSION_ID_PATTERN.test(normalizeText(sessionId));
+}
+
+function normalizeSessionId(sessionId = "") {
+  const normalized = normalizeText(sessionId);
+  if (!isValidSessionId(normalized)) {
+    throw new Error(`Invalid session id "${sessionId}". Expected YYYY-MM-DD_HH-MM-SS.`);
+  }
+  return normalized;
+}
+
+function resolveSessionPaths({ targetRoot, sessionId = "" } = {}) {
+  const normalizedTargetRoot = path.resolve(normalizeText(targetRoot) || process.cwd());
+  const sessionStateRoot = path.join(normalizedTargetRoot, SESSION_STATE_RELATIVE_PATH);
+  const sessionsRoot = path.join(sessionStateRoot, "active");
+  const completedSessionsRoot = path.join(sessionStateRoot, "completed");
+  const abandonedSessionsRoot = path.join(sessionStateRoot, "abandoned");
+  const worktreesRoot = path.join(sessionStateRoot, "worktrees");
+  const normalizedSessionId = sessionId ? normalizeSessionId(sessionId) : "";
+  const sessionRoot = normalizedSessionId ? path.join(sessionsRoot, normalizedSessionId) : "";
+  const worktree = normalizedSessionId ? path.join(worktreesRoot, normalizedSessionId) : "";
+  const branch = normalizedSessionId ? `jskit-studio/${normalizedSessionId}` : "";
+
+  return Object.freeze({
+    abandonedSessionRoot: normalizedSessionId ? path.join(abandonedSessionsRoot, normalizedSessionId) : "",
+    abandonedSessionsRoot,
+    branch,
+    completedSessionRoot: normalizedSessionId ? path.join(completedSessionsRoot, normalizedSessionId) : "",
+    completedSessionsRoot,
+    sessionId: normalizedSessionId,
+    sessionRoot,
+    sessionsRoot,
+    sessionStateRoot,
+    targetRoot: normalizedTargetRoot,
+    worktree,
+    worktreesRoot
+  });
+}
+
+async function resolveExistingSessionRoot(paths) {
+  if (paths.archive && await fileExists(paths.sessionRoot)) {
+    return {
+      archive: paths.archive,
+      root: paths.sessionRoot
+    };
+  }
+  if (await fileExists(paths.sessionRoot)) {
+    return {
+      archive: "active",
+      root: paths.sessionRoot
+    };
+  }
+  if (await fileExists(paths.completedSessionRoot)) {
+    return {
+      archive: "completed",
+      root: paths.completedSessionRoot
+    };
+  }
+  if (await fileExists(paths.abandonedSessionRoot)) {
+    return {
+      archive: "abandoned",
+      root: paths.abandonedSessionRoot
+    };
+  }
+  return {
+    archive: "",
+    root: ""
+  };
+}
+
+async function pathsForExistingSession(paths) {
+  const existing = await resolveExistingSessionRoot(paths);
+  if (!existing.root || existing.root === paths.sessionRoot) {
+    return paths;
+  }
+  return Object.freeze({
+    ...paths,
+    archive: existing.archive,
+    sessionRoot: existing.root
+  });
+}
+
+async function archiveSession(paths, archive) {
+  const archiveRoot = archive === "completed" ? paths.completedSessionRoot : paths.abandonedSessionRoot;
+  if (!archiveRoot || paths.sessionRoot === archiveRoot) {
+    return paths;
+  }
+  if (!(await fileExists(paths.sessionRoot))) {
+    return pathsForExistingSession(paths);
+  }
+  if (await fileExists(archiveRoot)) {
+    throw new Error(`Cannot archive session ${paths.sessionId}; target already exists: ${archiveRoot}`);
+  }
+  await mkdir(path.dirname(archiveRoot), { recursive: true });
+  await rename(paths.sessionRoot, archiveRoot);
+  return Object.freeze({
+    ...paths,
+    archive,
+    sessionRoot: archiveRoot
+  });
+}
+
+export {
+  archiveSession,
+  createAvailableSessionId,
+  createSessionId,
+  isValidSessionId,
+  normalizeSessionId,
+  resolveExistingSessionRoot,
+  resolveSessionPaths,
+  pathsForExistingSession
+};