@jlongo78/agent-spaces 0.9.7 → 0.9.9

package/.next/standalone/bin/spaces.js

@@ -58,7 +58,7 @@ setInterval(() => logMemory(), 60000);
 const SPACES_DIR = path.join(os.homedir(), '.spaces');
 const CONFIG_PATH = path.join(SPACES_DIR, 'server.json');
 const SESSION_SECRET_PATH = path.join(SPACES_DIR, 'session_secret');
-const NEXT_INTERNAL_PORT = 3400;
+let NEXT_INTERNAL_PORT = 3400;
 const projectDir = path.join(__dirname, '..');
 const MANAGED_PACKAGES = path.join(SPACES_DIR, 'packages');
 const MANAGED_NODE_MODULES = path.join(MANAGED_PACKAGES, 'node_modules');
@@ -227,8 +227,11 @@ function startServer() {
     || savedConfig.allowedOrigins
     || '';
 
+  // Use a unique internal port so multiple instances don't collide
+  NEXT_INTERNAL_PORT = PORT - 57; // 3457→3400, 3458→3401, etc.
+
   // ─── Kill any existing server on this port ───────────────────
-  stopServer();
+  stopServer(PORT);
 
   // ─── Resolve optional packages once ─────────────────────────
   const proPath = resolveSpacesPro();
@@ -704,12 +707,12 @@ function findPidsOnPort(port) {
   return [...pids].filter(p => !isNaN(p) && p > 0);
 }
 
-function stopServer() {
+function stopServer(overridePort) {
   let savedConfig = {};
   if (fs.existsSync(CONFIG_PATH)) {
     try { savedConfig = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8')); } catch {}
   }
-  const port = parseInt(process.env.SPACES_PORT || '', 10) || savedConfig.port || 3457;
+  const port = overridePort || parseInt(process.env.SPACES_PORT || '', 10) || savedConfig.port || 3457;
   const ports = [port, NEXT_INTERNAL_PORT];
   let killed = 0;
 

package/.next/standalone/bin/terminal-server.js

@@ -479,7 +479,7 @@ const AGENTS = {
   gemini: { command: 'gemini', resumeFlag: '--resume', resumeStyle: 'flag' },
   aider:  { command: 'aider',  resumeFlag: '',         resumeStyle: '' },
   forge:  { command: 'forge',  resumeFlag: '--cid',    resumeStyle: 'flag' },
-  pi:     { command: 'pi',    resumeFlag: '--continue', resumeStyle: 'bare' },
+  pi:     { command: 'pi',    resumeFlag: '--session', resumeStyle: 'flag' },
   custom: { command: '',       resumeFlag: '',         resumeStyle: '' },
 };
 
@@ -1441,6 +1441,14 @@ function handleConnection(wss, ws, req) {
   // Check for existing session to reattach
   const existing = sessions.get(paneId);
   if (existing && existing.pty && !existing.exited) {
+    // SECURITY: only the original owner may reattach. Without this, any
+    // authenticated user who learns a paneId could hijack another user's PTY.
+    if (existing.username !== username) {
+      console.log(`[WS] REJECTED reattach pane=${paneId.slice(0,8)} — owner=${existing.username} requester=${username}`);
+      ws.send(JSON.stringify({ type: 'error', data: 'Pane belongs to a different user' }));
+      ws.close();
+      return;
+    }
     console.log(`[WS] Reattach pane=${paneId.slice(0,8)} buffer=${existing.buffer.length} chunks`);
     existing.ws = ws;
 
@@ -1732,15 +1740,22 @@ function handleConnection(wss, ws, req) {
 
       if (agentSession && agentSession !== 'new' && agent.resumeFlag) {
         // Resume an existing session
-        if (agentType === 'claude') {
-          // Claude needs to be run from the correct project CWD
-          const sessionCwd = findSessionCwd(agentSession, username);
-
-          // Verify the session actually exists on disk before attempting resume.
-          // If the .jsonl file is gone (cleanup, etc.), fall back to `--continue`
-          // which resumes the most recent conversation in this project — much
-          // better than starting completely fresh.
-          const sessionExists = sessionCwd !== null || findSessionFile(agentSession, username);
+        if (agentType === 'claude' || agentType === 'pi') {
+          let sessionCwd = null;
+          let sessionExists = false;
+
+          if (agentType === 'claude') {
+            // Claude needs to be run from the correct project CWD
+            sessionCwd = findSessionCwd(agentSession, username);
+
+            // Verify the session actually exists on disk before attempting resume.
+            // If the .jsonl file is gone (cleanup, etc.), fall back to `--continue`
+            // which resumes the most recent conversation in this project — much
+            // better than starting completely fresh.
+            sessionExists = sessionCwd !== null || findSessionFile(agentSession, username);
+          } else if (agentType === 'pi') {
+            sessionExists = findPiSessionFile(agentSession, username, safeCwd);
+          }
 
           if (!sessionExists) {
             console.log(`[Resume] Session ${agentSession.slice(0, 8)} not found on disk for pane ${paneId.slice(0, 8)} — falling back to --continue`);
@@ -1915,6 +1930,29 @@ function findSessionFile(sessionId, username) {
   return false;
 }
 
+function findPiSessionFile(sessionId, username, cwd) {
+  const homeDir = getUserHome(username);
+  const globalSessionsDir = path.join(homeDir, '.pi', 'agent', 'sessions');
+  const projectSessionsDir = path.join(cwd, '.pi', 'sessions');
+
+  for (const dir of [globalSessionsDir, projectSessionsDir]) {
+    try {
+      if (fs.existsSync(dir)) {
+        for (const sub of fs.readdirSync(dir, { withFileTypes: true })) {
+          if (sub.isDirectory()) {
+            for (const file of fs.readdirSync(path.join(dir, sub.name))) {
+              if (file.endsWith('.jsonl') && file.includes(sessionId)) return true;
+            }
+          } else if (sub.isFile() && sub.name.endsWith('.jsonl') && sub.name.includes(sessionId)) {
+            return true;
+          }
+        }
+      }
+    } catch { /* ignore */ }
+  }
+  return false;
+}
+
 function findSessionCwd(sessionId, username) {
   const claudeProjectsDir = path.join(getUserHome(username), '.claude', 'projects');
   try {

package/.next/standalone/cortex-hook-debug.log

@@ -1,23 +1,118 @@
-[2026-04-07T14:23:08.558Z] Hook started
-[2026-04-07T14:23:08.569Z] Input length: 380
-[2026-04-07T14:23:08.569Z] Querying: http://localhost:3457/api/cortex/context/?q=it%20looks%20like%20we're%20using%20a%20ton%20of%20resources%20on%20this%20vm.%20%20what%20are%20the%20culprits%3F&limit=5&workspace_id=8 (event: UserPromptSubmit)
-[2026-04-07T14:23:08.614Z] Main error: 307
-[2026-04-07T14:23:08.614Z] Hook finished
-[2026-04-07T14:23:39.205Z] Hook started
-[2026-04-07T14:23:39.217Z] Input length: 398
-[2026-04-07T14:23:39.217Z] Querying: http://localhost:3457/api/cortex/context/?q=I%20installed%20the%20latest%20from%20npm%2C%20verified%20it%20says%200.9.5%20in%20settings%2C%20and%20I%20still%20can't%20copy%2Fpaste.&limit=5&workspace_id=8 (event: UserPromptSubmit)
-[2026-04-07T14:23:39.568Z] Success: Context found
-[2026-04-07T14:23:39.568Z] Hook finished
-[2026-04-07T14:24:06.849Z] [LEARN] Learn hook started
-[2026-04-07T14:24:06.856Z] [LEARN] Input length: 1826
-[2026-04-07T14:24:06.857Z] [LEARN] Sending POST to http://localhost:3457/api/cortex/knowledge/
-[2026-04-07T14:24:06.888Z] [LEARN] Response: 307
-[2026-04-07T14:25:55.152Z] Hook started
-[2026-04-07T14:25:55.164Z] Input length: 342
-[2026-04-07T14:25:55.164Z] Querying: http://localhost:3457/api/cortex/context/?q=kill%20that%20power-flow-sim-backend%20container&limit=5&workspace_id=8 (event: UserPromptSubmit)
-[2026-04-07T14:25:55.206Z] Main error: 307
-[2026-04-07T14:25:55.206Z] Hook finished
-[2026-04-07T14:26:41.638Z] [LEARN] Learn hook started
-[2026-04-07T14:26:41.646Z] [LEARN] Input length: 416
-[2026-04-07T14:26:41.650Z] [LEARN] Sending POST to http://localhost:3457/api/cortex/knowledge/
-[2026-04-07T14:26:41.691Z] [LEARN] Response: 307
+[2026-04-17T18:44:07.219Z] [LEARN] Learn hook started
+[2026-04-17T18:44:07.226Z] [LEARN] Input length: 857
+[2026-04-17T18:44:07.236Z] [LEARN] Sending POST to http://localhost:3457/api/cortex/knowledge/
+[2026-04-17T18:44:07.274Z] [LEARN] Response: 307
+[2026-04-17T18:45:18.172Z] Hook started
+[2026-04-17T18:45:18.178Z] Input length: 423
+[2026-04-17T18:45:18.179Z] Querying: http://localhost:3457/api/cortex/context/?q=tell%20me%20how%20the%20project%20wizard%20%20harness%20works%20from%20a%20high%20level.%20%20i%20need%20to%20talk%20about%20the%20functionality%20for%20another%20project%20i'm%20working%20on&limit=5&workspace_id=2 (event: UserPromptSubmit)
+[2026-04-17T18:45:18.212Z] Main error: 307
+[2026-04-17T18:45:18.212Z] Hook finished
+[2026-04-17T18:45:37.672Z] [LEARN] Learn hook started
+[2026-04-17T18:45:37.681Z] [LEARN] Input length: 3392
+[2026-04-17T18:45:37.688Z] [LEARN] Sending POST to http://localhost:3457/api/cortex/knowledge/
+[2026-04-17T18:45:37.722Z] [LEARN] Response: 307
+[2026-04-17T18:52:27.655Z] Hook started
+[2026-04-17T18:52:27.661Z] Input length: 319
+[2026-04-17T18:52:27.662Z] Querying: http://localhost:3457/api/cortex/context/?q=does%20it%20use%20skills%20and%20tools%20or%20no%3F&limit=5&workspace_id=2 (event: UserPromptSubmit)
+[2026-04-17T18:52:27.697Z] Main error: 307
+[2026-04-17T18:52:27.697Z] Hook finished
+[2026-04-17T18:52:39.328Z] [LEARN] Learn hook started
+[2026-04-17T18:52:39.336Z] [LEARN] Input length: 2048
+[2026-04-17T18:52:39.344Z] [LEARN] Sending POST to http://localhost:3457/api/cortex/knowledge/
+[2026-04-17T18:52:39.385Z] [LEARN] Response: 307
+[2026-04-19T13:26:25.015Z] Hook started
+[2026-04-19T13:26:25.022Z] Input length: 413
+[2026-04-19T13:26:25.023Z] Querying: http://localhost:3457/api/cortex/context/?q=pull%20the%20latest%20from%20github%20so%20we%20can%20do%20an%20npm%20release.%20%20can%20we%20use%20this%20access%20token%3F%20%20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&limit=5&workspace_id=2 (event: UserPromptSubmit)
+[2026-04-19T13:26:25.063Z] Main error: 307
+[2026-04-19T13:26:25.063Z] Hook finished
+[2026-04-19T13:26:59.700Z] [LEARN] Learn hook started
+[2026-04-19T13:26:59.707Z] [LEARN] Input length: 976
+[2026-04-19T13:26:59.716Z] [LEARN] Sending POST to http://localhost:3457/api/cortex/knowledge/
+[2026-04-19T13:26:59.762Z] [LEARN] Response: 307
+[2026-04-19T13:27:33.753Z] Hook started
+[2026-04-19T13:27:33.759Z] Input length: 287
+[2026-04-19T13:27:33.760Z] Prompt too short
+[2026-04-19T13:27:51.049Z] Hook started
+[2026-04-19T13:27:51.058Z] Input length: 335
+[2026-04-19T13:27:51.059Z] Querying: http://localhost:3457/api/cortex/context/?q=yesyou'll%20have%20to%20bump%20again.%20%200.9.7%20is%20live%20on%20npm&limit=5&workspace_id=2 (event: UserPromptSubmit)
+[2026-04-19T13:27:51.100Z] Main error: 307
+[2026-04-19T13:27:51.100Z] Hook finished
+[2026-04-19T13:31:43.687Z] [LEARN] Learn hook started
+[2026-04-19T13:31:43.698Z] [LEARN] Input length: 508
+[2026-04-19T13:31:43.707Z] [LEARN] Sending POST to http://localhost:3457/api/cortex/knowledge/
+[2026-04-19T13:31:43.747Z] [LEARN] Response: 307
+[2026-04-19T13:35:50.269Z] Hook started
+[2026-04-19T13:35:50.277Z] Input length: 307
+[2026-04-19T13:35:50.278Z] Querying: http://localhost:3457/api/cortex/context/?q=try%20now%2C%20i%20disabled%202fa&limit=5&workspace_id=2 (event: UserPromptSubmit)
+[2026-04-19T13:35:50.316Z] Main error: 307
+[2026-04-19T13:35:50.316Z] Hook finished
+[2026-04-19T13:38:15.302Z] [LEARN] Learn hook started
+[2026-04-19T13:38:15.309Z] [LEARN] Input length: 943
+[2026-04-19T13:38:15.318Z] [LEARN] Sending POST to http://localhost:3457/api/cortex/knowledge/
+[2026-04-19T13:38:15.356Z] [LEARN] Response: 307
+[2026-04-19T13:39:55.427Z] Hook started
+[2026-04-19T13:39:55.432Z] Input length: 324
+[2026-04-19T13:39:55.433Z] Querying: http://localhost:3457/api/cortex/context/?q=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&limit=5&workspace_id=2 (event: UserPromptSubmit)
+[2026-04-19T13:39:55.467Z] Main error: 307
+[2026-04-19T13:39:55.467Z] Hook finished
+[2026-04-19T13:42:05.596Z] [LEARN] Learn hook started
+[2026-04-19T13:42:05.605Z] [LEARN] Input length: 573
+[2026-04-19T13:42:05.615Z] [LEARN] Sending POST to http://localhost:3457/api/cortex/knowledge/
+[2026-04-19T13:42:05.657Z] [LEARN] Response: 307
+[2026-04-19T13:42:36.645Z] Hook started
+[2026-04-19T13:42:36.651Z] Input length: 356
+[2026-04-19T13:42:36.652Z] Querying: http://localhost:3457/api/cortex/context/?q=this%20is%20my%20pc%20--%20why%20does%20it%20matter%20if%20it's%20exposed%20in%20the%20conversation%3F&limit=5&workspace_id=2 (event: UserPromptSubmit)
+[2026-04-19T13:42:36.692Z] Main error: 307
+[2026-04-19T13:42:36.693Z] Hook finished
+[2026-04-19T13:42:48.628Z] [LEARN] Learn hook started
+[2026-04-19T13:42:48.803Z] [LEARN] Input length: 1549
+[2026-04-19T13:42:48.814Z] [LEARN] Sending POST to http://localhost:3457/api/cortex/knowledge/
+[2026-04-19T13:42:48.851Z] [LEARN] Response: 307
+[2026-04-19T13:43:13.309Z] Hook started
+[2026-04-19T13:43:13.315Z] Input length: 325
+[2026-04-19T13:43:13.315Z] Querying: http://localhost:3457/api/cortex/context/?q=how%20do%20I%20check%20to%20see%20if%20telemetry%20is%20on%3F&limit=5&workspace_id=2 (event: UserPromptSubmit)
+[2026-04-19T13:43:13.350Z] Main error: 307
+[2026-04-19T13:43:13.350Z] Hook finished
+[2026-04-19T13:43:53.691Z] [LEARN] Learn hook started
+[2026-04-19T13:43:53.703Z] [LEARN] Input length: 1307
+[2026-04-19T13:43:53.713Z] [LEARN] Sending POST to http://localhost:3457/api/cortex/knowledge/
+[2026-04-19T13:43:53.750Z] [LEARN] Response: 307
+[2026-04-19T13:48:18.876Z] Hook started
+[2026-04-19T13:48:18.882Z] Input length: 287
+[2026-04-19T13:48:18.882Z] Prompt too short
+[2026-04-19T13:52:11.498Z] [LEARN] Learn hook started
+[2026-04-19T13:52:11.505Z] [LEARN] Input length: 354
+[2026-04-19T13:52:11.514Z] [LEARN] Sending POST to http://localhost:3457/api/cortex/knowledge/
+[2026-04-19T13:52:11.557Z] [LEARN] Response: 307
+[2026-04-19T13:52:37.908Z] Hook started
+[2026-04-19T13:52:37.914Z] Input length: 314
+[2026-04-19T13:52:37.916Z] Querying: http://localhost:3457/api/cortex/context/?q=add%20that%20to%20my%20claude%20settings&limit=5&workspace_id=2 (event: UserPromptSubmit)
+[2026-04-19T13:52:37.948Z] Main error: 307
+[2026-04-19T13:52:37.949Z] Hook finished
+[2026-04-19T13:53:23.519Z] [LEARN] Learn hook started
+[2026-04-19T13:53:23.529Z] [LEARN] Input length: 532
+[2026-04-19T13:53:23.541Z] [LEARN] Sending POST to http://localhost:3457/api/cortex/knowledge/
+[2026-04-19T13:53:23.579Z] [LEARN] Response: 307
+[2026-04-22T17:51:18.661Z] Hook started
+[2026-04-22T17:51:18.668Z] Input length: 326
+[2026-04-22T17:51:18.669Z] Querying: http://localhost:3457/api/cortex/context/?q=update%20ffrom%20github%20and%20push%20a%20new%20npm%20release&limit=5&workspace_id=2 (event: UserPromptSubmit)
+[2026-04-22T17:51:18.696Z] Main error: 
+[2026-04-22T17:51:18.696Z] Hook finished
+[2026-04-22T17:51:58.962Z] [LEARN] Learn hook started
+[2026-04-22T17:51:58.968Z] [LEARN] Input length: 559
+[2026-04-22T17:51:58.976Z] [LEARN] Sending POST to http://localhost:3457/api/cortex/knowledge/
+[2026-04-22T17:51:59.003Z] [LEARN] Request error: 
+[2026-04-22T18:06:02.839Z] Hook started
+[2026-04-22T18:06:02.845Z] Input length: 1514
+[2026-04-22T18:06:02.846Z] Querying: http://localhost:3457/api/cortex/context/?q=npm%20notice%201.4kB%20bin%2Fspaces-reset-totp.js%0Anpm%20notice%2036.8kB%20bin%2Fspaces-service.js%0Anpm%20notice%208.9kB%20bin%2Fspaces-setup.js%0Anpm%20notice%2033.6kB%20bin%2Fspaces.js%0Anpm%20notice%202.3kB%20bin%2Fssh-auth-keys.sh%0Anpm%20notice%20108.5kB%20bin%2Fterminal-server.js%0Anpm%20notice%203.4kB%20package.json%0Anpm%20notice%20Tarball%20Details%0Anpm%20notice%20name%3A%20%40jlongo78%2Fagent-spaces%0Anpm%20notice%20version%3A%200.9.9%0Anpm%20notice%20filename%3A%20jlongo78-agent-spaces-0.9.9.tgz%0Anpm%20notice%20package%20size%3A%2018.5%20MB%0Anpm%20notice%20unpacked%20size%3A%2089.8%20MB%0Anpm%20notice%20shasum%3A%2051e72b721f4acb1c8310031c78f24475639d870c%0Anpm%20notice%20integrity%3A%20sha512-L3MTwHtZpUSCN%5B...%5DY1n6%2FUIyMlpYA%3D%3D%0Anpm%20notice%20total%20files%3A%203341%0Anpm%20notice%0Anpm%20notice%20Publishing%20to%20https%3A%2F%2Fregistry.npmjs.org%2F%20with%20tag%20latest%20and%20public%20access%0Anpm%20error%20code%20E404%0Anpm%20error%20404%20Not%20Found%20-%20PUT%20https%3A%2F%2Fregistry.npmjs.org%2F%40jlongo78%252fagent-spaces%20-%20Not%20found%0Anpm%20error%20404%0Anpm%20error%20404%20%20'%40jlongo78%2Fagent-spaces%400.9.9'%20is%20not%20in%20this%20registry.%0Anpm%20error%20404%0Anpm%20error%20404%20Note%20that%20you%20can%20also%20install%20from%20a%0Anpm%20error%20404%20tarball%2C%20folder%2C%20http%20url%2C%20or%20git%20url.%0Anpm%20error%20A%20complete%20log%20of%20this%20run%20can%20be%20found%20in%3A%20C%3A%5CUsers%5Cjohns%5CAppData%5CLocal%5Cnpm-cache%5C_logs%5C2026-04-22T18_01_12_712Z-debug-0.log%0A%0AD%3A%5Cprojects%5Cspaces%3E&limit=5&workspace_id=2 (event: UserPromptSubmit)
+[2026-04-22T18:06:02.872Z] Main error: 
+[2026-04-22T18:06:02.873Z] Hook finished
+[2026-04-22T18:06:14.831Z] [LEARN] Learn hook started
+[2026-04-22T18:06:14.838Z] [LEARN] Input length: 960
+[2026-04-22T18:06:14.847Z] [LEARN] Sending POST to http://localhost:3457/api/cortex/knowledge/
+[2026-04-22T18:06:14.877Z] [LEARN] Request error: 
+[2026-04-22T18:07:49.032Z] Hook started
+[2026-04-22T18:07:49.039Z] Input length: 320
+[2026-04-22T18:07:49.041Z] Querying: http://localhost:3457/api/cortex/context/?q=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&limit=5&workspace_id=2 (event: UserPromptSubmit)
+[2026-04-22T18:07:49.071Z] Main error: 
+[2026-04-22T18:07:49.071Z] Hook finished

package/.next/standalone/docs/features/claude-usage.md

@@ -0,0 +1,105 @@
+# Claude Plan-Usage Display
+
+**Status:** stable
+**Owner:** jlongo
+**Last updated:** 2026-04-22
+
+## Overview
+
+A compact readout of the user's Anthropic plan-usage rate limits, surfaced in the terminal page header whenever the active workspace has at least one Claude pane. Shows 5-hour, 7-day Opus, and 7-day Sonnet windows at a glance; click expands to all windows plus overage credits. Data matches what `/usage` shows inside Claude Code.
+
+## User-facing behavior
+
+- Open any workspace on `/terminal` that has a Claude pane.
+- A horizontal strip appears in the header (right side, before Files / Collab / Close / Add Pane).
+- Three thin progress bars: **5h**, **Opus**, **Sonnet** — each with a percent label and a color that escalates green → amber → red.
+- Hover a bar → tooltip `{label}: X% used · resets in 2h 14m`.
+- Click the strip → popover with all five rate-limit windows + an overage-credits block if the account has overage enabled.
+- If the OAuth token is missing or expired, the strip shows `sign in via Claude Code` with a small login icon. No auto-refresh.
+- If the Anthropic endpoint fails or times out, the strip hides silently.
+
+## Architecture
+
+UI (`src/components/claude/claude-usage-strip.tsx`) → polling hook (`src/hooks/use-claude-usage.ts`) → API route (`src/app/api/claude/usage/route.ts`) → credentials reader (`src/lib/claude/credentials.ts`) + Anthropic fetcher with 30s cache (`src/lib/claude/usage.ts`) → `https://api.anthropic.com/api/oauth/usage`.
+
+Polling: hook calls the route on mount and every 60s while the strip is enabled. Server caches the Anthropic response 30s per access-token prefix so rapid re-polls don't hammer Anthropic.
+
+## Key files
+
+| Path | Role |
+|---|---|
+| `src/lib/claude/credentials.ts` | Reads `~/.claude/.credentials.json`, extracts `claudeAiOauth`, exposes `isTokenExpired()`. |
+| `src/lib/claude/usage.ts` | Calls Anthropic's `/api/oauth/usage`, 5s timeout, 30s in-memory cache. |
+| `src/app/api/claude/usage/route.ts` | `GET` handler; returns one of `ok` / `unauthenticated` / `expired` / `upstream_error`. |
+| `src/hooks/use-claude-usage.ts` | 60s polling hook, toggled by `enabled` arg. |
+| `src/components/claude/claude-usage-strip.tsx` | Compact 3-bar strip + expanded popover. |
+| `src/app/(desktop)/terminal/page.tsx` | Mounts the strip conditionally in the header. |
+| `src/types/claude.ts` | `RateLimit`, `ExtraUsage`, `Utilization`, `UsageResponse`. |
+
+## Data model
+
+No DB tables. All state is transient:
+- Server-side: in-memory `Map<tokenPrefix, { fetchedAt, data }>` in `src/lib/claude/usage.ts` with 30s TTL. Process-local; resets on server restart.
+- Client-side: React state in the hook.
+
+## APIs / contracts
+
+### Internal endpoints
+
+- `GET /api/claude/usage` — returns `UsageResponse`:
+  - `200 { status: "ok", data: Utilization }` — happy path.
+  - `200 { status: "unauthenticated" }` — no credentials file or no `claudeAiOauth`.
+  - `200 { status: "expired" }` — access token past `expiresAt`.
+  - `200 { status: "upstream_error" }` — Anthropic non-2xx or timeout.
+
+Auth: same `withUser`/`getAuthUser` wrapping as every other `/api/*` route.
+
+### External calls
+
+- **Anthropic `GET https://api.anthropic.com/api/oauth/usage`** — uses the user's own OAuth access token read from `~/.claude/.credentials.json`. No secret of our own. User-Agent `claude-code/spaces-integration`.
+
+## Configuration & environment
+
+- `CLAUDE_CONFIG_DIR` — respected (defaults to `~/.claude`). Same semantics as Claude Code.
+- No env vars, feature flags, or tier gates specific to this feature.
+
+## How to run / test locally
+
+```bash
+npm install
+npm run build
+npm start
+# visit http://localhost:3457/terminal, enter a workspace, add a Claude pane
+```
+
+Manual QA checklist:
+
+1. With a valid OAuth session (logged in via any recent Claude Code run): the strip appears in the header; percents match `/usage` inside Claude Code.
+2. Hover each bar → tooltip shows the reset timing.
+3. Click → popover with all five windows and overage block (if applicable).
+4. Delete the Claude pane from the workspace → strip disappears.
+5. Set `claudeAiOauth.expiresAt` to a past timestamp in `.credentials.json`, reload → strip shows "sign in via Claude Code".
+6. Move `.credentials.json` aside temporarily, reload → same sign-in hint.
+7. Disconnect network → within ~90s the strip silently hides (`upstream_error` → null render).
+
+No automated tests for v1.
+
+## Known quirks & decisions
+
+- **Passive refresh.** We do not refresh the OAuth access token. Claude Code owns the refresh lifecycle and writes `.credentials.json`; racing with it would corrupt the shared file.
+- **Account-wide data, not per-pane.** The Anthropic endpoint returns account-level rate limits. Rendering once in the header (not per-pane) is intentional.
+- **User-Agent and anthropic-beta header.** The Anthropic `/api/oauth/usage` endpoint requires the `anthropic-beta: oauth-2025-04-20` header in addition to the Bearer token — without it the call 4xx-errors out. Both the UA (`claude-code/spaces`) and the beta header are constants in `src/lib/claude/usage.ts`; if upstream ever rotates the beta header, bump it there.
+- **30s cache + 60s poll.** Outer-bound staleness is ~90s; fine for windows that move in hours.
+- **Token-prefix cache key.** First 16 chars of `accessToken`. Collision probability is effectively nil; avoids holding full tokens in the cache structure beyond the single request.
+- **Silent upstream failure.** Errors hide the strip rather than showing a red toast — rate-limit info is nice-to-have, not mission-critical.
+- **Ships direct to `main`.** Per repo convention.
+
+## Open questions / TODOs
+
+- [ ] Active OAuth refresh — mirror Claude Code's `/oauth/token` dance to keep the widget live past expiry. Deferred for v1.
+- [ ] Session-cost complement using local JSONL token counts (different data source).
+- [ ] Consider surfacing 7-day-overall alongside the current three for users who care.
+
+## Changelog
+
+- 2026-04-22 — Initial implementation. v1 ships direct to `main`.

package/.next/standalone/docs/features/workspace-todos.md

@@ -0,0 +1,127 @@
+# Workspace Todos
+
+**Status:** stable
+**Owner:** jlongo
+**Last updated:** 2026-04-21
+
+## Overview
+
+A lightweight todo list attached to each workspace. Renders inline at the top of `/terminal` above the pane grid, always visible. Minimal model: text + checkbox + delete. Scoped per-workspace — switching workspaces swaps the list. Not in scope: agent read/write, drag-reorder, priorities/due dates, cross-workspace views.
+
+## User-facing behavior
+
+- Visit `/terminal`, enter any workspace.
+- A "Todos" bar renders above the pane grid with an "Add todo…" input.
+- Enter adds a todo at the bottom of the uncompleted list. Input stays focused.
+- Click the checkbox → strike-through + sink to the completed section.
+- Click text → inline edit. Enter saves, Esc cancels, blur saves.
+- Hover row → `×` delete button.
+- Eye icon in the header toggles visibility of completed todos (ephemeral, resets on reload).
+
+## Architecture
+
+UI (`src/components/workspace/workspace-todos.tsx`) → API routes (`src/app/api/workspaces/[id]/todos/*`) → DB helpers (`src/lib/db/queries.ts`) → SQLite (`workspace_todos` table in the per-user DB at `~/.spaces/<user>.db`).
+
+Mutations are optimistic client-side with rollback on failure. Workspace switch triggers a fresh refetch keyed on `workspaceId`.
+
+## Key files
+
+| Path | Role |
+|---|---|
+| `src/components/workspace/workspace-todos.tsx` | Inline UI component — fetching, optimistic CRUD, rendering |
+| `src/app/api/workspaces/[id]/todos/route.ts` | `GET` list, `POST` create |
+| `src/app/api/workspaces/[id]/todos/[todoId]/route.ts` | `PATCH` update, `DELETE` remove |
+| `src/lib/db/schema.ts` | `workspace_todos` table declaration inside `initSchema()` |
+| `src/lib/db/queries.ts` | `getWorkspaceTodos`, `addWorkspaceTodo`, `updateWorkspaceTodo`, `deleteWorkspaceTodo` |
+| `src/types/claude.ts` | `WorkspaceTodo` type |
+| `src/app/(desktop)/terminal/page.tsx` | Mounts `<WorkspaceTodos>` above the pane grid |
+| `tests/db/workspace-todos.test.ts` | Query-layer tests — ordering, cascade, scoping |
+
+## Data model
+
+### `workspace_todos`
+
+| Column | Type | Notes |
+|---|---|---|
+| `id` | INTEGER PK | autoincrement |
+| `workspace_id` | INTEGER NOT NULL | FK → `workspaces(id)` ON DELETE CASCADE |
+| `text` | TEXT NOT NULL | trimmed on insert/update; empty rejected |
+| `completed` | INTEGER NOT NULL DEFAULT 0 | 0 or 1 |
+| `sort_order` | INTEGER NOT NULL DEFAULT 0 | meaningful only among uncompleted rows |
+| `created` | TEXT NOT NULL DEFAULT datetime('now') | |
+| `completed_at` | TEXT | set when completed flips 0→1, cleared on 1→0 |
+
+Index: `idx_workspace_todos_workspace` on `workspace_id`.
+
+### TypeScript
+
+```ts
+interface WorkspaceTodo {
+  id: number;
+  workspaceId: number;
+  text: string;
+  completed: boolean;
+  sortOrder: number;
+  created: string;
+  completedAt: string | null;
+}
+```
+
+### Invariants
+
+- Listing order: uncompleted first by `sort_order` ASC, then completed by `completed_at` DESC.
+- New todos get `sort_order = MAX(sort_order WHERE completed=0) + 1`.
+- `completed_at` is `NULL` iff `completed = 0`.
+- Deleting a workspace deletes its todos via FK cascade.
+
+## APIs / contracts
+
+### Internal endpoints
+
+| Method | Path | Request | Response |
+|---|---|---|---|
+| `GET` | `/api/workspaces/:id/todos` | — | `WorkspaceTodo[]` |
+| `POST` | `/api/workspaces/:id/todos` | `{ text: string }` | `201 WorkspaceTodo` or `400 { error }` |
+| `PATCH` | `/api/workspaces/:id/todos/:todoId` | `{ text?, completed? }` | `WorkspaceTodo` or `400`/`404` |
+| `DELETE` | `/api/workspaces/:id/todos/:todoId` | — | `{ ok: true }` |
+
+Auth via `getAuthUser` + `withUser`, same pattern as sibling workspace routes.
+
+### External calls
+N/A.
+
+## Configuration & environment
+None. Always-on Community-tier feature. No env vars, flags, or tier gates.
+
+## How to run / test locally
+
+```bash
+npm install
+npm run build
+npm start
+# visit http://localhost:3457/terminal, enter any workspace
+```
+
+Automated:
+```bash
+npx vitest run tests/db/workspace-todos.test.ts
+```
+
+## Known quirks & decisions
+
+- **Schema lives in `initSchema()`, no migration file.** Matches the pattern in `src/lib/db/schema.ts`; the repo has no separate migration system.
+- **No agent write path in v1.** The coworker's "pi /todos" plugin that inspired this lets agents add todos from inside the session — deferred because it requires an MCP tool or CLI surface.
+- **Optimistic updates without toasts.** Failures `console.error` and revert local state; this is a local-only app, so silent revert is acceptable for v1.
+- **`sort_order = Number.MAX_SAFE_INTEGER` for optimistic inserts.** The temp row sorts to the bottom of uncompleted; the server returns the real `sort_order` on response and replaces the temp.
+- **No confirm on delete.** Minimal ethos. Add undo toast in a follow-up if this proves painful.
+- **Direct-to-main workflow.** Per repo convention for this codebase; no PR flow.
+
+## Open questions / TODOs
+
+- [ ] Agent write access via MCP tool once UI v1 proves out.
+- [ ] Optional: persist the "show completed" toggle in localStorage.
+- [ ] Optional: keyboard shortcut to focus the add-input from anywhere on `/terminal`.
+
+## Changelog
+
+- 2026-04-21 — Initial implementation. v1 ships direct to `main`.