@kitfunso/aura 0.1.0

package/src/decide.js

@@ -0,0 +1,113 @@
+"use strict";
+// Pure decision core. No fs, no child processes, no Win32: hook.js owns all I/O.
+// Rules and the measurements behind them: docs/ARCHITECTURE.md.
+const path = require("path");
+
+// A tab the user named is an identity; a title an agent or a shell wrote is not,
+// and reading one of those back would feed the color its own output.
+const MAX_WINDOW_NAME = 40;
+// Every terminal ships these, so they name a shell, never a project.
+const DEFAULT_TITLES = [
+  "windows powershell", "powershell", "pwsh", "command prompt", "cmd", "cmd.exe",
+  "windows terminal", "git bash", "bash", "sh", "zsh", "node", "ubuntu", "wsl",
+];
+
+function usableWindowTitle(raw) {
+  const name = String(raw == null ? "" : raw).replace(/[\u0000-\u001f]+/g, " ").trim();
+  if (!name || name.length > MAX_WINDOW_NAME || name.indexOf("\u00b7") !== -1) return null;
+  // A separator or a drive colon means a shell wrote the path in; a name has neither.
+  if (name.indexOf("/") !== -1 || name.indexOf(":") !== -1) return null;
+  return DEFAULT_TITLES.indexOf(name.toLowerCase()) === -1 ? name : null;
+}
+
+// Identity precedence: origin remote URL > repo root path > window title > cwd.
+// isRepo stays literal; hasColor is the question every caller actually asks.
+function identityFrom({ gitCombined, remoteUrl, cwd, windowTitle }) {
+  if (!gitCombined) {
+    const named = usableWindowTitle(windowTitle);
+    // Namespaced so a tab called "aura" cannot land on the aura repo's color.
+    if (named) {
+      return { repoId: "window:" + named, branch: null, name: named, isRepo: false, hasColor: true, fromWindowTitle: true, root: null };
+    }
+    const normalized = path.resolve(cwd);
+    return { repoId: normalized, branch: null, name: path.basename(normalized), isRepo: false, hasColor: false, fromWindowTitle: false, root: null };
+  }
+  const lines = gitCombined.split(/\r?\n/);
+  const root = lines[0];
+  // "HEAD" means unborn (no commits yet) or detached: a repo, with no branch.
+  const branch = lines[1] && lines[1] !== "HEAD" ? lines[1] : null;
+  return { repoId: remoteUrl || root, branch, name: path.basename(root), isRepo: true, hasColor: true, fromWindowTitle: false, root };
+}
+
+// A name holds still; an agent's title follows the prompt. So a title becomes an
+// identity only once two prompts have read it the same.
+function settleWindowName(probe, found) {
+  if (found && probe === undefined) return { probe: found, name: null };
+  return { probe: null, name: found && found === probe ? found : "" };
+}
+
+// "prompt" is the shell caller's name for the same thing: the window is already
+// up, so there is no TUI init race to wait out.
+function isPromptEvent(eventName) {
+  return eventName === "UserPromptSubmit" || eventName === "prompt";
+}
+
+// Proof the session runs in a terminal the user launched; headless runs set none.
+const TERMINAL_MARKERS = ["WT_SESSION", "WEZTERM_PANE", "ALACRITTY_WINDOW_ID", "GHOSTTY_RESOURCES_DIR"];
+
+function hasTerminalMarker(env) {
+  return TERMINAL_MARKERS.some(function (name) { return Boolean(env[name]); });
+}
+
+// Tabs share one window frame, so ownership is a property of the window.
+function coloredSessionHwnds(sessions, exceptSessionId) {
+  const hwnds = [];
+  Object.keys(sessions || {}).forEach(function (id) {
+    const session = sessions[id];
+    if (id !== exceptSessionId && session && session.hasColor === true && session.hwnd) {
+      const key = String(session.hwnd);
+      if (hwnds.indexOf(key) === -1) hwnds.push(key);
+    }
+  });
+  return hwnds;
+}
+
+function windowHasColoredSession(sessions, hwnd, exceptSessionId) {
+  if (!hwnd) return false;
+  return coloredSessionHwnds(sessions, exceptSessionId).indexOf(String(hwnd)) !== -1;
+}
+
+function decideEvent({ eventName, platform, session, frameHex, vtSignature, hasColor, windowFrameCleared }) {
+  const isPrompt = isPromptEvent(eventName);
+  // A session start may land in a new tab or window, so it re-handshakes.
+  const clearHandshake = !isPrompt;
+  const cachedVtSent = clearHandshake ? undefined : session.vtSent;
+  const needsVtDelivery = platform === "win32" && cachedVtSent !== vtSignature;
+  // The start-time window is a guess (the user may be looking elsewhere); the
+  // first prompt proves which window is theirs, and already spawns for VT.
+  const reresolveWindow = isPrompt && needsVtDelivery;
+  const cachedHwnd = (clearHandshake || reresolveWindow) ? null : session.hwnd || null;
+  // A bare shell in the window may have cleared the color this session owns.
+  const reclaimFrame = hasColor && Boolean(windowFrameCleared);
+  // With no identity the frame resets once, so a window aura colored earlier goes back.
+  const needsReset = !hasColor && !(clearHandshake ? false : session.frameCleared);
+  const needsFrame = !cachedHwnd || session.frameHex !== frameHex || reclaimFrame || needsReset;
+  return {
+    isPrompt,
+    clearHandshake,
+    cachedHwnd,
+    spawnAdapter: needsFrame || needsVtDelivery,
+    // An immediate start-time write races Claude Code's TUI init and is wiped.
+    vtDelayMs: isPrompt ? 0 : 2000,
+    markVtSent: isPrompt && needsVtDelivery,
+    // No repo and no tab name: the window keeps the terminal's own default.
+    paintsFrame: hasColor,
+    resetFrame: !hasColor,
+    usesColor: hasColor,
+  };
+}
+
+module.exports = {
+  identityFrom, usableWindowTitle, settleWindowName, isPromptEvent, decideEvent,
+  hasTerminalMarker, windowHasColoredSession, coloredSessionHwnds,
+};

package/src/git.js

@@ -0,0 +1,39 @@
+"use strict";
+// The git probe. Lives outside hook.js so tests can drive it against real repos.
+const { execFileSync } = require("child_process");
+const { identityFrom } = require("./decide.js");
+
+// The output decides, never the exit code: rev-parse exits 128 on a repo with
+// no commits yet, but still prints a valid toplevel on stdout.
+function runGit(cwd, args) {
+  try {
+    return execFileSync("git", ["-C", cwd].concat(args), {
+      timeout: 1500,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).toString().trim() || null;
+  } catch (err) {
+    const partial = err && err.stdout ? err.stdout.toString().trim() : "";
+    return partial || null;
+  }
+}
+
+// One git spawn on the hot path; the remote URL is cached per repo root.
+function resolveIdentity(cwd, state, recheckNullRemote, windowTitle) {
+  const combined = runGit(cwd, ["rev-parse", "--show-toplevel", "--abbrev-ref", "HEAD"]);
+  let remoteUrl = null;
+  if (combined) {
+    const root = combined.split(/\r?\n/)[0];
+    const remotes = state.remotes || (state.remotes = {});
+    // Recheck nulls at session start only: a repo that gains an origin remote
+    // must stop using its path color, but the prompt path stays at one spawn.
+    if (!(root in remotes) || (recheckNullRemote && remotes[root] === null)) {
+      remotes[root] = runGit(cwd, ["config", "--get", "remote.origin.url"]);
+    }
+    remoteUrl = remotes[root];
+  }
+  // The caller persists remoteUrl under root: without it every prompt pays a
+  // second git spawn to re-learn the same URL.
+  return Object.assign(identityFrom({ gitCombined: combined, remoteUrl, cwd, windowTitle }), { remoteUrl });
+}
+
+module.exports = { runGit, resolveIdentity };

package/src/hook.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+"use strict";
+// aura hook entry, fired by Claude Code on SessionStart and UserPromptSubmit.
+// Never blocks a prompt (rule 6) and never writes escapes to stdout (rule 3),
+// which is why the sink here is the tty device. Design: docs/ARCHITECTURE.md.
+const fs = require("fs");
+const { mark } = require("./mark.js");
+const { writeToTerminal } = require("./tty.js");
+
+function main() {
+  let raw = "";
+  try { raw = fs.readFileSync(0, "utf8"); } catch (err) { /* no stdin */ }
+  let event = {};
+  try { event = JSON.parse(raw); } catch (err) { /* not JSON */ }
+
+  mark({
+    cwd: event.cwd || process.cwd(),
+    sessionId: event.session_id || "unknown",
+    eventName: event.hook_event_name,
+    promptText: event.prompt,
+    sink: writeToTerminal,
+    // On Windows this write lands in the hook's own hidden console, so the
+    // adapter has to repeat the escapes into the tab's real console.
+    redeliverVt: true,
+  });
+}
+
+try { main(); } catch (err) { /* rule 6: fail silent */ }
+process.exit(0);

package/src/install.js

@@ -0,0 +1,158 @@
+"use strict";
+// Wires aura into the two things that can call it: Claude Code's hooks, and a
+// shell profile. Rule 4: back up first, merge, NEVER overwrite. Flags:
+// --settings <path>, --shell <name>, --profile <path>.
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const { shellSnippet, SHELLS } = require("./shell/init.js");
+
+function argValue(flag) {
+  const index = process.argv.indexOf(flag);
+  return index !== -1 && process.argv[index + 1] ? process.argv[index + 1] : null;
+}
+
+const SETTINGS_FILE = argValue("--settings") || path.join(os.homedir(), ".claude", "settings.json");
+const HOOK_EVENTS = ["SessionStart", "UserPromptSubmit"];
+const BLOCK_OPEN = "# >>> aura >>>";
+const BLOCK_CLOSE = "# <<< aura <<<";
+
+// Forward slashes work in every shell Claude Code uses to run hook commands.
+const hookScript = path.resolve(__dirname, "hook.js").replace(/\\/g, "/");
+const hookCommand = 'node "' + hookScript + '"';
+const cli = path.resolve(__dirname, "..", "bin", "aura.js");
+
+function backUpOnce(file, raw) {
+  // Only the first run writes the backup: it holds the pre-aura content.
+  if (!fs.existsSync(file + ".aura-bak")) fs.writeFileSync(file + ".aura-bak", raw);
+}
+
+function writeAtomic(file, contents) {
+  // A crash mid-write must never truncate the file we were asked to preserve.
+  const tmp = file + ".aura-tmp";
+  fs.writeFileSync(tmp, contents);
+  fs.renameSync(tmp, file);
+}
+
+function isAuraGroup(group) {
+  return Array.isArray(group.hooks) && group.hooks.some(function (h) {
+    return typeof h.command === "string" && h.command.indexOf("aura/src/hook.js") !== -1;
+  });
+}
+
+function installHooks(uninstall) {
+  if (!fs.existsSync(SETTINGS_FILE)) {
+    console.error("aura: " + SETTINGS_FILE + " not found. Is Claude Code installed?");
+    process.exit(1);
+  }
+  const raw = fs.readFileSync(SETTINGS_FILE, "utf8");
+  let settings;
+  try {
+    settings = JSON.parse(raw);
+  } catch (err) {
+    console.error("aura: " + SETTINGS_FILE + " is not valid JSON; refusing to touch it.");
+    process.exit(1);
+  }
+  backUpOnce(SETTINGS_FILE, raw);
+
+  if (!settings.hooks || typeof settings.hooks !== "object") settings.hooks = {};
+  let changed = false;
+  for (const eventName of HOOK_EVENTS) {
+    const groups = Array.isArray(settings.hooks[eventName]) ? settings.hooks[eventName] : [];
+    const hasAura = groups.some(isAuraGroup);
+    if (uninstall && hasAura) {
+      settings.hooks[eventName] = groups.filter(function (g) { return !isAuraGroup(g); });
+      changed = true;
+    } else if (!uninstall && !hasAura) {
+      groups.push({ hooks: [{ type: "command", command: hookCommand }] });
+      settings.hooks[eventName] = groups;
+      changed = true;
+    }
+  }
+
+  if (changed) writeAtomic(SETTINGS_FILE, JSON.stringify(settings, null, 2) + "\n");
+  const action = uninstall ? "removed from" : "installed into";
+  console.log("aura: " + (changed ? action : "no change needed in") + " " + SETTINGS_FILE);
+  console.log("aura: backup at " + SETTINGS_FILE + ".aura-bak");
+  if (changed && !uninstall) {
+    console.log("aura: colors appear in NEW Claude Code sessions (existing sessions keep their old hook config).");
+  }
+}
+
+function powershellProfile() {
+  // PowerShell knows where its own profile is; Documents is often redirected.
+  const out = execFileSync("powershell.exe",
+    ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", "$PROFILE"]).toString().trim();
+  if (!out) throw new Error("powershell.exe did not report a profile path");
+  return out;
+}
+
+function profileFor(shell) {
+  const explicit = argValue("--profile");
+  if (explicit) return explicit;
+  if (shell === "powershell") return powershellProfile();
+  if (shell === "zsh") return path.join(os.homedir(), ".zshrc");
+  return path.join(os.homedir(), ".bashrc");
+}
+
+function withoutAuraBlock(text) {
+  const open = text.indexOf(BLOCK_OPEN);
+  if (open === -1) return text;
+  const close = text.indexOf(BLOCK_CLOSE, open);
+  if (close === -1) return text;
+  const before = text.slice(0, open).replace(/\n+$/, "");
+  const after = text.slice(close + BLOCK_CLOSE.length).replace(/^\n+/, "");
+  if (!before) return after;
+  if (!after) return before + "\n";
+  return before + "\n\n" + after;
+}
+
+function installShell(shell, uninstall) {
+  let file;
+  try {
+    file = profileFor(shell);
+  } catch (err) {
+    console.error("aura: could not find the " + shell + " profile. Pass --profile <path>.");
+    process.exit(1);
+  }
+  const existed = fs.existsSync(file);
+  if (!existed && uninstall) {
+    console.log("aura: no change needed in " + file);
+    return;
+  }
+  const raw = existed ? fs.readFileSync(file, "utf8") : "";
+  if (existed) backUpOnce(file, raw);
+
+  const stripped = withoutAuraBlock(raw);
+  let next = stripped;
+  if (!uninstall) {
+    const snippet = shellSnippet(shell, cli);
+    const block = BLOCK_OPEN + "\n" + snippet.replace(/\n+$/, "") + "\n" + BLOCK_CLOSE + "\n";
+    next = stripped ? stripped.replace(/\n*$/, "\n\n") + block : block;
+  }
+  if (next === raw) {
+    console.log("aura: no change needed in " + file);
+    return;
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  writeAtomic(file, next);
+  console.log("aura: " + (uninstall ? "removed from " : "installed into ") + file);
+  if (existed) console.log("aura: backup at " + file + ".aura-bak");
+  if (!uninstall) console.log("aura: colors appear in NEW shells. Open a terminal in a repo to see it.");
+}
+
+function run(uninstall) {
+  const shell = argValue("--shell");
+  if (shell) {
+    if (SHELLS.indexOf(shell) === -1) {
+      console.error("aura: unknown shell " + shell + ". Known: " + SHELLS.join(", "));
+      process.exit(1);
+    }
+    installShell(shell, uninstall);
+    return;
+  }
+  installHooks(uninstall);
+}
+
+module.exports = { run };

package/src/mark.js

@@ -0,0 +1,214 @@
+"use strict";
+// The whole colouring operation, with no opinion about who called it. Callers
+// differ only in where the escapes go and whether the adapter must repeat them.
+// Rules and measurements: docs/ARCHITECTURE.md.
+const path = require("path");
+const { execFileSync } = require("child_process");
+const { colorsFor, fnv1a } = require("./color.js");
+const {
+  identityFrom, usableWindowTitle, settleWindowName, isPromptEvent, decideEvent,
+  hasTerminalMarker, windowHasColoredSession, coloredSessionHwnds,
+} = require("./decide.js");
+const { resolveIdentity } = require("./git.js");
+const { readState, updateState, stateFile } = require("./state.js");
+
+const ESC = "\u001b";
+const BEL = "\u0007";
+const PROMPT_SNIPPET_LEN = 60;
+// Palette slot redefined to carry the tab RGB, then selected with DECAC. It sits
+// above 255 so aura never repaints an index text can be printed in.
+const TAB_COLOR_SLOT = 264;
+
+// Prompt text lands inside an escape sequence: strip control bytes so it can
+// never terminate or inject a sequence of its own.
+function sanitizeForTitle(text) {
+  return String(text).replace(/[\u0000-\u001f]+/g, " ").replace(/\s+/g, " ").trim();
+}
+
+function buildEscapes(colors, title, usesColor, env) {
+  if (!usesColor) return title ? `${ESC}]0;${title}${BEL}` : "";
+  let out = `${ESC}]11;${colors.tintHex}${BEL}`;
+  const hex = colors.frameHex;
+  if (env.WT_SESSION) {
+    const r = hex.slice(1, 3);
+    const g = hex.slice(3, 5);
+    const b = hex.slice(5, 7);
+    out += `${ESC}]4;${TAB_COLOR_SLOT};rgb:${r}/${g}/${b}${BEL}`;
+    out += `${ESC}[2;15;${TAB_COLOR_SLOT},|`;
+  } else if (env.TERM_PROGRAM === "iTerm.app") {
+    const r = parseInt(hex.slice(1, 3), 16);
+    const g = parseInt(hex.slice(3, 5), 16);
+    const b = parseInt(hex.slice(5, 7), 16);
+    out += `${ESC}]6;1;bg;red;brightness;${r}${BEL}`;
+    out += `${ESC}]6;1;bg;green;brightness;${g}${BEL}`;
+    out += `${ESC}]6;1;bg;blue;brightness;${b}${BEL}`;
+  }
+  if (title) out += `${ESC}]0;${title}${BEL}`;
+  return out;
+}
+
+// The tab's own name, read through the same allowlist the frame paint uses. The
+// cached handle is preferred: the foreground window may belong to another tab.
+function queryWindowTitle(env, cachedHwnd) {
+  if (process.platform !== "win32") return null;
+  if (!cachedHwnd && !hasTerminalMarker(env)) return null;
+  const adapter = path.join(__dirname, "adapters", "frame-win.ps1");
+  const args = [
+    "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", adapter,
+    "-FrameColor", "000000", "-QueryTitle",
+  ];
+  if (cachedHwnd) args.push("-Hwnd", String(cachedHwnd));
+  try {
+    return execFileSync("powershell.exe", args, {
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
+    }).toString().trim() || null;
+  } catch (err) {
+    return null;
+  }
+}
+
+function paintFrame(frameHex, cachedHwnd, vtPayload, vtDelay, mode, env) {
+  if (process.platform !== "win32") return null;
+  // Without a terminal marker this is a headless run, where the foreground
+  // window belongs to some unrelated app. A cached handle is always safe.
+  if (!cachedHwnd && !hasTerminalMarker(env)) return null;
+  const adapter = path.join(__dirname, "adapters", "frame-win.ps1");
+  const args = [
+    "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", adapter,
+    "-FrameColor", frameHex.slice(1),
+  ];
+  if (cachedHwnd) args.push("-Hwnd", String(cachedHwnd));
+  // Resolve the handle without writing a color a repo sibling may own.
+  if (mode.name !== "paint") args.push("-NoPaint");
+  if (mode.name === "reset") {
+    args.push("-Reset");
+    if (mode.skipHwnds.length) args.push("-SkipHwnds", mode.skipHwnds.join(","));
+  }
+  if (vtPayload) {
+    args.push("-VtB64", Buffer.from(vtPayload, "utf8").toString("base64"));
+    if (vtDelay) {
+      args.push("-VtDelayMs", String(vtDelay.ms));
+      args.push("-StateFile", stateFile());
+      args.push("-SessionId", vtDelay.sessionId);
+      args.push("-VtSig", vtDelay.sig);
+    }
+  }
+  try {
+    const out = execFileSync("powershell.exe", args, {
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
+    }).toString().trim();
+    const hwnd = parseInt(out, 10);
+    return Number.isFinite(hwnd) && hwnd > 0 ? hwnd : null;
+  } catch (err) {
+    return null;
+  }
+}
+
+// sink writes the escapes and returns a label for state. redeliverVt: the
+// caller's console is hidden, so the adapter repeats them into the real one.
+function mark({
+  cwd, sessionId, eventName, promptText, env = process.env,
+  sink = () => null, redeliverVt = true,
+}) {
+  // Only a snapshot for identity and the decision; nothing here reaches disk.
+  const state = readState() || { sessions: {} };
+  // A tag outranks cwd, which carries no project when an agent was launched
+  // from a home folder.
+  const pinned = (state.tags || {})[sessionId];
+  const session = state.sessions[sessionId] || {};
+  // A tag is an explicit answer, so a tagged session never reads its tab name.
+  const windowName = pinned ? null : session.windowName || null;
+  let identity = resolveIdentity(pinned || cwd, state, eventName === "SessionStart", windowName);
+  if (!identity.hasColor && !pinned && session.windowName === undefined && isPromptEvent(eventName)) {
+    const found = usableWindowTitle(queryWindowTitle(env, session.hwnd));
+    const settled = settleWindowName(session.windowProbe, found);
+    if (settled.probe) session.windowProbe = settled.probe;
+    else {
+      delete session.windowProbe;
+      session.windowName = settled.name;
+    }
+    // git already answered null here, so the name settles it with no second spawn.
+    if (session.windowName) identity = identityFrom({ gitCombined: null, cwd, windowTitle: session.windowName });
+  }
+  const colors = colorsFor({ repoId: identity.repoId, branch: identity.branch });
+
+  const titleParts = [identity.name];
+  if (identity.branch) titleParts.push(identity.branch);
+  if (promptText) titleParts.push(sanitizeForTitle(promptText).slice(0, PROMPT_SNIPPET_LEN));
+  // Writing a title over an identity we READ from that title renames it, and
+  // the rename would move the color on the next prompt.
+  const title = identity.fromWindowTitle ? "" : titleParts.join(" · ");
+  const escapes = buildEscapes(colors, title, identity.hasColor, env);
+  // The signature covers what was delivered, not just its color, so any change
+  // to the escapes re-delivers. The title is out: it moves every prompt.
+  const vtSignature = fnv1a(buildEscapes(colors, "", identity.hasColor, env)).toString(36);
+
+  // A caller that writes to a visible console has already delivered them, so
+  // caching here is what keeps the adapter off that caller's prompt path.
+  if (!redeliverVt) session.vtSent = vtSignature;
+  session.tty = sink(escapes);
+
+  const owners = state.frameOwner || {};
+  const plan = decideEvent({
+    eventName,
+    platform: process.platform,
+    session,
+    frameHex: colors.frameHex,
+    vtSignature,
+    hasColor: identity.hasColor,
+    windowFrameCleared: Boolean(session.hwnd && owners[String(session.hwnd)] === "cleared"),
+  });
+  if (plan.clearHandshake) {
+    delete session.hwnd;
+    delete session.vtSent;
+    delete session.frameCleared;
+  }
+  let painted = false;
+  let cleared = false;
+  if (plan.spawnAdapter) {
+    const vtDelay = plan.vtDelayMs > 0 ? { ms: plan.vtDelayMs, sessionId, sig: vtSignature } : null;
+    // The adapter re-checks the list: the window it resolves may not be cached yet.
+    const mode = plan.paintsFrame ? { name: "paint" }
+      : plan.resetFrame ? { name: "reset", skipHwnds: coloredSessionHwnds(state.sessions, sessionId) }
+      : { name: "none" };
+    const payload = redeliverVt ? escapes : null;
+    const hwnd = paintFrame(colors.frameHex, plan.cachedHwnd, payload, vtDelay, mode, env);
+    if (hwnd) {
+      session.hwnd = hwnd;
+      // Ownership follows the color write, not the handle lookup.
+      painted = plan.paintsFrame;
+      cleared = mode.name === "reset" &&
+        !windowHasColoredSession(state.sessions, hwnd, sessionId);
+      if (cleared) session.frameCleared = true;
+      if (plan.markVtSent && redeliverVt) session.vtSent = vtSignature;
+    }
+  }
+  session.repoId = identity.repoId;
+  session.branch = identity.branch;
+  // repoId is a path either way, so it cannot tell a colored session from a bare one.
+  session.isRepo = identity.isRepo;
+  session.hasColor = identity.hasColor;
+  session.frameHex = colors.frameHex;
+  if (promptText) session.lastPrompt = sanitizeForTitle(promptText).slice(0, 200);
+  session.updatedAt = new Date().toISOString();
+  // Only this session's entry is ours to write; the rest of the file belongs
+  // to concurrent shells, so the delta goes onto a fresh read under a lock.
+  updateState(function (fresh) {
+    fresh.sessions[sessionId] = session;
+    if (identity.root) (fresh.remotes || (fresh.remotes = {}))[identity.root] = identity.remoteUrl;
+    // Ownership is keyed by HWND, because tabs share one frame.
+    if (session.hwnd && process.platform === "win32") {
+      const freshOwners = fresh.frameOwner || (fresh.frameOwner = {});
+      const hwndKey = String(session.hwnd);
+      if (painted) freshOwners[hwndKey] = sessionId;
+      else if (cleared) freshOwners[hwndKey] = "cleared";
+    }
+  });
+  return { identity, colors, escapes, hwnd: session.hwnd || null };
+}
+
+module.exports = { mark, buildEscapes, sanitizeForTitle };

package/src/shell/init.js

@@ -0,0 +1,16 @@
+"use strict";
+// The snippets next to this file are data with one hole in them: the path of
+// the CLI the shell should call. Both callers know it from their own location.
+const fs = require("fs");
+const path = require("path");
+
+const SNIPPETS = { powershell: "powershell.ps1", bash: "posix.sh", zsh: "posix.sh" };
+
+function shellSnippet(shell, cliPath) {
+  if (!SNIPPETS[shell]) return null;
+  const text = fs.readFileSync(path.join(__dirname, SNIPPETS[shell]), "utf8");
+  // Forward slashes work in every shell these snippets target.
+  return text.replace(/__AURA_CLI__/g, cliPath.replace(/\\/g, "/"));
+}
+
+module.exports = { shellSnippet, SHELLS: Object.keys(SNIPPETS) };

package/src/shell/posix.sh

@@ -0,0 +1,33 @@
+# Appends to the prompt hook instead of replacing it, so an existing
+# PROMPT_COMMAND or precmd keeps running. Emitted by "aura shell-init".
+AURA_CLI="__AURA_CLI__"
+
+# Start second, because pids are recycled well inside the 48h state window.
+if [ -z "$AURA_SESSION" ]; then
+  AURA_SESSION="shell-$$-$(date +%s)"
+fi
+# Exported so an agent started here tags the window's own session, not its pid.
+export AURA_SESSION
+AURA_LAST_PATH=""
+
+aura_mark_cwd() {
+  # Rule 6: a broken aura must never break a prompt.
+  [ "$PWD" = "$AURA_LAST_PATH" ] && return 0
+  AURA_LAST_PATH="$PWD"
+  aura_out=$(command node "$AURA_CLI" mark --write --cwd "$PWD" --session "$AURA_SESSION" 2>/dev/null)
+  [ -n "$aura_out" ] && printf '%s' "$aura_out"
+  return 0
+}
+
+if [ -n "$ZSH_VERSION" ]; then
+  case " ${precmd_functions[*]} " in
+    *" aura_mark_cwd "*) ;;
+    *) precmd_functions+=(aura_mark_cwd) ;;
+  esac
+elif [ -n "$BASH_VERSION" ]; then
+  case "$PROMPT_COMMAND" in
+    *aura_mark_cwd*) ;;
+    "") PROMPT_COMMAND="aura_mark_cwd" ;;
+    *) PROMPT_COMMAND="aura_mark_cwd;$PROMPT_COMMAND" ;;
+  esac
+fi

package/src/shell/powershell.ps1

@@ -0,0 +1,33 @@
+# Wraps the current prompt instead of replacing it, so posh-git, oh-my-posh and
+# Starship keep working. Emitted by "aura shell-init", which fills the CLI path.
+$global:AuraCli = "__AURA_CLI__"
+
+# Start second, because Windows recycles pids well inside the 48h state window.
+if (-not $global:AuraSession) {
+    if ($env:AURA_SESSION) {
+        $global:AuraSession = $env:AURA_SESSION
+    } else {
+        $global:AuraSession = "shell-" + $PID + "-" + [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
+    }
+}
+# Exported so an agent started here tags the window's own session, not its pid.
+$env:AURA_SESSION = $global:AuraSession
+
+# Re-wrap when something else took the prompt; a plain re-source is a no-op.
+if ($null -eq $function:prompt -or $function:prompt.ToString() -notmatch 'aura-prompt') {
+    $global:AuraPrevPrompt = $function:prompt
+    $global:AuraLastPath = ""
+}
+
+function global:prompt {
+    # aura-prompt
+    try {
+        $auraPath = $PWD.ProviderPath
+        if ($auraPath -ne $global:AuraLastPath) {
+            $global:AuraLastPath = $auraPath
+            $auraOut = & node $global:AuraCli mark --write --cwd $auraPath --session $global:AuraSession
+            if ($auraOut) { [Console]::Write(($auraOut -join "")) }
+        }
+    } catch { }
+    if ($global:AuraPrevPrompt) { & $global:AuraPrevPrompt } else { "PS " + $PWD.ProviderPath + "> " }
+}