aether-code 0.4.0 → 0.6.0

package/bin/aether-code.js

@@ -14,9 +14,11 @@ import { runRepl } from "../src/repl.js";
 import { runSetup } from "../src/setup.js";
 import { fetchBalance, AetherError } from "../src/api.js";
 import { writeConfigFile, getConfig, CONFIG_PATH } from "../src/config.js";
+import { generateAndApprovePlan } from "../src/plan.js";
+import { listSessions, loadSession, loadMostRecent, deleteSession, truncatePreview, sessionsDir } from "../src/sessions.js";
 import { c, errorLine, divider } from "../src/render.js";
 
-const VERSION = "0.4.0";
+const VERSION = "0.6.0";
 
 const HELP = `${c.bold("aether")} — uncensored AI coding agent
 
@@ -30,6 +32,7 @@ ${c.bold("SUBCOMMANDS")}
   ${c.cyan("logout")}                               Clear saved API key
   ${c.cyan("balance")}                              Show plan + credit balance
   ${c.cyan("config")} show|set|set-base|path        Manage config file
+  ${c.cyan("sessions")} [list|show|delete] [id]     List, show, or delete saved sessions
 
 ${c.bold("EXAMPLES")}
   aether                               # interactive REPL
@@ -40,6 +43,9 @@ ${c.bold("EXAMPLES")}
   aether --cwd ./my-project "fix the failing tests"
 
 ${c.bold("FLAGS")}
+  --plan             Show a numbered plan first; approve / refine / cancel before any tools fire.
+  --resume [id]      Continue a prior conversation. No id = most recent.
+  --no-save          Don't persist this session to ~/.aether/sessions/.
   --yes              Auto-approve all writes and shell commands. Use with care.
   --cwd <path>       Working directory for the agent (default: current dir).
   --max-turns <n>    Maximum turns before stopping (default: 25).
@@ -65,6 +71,19 @@ function parseArgs(argv) {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--yes") { args.flags.yes = true; }
+    else if (a === "--plan") { args.flags.plan = true; }
+    else if (a === "--no-save") { args.flags.noSave = true; }
+    else if (a === "--resume") {
+      // --resume optionally takes a session id. If next arg starts with "--"
+      // or doesn't exist, default to "latest".
+      const nxt = argv[i + 1];
+      if (!nxt || nxt.startsWith("--")) {
+        args.flags.resume = "latest";
+      } else {
+        args.flags.resume = nxt;
+        i++;
+      }
+    }
     else if (a === "--unsafe-paths") { args.flags.unsafePaths = true; }
     else if (a === "--help" || a === "-h") { args.flags.help = true; }
     else if (a === "--version" || a === "-v") { args.flags.version = true; }
@@ -122,13 +141,30 @@ async function main() {
     await handleBalance();
     return;
   }
+  if (sub === "sessions") {
+    await handleSessions(args._.slice(1));
+    return;
+  }
 
   const prompt = args._.join(" ").trim();
 
-  // No task → drop into interactive REPL (Claude-CLI-style)
+  // Resume from a prior session if --resume was passed
+  let resumed = null;
+  if (args.flags.resume) {
+    resumed =
+      args.flags.resume === "latest"
+        ? loadMostRecent()
+        : loadSession(args.flags.resume);
+    if (!resumed) {
+      die(`No session found for '${args.flags.resume}'. Run 'aether sessions' to see what's available.`);
+    }
+  }
+
+  // No task AND not resuming → drop into interactive REPL.
+  // No task BUT resuming → drop into REPL with the prior history loaded.
   if (!prompt) {
     if (cwd !== process.cwd()) process.chdir(cwd);
-    await runRepl({ cwd, autoYes, maxTurns });
+    await runRepl({ cwd, autoYes, maxTurns, resumed });
     return;
   }
 
@@ -140,16 +176,52 @@ async function main() {
   }
 
   console.log(divider());
-  console.log(c.magenta(c.bold("aether-code")) + c.gray(` · cwd ${cwd}${autoYes ? " · auto-yes" : ""}${unsafePaths ? " · unsafe-paths" : ""}`));
+  console.log(c.magenta(c.bold("aether-code")) + c.gray(` · cwd ${cwd}${autoYes ? " · auto-yes" : ""}${unsafePaths ? " · unsafe-paths" : ""}${args.flags.plan ? " · plan-mode" : ""}${resumed ? ` · resumed ${resumed.id}` : ""}`));
   console.log(c.gray(`task: `) + prompt);
   console.log(divider());
 
+  // Plan mode: generate plan first, get approval, then execute with the plan
+  // injected into the conversation as context.
+  let priorMessages = resumed ? resumed.messages : undefined;
+  if (args.flags.plan) {
+    let currentTask = prompt;
+    // Up to 3 plan/refine cycles before bailing
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const planResult = await generateAndApprovePlan({ initialPrompt: currentTask, cwd });
+      if (planResult.cancelled) {
+        console.log(c.gray("\nCancelled. No tools were run."));
+        return;
+      }
+      if (planResult.approved) {
+        // Inject the plan as prior context so the agent remembers it as it executes
+        priorMessages = [
+          { role: "user", content: currentTask },
+          { role: "assistant", content: `Plan:\n${planResult.planText}` },
+        ];
+        break;
+      }
+      if (planResult.refinement) {
+        console.log(c.gray(`Refining: ${planResult.refinement}`));
+        currentTask = `${currentTask}\n\nRefinement: ${planResult.refinement}`;
+      }
+    }
+    if (!priorMessages) {
+      console.log(c.yellow("\nGave up after 3 refinement cycles. Try a clearer task."));
+      return;
+    }
+    console.log("");
+  }
+
   const result = await runAgent({
     initialPrompt: prompt,
+    priorMessages,
     cwd,
     autoYes,
     unsafePaths,
     maxTurns,
+    sessionId: resumed?.id,                       // reuse the prior id when resuming
+    sessionCreatedAt: resumed?.createdAt,
+    saveSessions: !args.flags.noSave,
   });
 
   console.log("\n" + divider());
@@ -162,6 +234,9 @@ async function main() {
     console.log(c.red(c.bold("✗ Stopped")) + c.gray(`  ${result.totalCredits} credits used · ${result.totalIn}→${result.totalOut} tokens`));
     if (result.error) console.log(errorLine(result.error.message));
   }
+  if (result.sessionId) {
+    console.log(c.gray(`  session: ${result.sessionId}  — resume with `) + c.cyan(`aether --resume ${result.sessionId}`));
+  }
   console.log(divider());
 }
 
@@ -221,6 +296,79 @@ async function handleBalance() {
   }
 }
 
+async function handleSessions(rest) {
+  const sub = (rest[0] || "list").toLowerCase();
+
+  if (sub === "list" || sub === "ls") {
+    const sessions = listSessions(50);
+    if (sessions.length === 0) {
+      console.log(c.gray("No sessions saved yet. They appear here after you run aether on any task."));
+      console.log(c.gray(`Sessions live in: ${sessionsDir()}`));
+      return;
+    }
+    console.log(c.bold(c.magenta("Recent sessions")) + c.gray(`  (${sessions.length})`));
+    console.log(c.gray("─".repeat(72)));
+    for (const s of sessions) {
+      const when = new Date(s.lastUsedAt).toLocaleString("en-US", {
+        month: "short", day: "numeric", hour: "numeric", minute: "2-digit",
+      });
+      const credits = s.totalCredits ? c.gray(` · ${s.totalCredits} cr`) : "";
+      console.log(c.cyan(s.id) + c.gray(` · ${when}`) + credits);
+      console.log(c.gray("  ") + truncatePreview(s.firstUserMessage, 64));
+      console.log(c.dim(`  in ${truncatePreview(s.cwd, 64)}`));
+      console.log("");
+    }
+    console.log(c.gray(`Resume with `) + c.cyan(`aether --resume <id>`) + c.gray(`  (or just `) + c.cyan(`aether --resume`) + c.gray(` for the most recent)`));
+    return;
+  }
+
+  if (sub === "show") {
+    const id = rest[1];
+    if (!id) die("sessions show: missing session id");
+    const s = loadSession(id);
+    if (!s) die(`No session found for '${id}'`);
+    console.log(c.bold(c.magenta(`Session ${s.id}`)));
+    console.log(c.gray(`Created: ${s.createdAt}`));
+    console.log(c.gray(`Last used: ${s.lastUsedAt}`));
+    console.log(c.gray(`Cwd: ${s.cwd}`));
+    console.log(c.gray(`Credits: ${s.totalCredits ?? 0}, Messages: ${s.messages?.length ?? 0}`));
+    console.log(c.gray("─".repeat(72)));
+    for (const m of s.messages || []) {
+      const label =
+        m.role === "user" ? c.cyan("user")
+        : m.role === "assistant" ? c.magenta("assistant")
+        : m.role === "tool" ? c.green("tool")
+        : c.gray(m.role);
+      const text = typeof m.content === "string" ? m.content : JSON.stringify(m.content);
+      console.log(`${label}: ${truncatePreview(text, 200)}`);
+      if (m.tool_calls?.length) {
+        for (const tc of m.tool_calls) {
+          console.log(c.gray(`  ↪ ${tc.function?.name}(${tc.function?.arguments?.slice(0, 80) ?? ""})`));
+        }
+      }
+    }
+    return;
+  }
+
+  if (sub === "delete" || sub === "rm") {
+    const id = rest[1];
+    if (!id) die("sessions delete: missing session id");
+    if (deleteSession(id)) {
+      console.log(`${c.green("✓")} Deleted session ${id}`);
+    } else {
+      die(`No session found for '${id}'`);
+    }
+    return;
+  }
+
+  if (sub === "dir" || sub === "path") {
+    console.log(sessionsDir());
+    return;
+  }
+
+  die(`sessions: unknown subcommand '${sub}'. Try: list, show <id>, delete <id>, dir`);
+}
+
 main().catch((err) => {
   console.error(errorLine(err.message || String(err)));
   if (process.env.DEBUG) console.error(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aether-code",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Uncensored AI coding agent for your terminal. Type `aether` to launch the interactive REPL — like Claude Code, with no refusal layer.",
   "homepage": "https://trynoguard.com",
   "repository": {
@@ -22,7 +22,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "lint": "node --check bin/aether-code.js src/agent.js src/api.js src/config.js src/render.js src/tools.js src/diff.js src/repl.js"
+    "lint": "node --check bin/aether-code.js && node --check src/agent.js && node --check src/api.js && node --check src/config.js && node --check src/render.js && node --check src/tools.js && node --check src/diff.js && node --check src/repl.js && node --check src/plan.js && node --check src/sessions.js"
   },
   "keywords": [
     "aether",

package/src/agent.js

@@ -4,6 +4,7 @@
 
 import { agentTurnStream, AetherError } from "./api.js";
 import { TOOL_DEFINITIONS, executeTool } from "./tools.js";
+import { saveSession, newSessionId } from "./sessions.js";
 import {
   c, turnLine, costLine, toolAnnounce, toolResultLine, errorLine, assistantPrefix,
 } from "./render.js";
@@ -18,6 +19,10 @@ export async function runAgent({
   unsafePaths = false,
   maxTurns = DEFAULT_MAX_TURNS,
   onTokens = () => {},
+  // Session persistence options
+  sessionId,                  // existing id (resume) or null (new)
+  saveSessions = true,        // disable with --no-save
+  sessionCreatedAt,           // ISO from prior session, or now
 }) {
   const messages = priorMessages
     ? [...priorMessages, { role: "user", content: initialPrompt }]
@@ -27,6 +32,32 @@ export async function runAgent({
   let totalOut = 0;
   let lastBalance = null;
 
+  // Session bookkeeping — save after every turn so a crash doesn't lose state.
+  const activeSessionId = sessionId ?? (saveSessions ? newSessionId() : null);
+  const createdAt = sessionCreatedAt ?? new Date().toISOString();
+  // Find the first user message text for the index display
+  const firstUser = messages.find((m) => m.role === "user");
+  const firstUserMessage =
+    firstUser && typeof firstUser.content === "string" ? firstUser.content : initialPrompt;
+  const persist = () => {
+    if (!activeSessionId || !saveSessions) return;
+    try {
+      saveSession({
+        id: activeSessionId,
+        createdAt,
+        cwd,
+        totalCredits,
+        totalIn,
+        totalOut,
+        firstUserMessage,
+        messages,
+      });
+    } catch (e) {
+      // Don't kill the agent on save failure; just warn once.
+      console.log(c.dim(`(session save failed: ${e.message})`));
+    }
+  };
+
   for (let i = 0; i < maxTurns; i++) {
     process.stdout.write("\n" + turnLine(i + 1) + "\n");
 
@@ -60,7 +91,17 @@ export async function runAgent({
       });
     } catch (err) {
       if (err instanceof AetherError) {
-        return { ok: false, error: err, totalCredits, totalIn, totalOut, balance: lastBalance, messages };
+        persist();
+        return {
+          ok: false,
+          error: err,
+          totalCredits,
+          totalIn,
+          totalOut,
+          balance: lastBalance,
+          messages,
+          sessionId: activeSessionId,
+        };
       }
       throw err;
     }
@@ -88,7 +129,17 @@ export async function runAgent({
 
     const toolCalls = res.message.tool_calls ?? [];
     if (toolCalls.length === 0) {
-      return { ok: true, totalCredits, totalIn, totalOut, turns: i + 1, balance: lastBalance, messages };
+      persist();
+      return {
+        ok: true,
+        totalCredits,
+        totalIn,
+        totalOut,
+        turns: i + 1,
+        balance: lastBalance,
+        messages,
+        sessionId: activeSessionId,
+      };
     }
 
     // Execute each tool call. Now we know the full args, render the friendly
@@ -108,8 +159,20 @@ export async function runAgent({
         content: result.output ?? (result.ok ? "(no output)" : "Failed."),
       });
     }
+    // Save after each tool round so a kill -9 doesn't lose state
+    persist();
   }
 
   console.log(c.yellow(`\n⚠ Reached max turns (${maxTurns}). Stopping.`));
-  return { ok: false, error: new Error("Max turns reached"), totalCredits, totalIn, totalOut, balance: lastBalance, messages };
+  persist();
+  return {
+    ok: false,
+    error: new Error("Max turns reached"),
+    totalCredits,
+    totalIn,
+    totalOut,
+    balance: lastBalance,
+    messages,
+    sessionId: activeSessionId,
+  };
 }

package/src/api.js

@@ -66,6 +66,7 @@ export async function agentTurnStream({
   tools,
   maxTokens,
   temperature,
+  toolChoice,
   onDelta,
   onToolCallDelta,
   onFinish,
@@ -94,6 +95,7 @@ export async function agentTurnStream({
         tools,
         max_tokens: maxTokens,
         temperature,
+        ...(toolChoice ? { tool_choice: toolChoice } : {}),
       }),
     });
   } catch (e) {

package/src/plan.js

@@ -0,0 +1,133 @@
+// Plan mode — get a structured multi-step plan from the model BEFORE any
+// tools fire, show it to the user, let them approve or refine.
+//
+// Flow:
+//   1. Send a preflight request to /api/v1/agent with tool_choice: "none"
+//      and a planning system prompt. Model returns a numbered plan as text.
+//   2. Render the plan with borders. Prompt user: approve / refine / cancel.
+//   3. If approved, the plan text is appended as a tool-style "plan" entry
+//      in the message history (so the model remembers it as it executes).
+//   4. Normal agent loop continues with tools enabled.
+
+import readline from "node:readline";
+import { agentTurnStream, AetherError } from "./api.js";
+import { TOOL_DEFINITIONS } from "./tools.js";
+import { c, errorLine } from "./render.js";
+
+const PLAN_SYSTEM = `You are in PLAN MODE. The user wants to see what you'll do BEFORE you do it.
+
+Output a NUMBERED PLAN of the concrete steps you'll take. Each step should be:
+- One short line
+- Reference a specific tool you'll call (read_file, write_file, edit_file, run_shell, list_dir, search_files)
+- Mention the file path or command involved
+
+DO NOT call any tools. DO NOT include code blocks. Just the numbered plan.
+
+End with one line: "Approve this plan? (y / n / refine)"
+
+Example output:
+
+1. read_file: src/auth.ts  — inspect the existing handler
+2. edit_file: src/auth.ts  — add input validation before the password check
+3. write_file: src/auth.test.ts  — add a test for invalid input
+4. run_shell: npm test  — verify the test passes
+
+Approve this plan? (y / n / refine)`;
+
+function ask(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function renderPlanBox(plan) {
+  const w = Math.min(process.stdout.columns || 80, 90);
+  const top = c.gray("╭" + "─".repeat(w - 2) + "╮");
+  const bot = c.gray("╰" + "─".repeat(w - 2) + "╯");
+  const blank = c.gray("│") + " ".repeat(w - 2) + c.gray("│");
+  const lines = [top, blank, c.gray("│ ") + c.bold(c.cyan("📋 Plan")) + " ".repeat(w - 11) + c.gray("│"), blank];
+  for (const line of plan.split("\n")) {
+    // Wrap long lines
+    const wrapWidth = w - 4;
+    let rest = line;
+    while (rest.length > wrapWidth) {
+      const slice = rest.slice(0, wrapWidth);
+      lines.push(c.gray("│ ") + slice + " ".repeat(w - 3 - slice.length) + c.gray("│"));
+      rest = rest.slice(wrapWidth);
+    }
+    lines.push(c.gray("│ ") + rest + " ".repeat(Math.max(0, w - 3 - rest.length)) + c.gray("│"));
+  }
+  lines.push(blank, bot);
+  return lines.join("\n");
+}
+
+/**
+ * Generate a plan, show it, get approval. Returns:
+ *   { approved: true, planText: "..." }       — user said yes
+ *   { approved: false, cancelled: true }       — user said no
+ *   { approved: false, refinement: "..." }     — user wants to refine
+ */
+export async function generateAndApprovePlan({ initialPrompt, cwd, priorMessages }) {
+  process.stdout.write(c.dim("Generating plan...\n"));
+
+  const messages = priorMessages
+    ? [...priorMessages, { role: "user", content: initialPrompt }]
+    : [
+        { role: "system", content: PLAN_SYSTEM },
+        { role: "user", content: initialPrompt },
+      ];
+
+  let planText = "";
+  let creditsCharged = 0;
+  let inputTokens = 0;
+  let outputTokens = 0;
+
+  try {
+    const res = await agentTurnStream({
+      messages,
+      tools: TOOL_DEFINITIONS,
+      // Override server heuristic — we explicitly want NO tools here.
+      toolChoice: "none",
+      maxTokens: 1200,
+    });
+    planText = (res.message.content || "").trim();
+    creditsCharged = res.creditsCharged ?? 0;
+    inputTokens = res.usage?.prompt_tokens ?? 0;
+    outputTokens = res.usage?.completion_tokens ?? 0;
+  } catch (err) {
+    if (err instanceof AetherError) {
+      console.log(errorLine(err.message));
+      return { approved: false, cancelled: true };
+    }
+    throw err;
+  }
+
+  if (!planText) {
+    console.log(errorLine("Got empty plan from model. Try again or run without --plan."));
+    return { approved: false, cancelled: true };
+  }
+
+  // Render the plan in a box
+  console.log("");
+  console.log(renderPlanBox(planText));
+  console.log(c.dim(`  ${creditsCharged} cr · ${inputTokens}→${outputTokens} tokens (planning)\n`));
+
+  // Prompt for approval
+  const answer = await ask(
+    c.yellow("  ? ") + c.bold("Run this plan?") + c.gray(" [y / n / refine]: "),
+  );
+  const lower = answer.toLowerCase();
+
+  if (lower === "y" || lower === "yes") {
+    return { approved: true, planText, creditsCharged, inputTokens, outputTokens };
+  }
+  if (lower === "n" || lower === "no" || lower === "" || lower === "exit") {
+    return { approved: false, cancelled: true };
+  }
+  // Anything else is treated as refinement text
+  return { approved: false, refinement: answer || lower };
+}

package/src/repl.js

@@ -13,9 +13,10 @@ import path from "node:path";
 import { runAgent } from "./agent.js";
 import { fetchBalance, AetherError } from "./api.js";
 import { runSetup } from "./setup.js";
+import { listSessions, truncatePreview } from "./sessions.js";
 import { c, errorLine, banner, statusLine } from "./render.js";
 
-const VERSION = "0.4.0";
+const VERSION = "0.6.0";
 const MODEL_NAME = "Aether Core";
 
 const SHORTCUTS = `
@@ -27,22 +28,29 @@ const SHORTCUTS = `
   ${c.cyan("/yes")}       Toggle auto-approve mode (skip y/N prompts)
   ${c.cyan("/turns")} ${c.gray("<n>")}     Set max turns per prompt (default 25)
   ${c.cyan("/model")}     Show current model
+  ${c.cyan("/sessions")}  List recent saved sessions
+  ${c.cyan("/session")}   Show id + path of the current session
 
 ${c.gray("Anything else is sent to the agent as your next message.")}
 ${c.gray("Conversation history is kept across messages until you /clear.")}
 `;
 
-export async function runRepl({ cwd: initialCwd, autoYes: initialAutoYes, maxTurns: initialMaxTurns }) {
+export async function runRepl({ cwd: initialCwd, autoYes: initialAutoYes, maxTurns: initialMaxTurns, resumed }) {
   const state = {
     cwd: initialCwd,
     autoYes: !!initialAutoYes,
     maxTurns: initialMaxTurns ?? 25,
-    messages: [], // accumulates across turns
+    messages: resumed?.messages ?? [],
     balance: null,
-    sessionCredits: 0,
-    sessionIn: 0,
-    sessionOut: 0,
+    sessionCredits: resumed?.totalCredits ?? 0,
+    sessionIn: resumed?.totalIn ?? 0,
+    sessionOut: resumed?.totalOut ?? 0,
+    sessionId: resumed?.id,
+    sessionCreatedAt: resumed?.createdAt,
   };
+  if (resumed) {
+    console.log(c.gray(`\nResumed session ${c.cyan(resumed.id)} · ${state.messages.length} messages from ${new Date(resumed.lastUsedAt).toLocaleString()}\n`));
+  }
 
   // Free balance check up front. If no key configured, walk through first-time
   // setup flow (open browser → paste key → verify → save).
@@ -125,8 +133,15 @@ export async function runRepl({ cwd: initialCwd, autoYes: initialAutoYes, maxTur
       cwd: state.cwd,
       autoYes: state.autoYes,
       maxTurns: state.maxTurns,
+      sessionId: state.sessionId,
+      sessionCreatedAt: state.sessionCreatedAt,
     });
 
+    // Capture the session id from the first turn so we keep appending to it
+    if (!state.sessionId && result.sessionId) {
+      state.sessionId = result.sessionId;
+      if (!state.sessionCreatedAt) state.sessionCreatedAt = new Date().toISOString();
+    }
     state.sessionCredits += result.totalCredits ?? 0;
     state.sessionIn += result.totalIn ?? 0;
     state.sessionOut += result.totalOut ?? 0;
@@ -212,6 +227,34 @@ async function handleSlash(line, state) {
     case "model":
       console.log(c.gray(`model: ${MODEL_NAME} · 1M context · uncensored`));
       break;
+    case "sessions":
+    case "ls": {
+      const sessions = listSessions(15);
+      if (sessions.length === 0) {
+        console.log(c.gray("No saved sessions yet."));
+      } else {
+        console.log(c.bold(c.magenta("Recent sessions")) + c.gray(`  (${sessions.length})`));
+        for (const s of sessions) {
+          const when = new Date(s.lastUsedAt).toLocaleString("en-US", {
+            month: "short", day: "numeric", hour: "numeric", minute: "2-digit",
+          });
+          const mark = s.id === state.sessionId ? c.green(" ← current") : "";
+          console.log(c.cyan(s.id) + c.gray(` · ${when}`) + mark);
+          console.log(c.gray("  ") + truncatePreview(s.firstUserMessage, 64));
+        }
+        console.log(c.gray(`\nResume from shell: `) + c.cyan(`aether --resume <id>`));
+      }
+      break;
+    }
+    case "session": {
+      if (state.sessionId) {
+        console.log(c.gray(`session: `) + c.cyan(state.sessionId));
+        console.log(c.gray(`messages: ${state.messages.length}, credits this session: ${state.sessionCredits}`));
+      } else {
+        console.log(c.gray("No session id yet — send a message to create one."));
+      }
+      break;
+    }
     default:
       console.log(errorLine(`Unknown command: /${cmd}. Type ${c.cyan("/help")} for shortcuts.`));
   }

package/src/sessions.js

@@ -0,0 +1,145 @@
+// Session persistence — save conversation history to disk so users can
+// resume across invocations.
+//
+// Storage: `~/.aether/sessions/<id>.json`, one file per session.
+// Index:   `~/.aether/sessions/index.json` — a sorted list of recent sessions
+//          with metadata for `aether sessions` and `aether --resume`.
+//
+// Garbage collection: keep at most MAX_SESSIONS (50). Older files removed
+// on each save. The index reflects only live files.
+//
+// File mode 0600 — same convention as ~/.aetherrc since sessions can contain
+// pasted code, internal paths, etc.
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+const SESSIONS_DIR = path.join(os.homedir(), ".aether", "sessions");
+const INDEX_FILE = path.join(SESSIONS_DIR, "index.json");
+const MAX_SESSIONS = 50;
+
+export function sessionsDir() {
+  return SESSIONS_DIR;
+}
+
+function ensureDir() {
+  fs.mkdirSync(SESSIONS_DIR, { recursive: true });
+}
+
+/** Generate a fresh session id — local date+time, sortable. */
+export function newSessionId() {
+  const now = new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+
+/**
+ * Persist a session. Called incrementally as the agent runs.
+ *
+ * @param {object} session — { id, createdAt, lastUsedAt, cwd, model, totalCredits,
+ *                              totalIn, totalOut, firstUserMessage, messages }
+ */
+export function saveSession(session) {
+  ensureDir();
+  const file = path.join(SESSIONS_DIR, `${session.id}.json`);
+  const payload = {
+    ...session,
+    lastUsedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(file, JSON.stringify(payload, null, 2), { mode: 0o600 });
+  try { fs.chmodSync(file, 0o600); } catch { /* windows */ }
+  rebuildIndex();
+}
+
+/** Load a session by id. Returns null if not found. */
+export function loadSession(id) {
+  const file = path.join(SESSIONS_DIR, `${id}.json`);
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Load the most recent session (by lastUsedAt). Null if none. */
+export function loadMostRecent() {
+  const list = listSessions(1);
+  if (list.length === 0) return null;
+  return loadSession(list[0].id);
+}
+
+/** Delete a session by id. Returns true if it existed. */
+export function deleteSession(id) {
+  const file = path.join(SESSIONS_DIR, `${id}.json`);
+  try {
+    fs.unlinkSync(file);
+    rebuildIndex();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Return up to `limit` sessions sorted by lastUsedAt descending.
+ * Each entry is the LIGHTWEIGHT summary, not the full conversation.
+ */
+export function listSessions(limit = 20) {
+  ensureDir();
+  try {
+    const idx = JSON.parse(fs.readFileSync(INDEX_FILE, "utf8"));
+    return Array.isArray(idx) ? idx.slice(0, limit) : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Rebuild the index by reading every session file's metadata. */
+function rebuildIndex() {
+  ensureDir();
+  let files;
+  try {
+    files = fs.readdirSync(SESSIONS_DIR).filter((f) => f.endsWith(".json") && f !== "index.json");
+  } catch {
+    return;
+  }
+  const entries = [];
+  for (const f of files) {
+    try {
+      const s = JSON.parse(fs.readFileSync(path.join(SESSIONS_DIR, f), "utf8"));
+      entries.push({
+        id: s.id,
+        createdAt: s.createdAt,
+        lastUsedAt: s.lastUsedAt ?? s.createdAt,
+        cwd: s.cwd,
+        firstUserMessage: s.firstUserMessage ?? "(no message)",
+        totalCredits: s.totalCredits ?? 0,
+        messageCount: Array.isArray(s.messages) ? s.messages.length : 0,
+      });
+    } catch {
+      // Corrupt file — skip
+    }
+  }
+  // Sort by last used, descending
+  entries.sort((a, b) => (b.lastUsedAt || "").localeCompare(a.lastUsedAt || ""));
+
+  // Garbage-collect oldest sessions beyond MAX_SESSIONS
+  if (entries.length > MAX_SESSIONS) {
+    const toDelete = entries.slice(MAX_SESSIONS);
+    for (const old of toDelete) {
+      try { fs.unlinkSync(path.join(SESSIONS_DIR, `${old.id}.json`)); } catch { /* tolerate */ }
+    }
+    entries.length = MAX_SESSIONS;
+  }
+
+  fs.writeFileSync(INDEX_FILE, JSON.stringify(entries, null, 2), { mode: 0o600 });
+  try { fs.chmodSync(INDEX_FILE, 0o600); } catch { /* windows */ }
+}
+
+/** Truncate a long user message for display in the listing. */
+export function truncatePreview(text, max = 60) {
+  if (!text) return "";
+  const oneLine = text.replace(/\s+/g, " ").trim();
+  return oneLine.length > max ? oneLine.slice(0, max - 1) + "…" : oneLine;
+}