eco-helpers 3.2.14 → 3.2.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d67a16095de2e32c2c627214b0254df6d2685e0591ab6295082736e52494c4d3
-  data.tar.gz: 60835a688189d8feda9bdc6198bbdb0cfaa9e9f95e5c7521f36cedbec706c1b0
+  metadata.gz: 1bf8d3ba40b3f6731a9790d3068ecfd8396b13af79fd5a553aed7dafa5514236
+  data.tar.gz: 386c5c215aef1afb8e5ef4c8fb72aeddd6ec4c66bb89d569e9c579063128900f
 SHA512:
-  metadata.gz: 0c1ded6a88ad0c6394e96cb511fddb5c5ac29635307affc1577d5eeb210f01ad8dd78edf78e449b9bca765a8754aa31083abb72beb60746ed21741e523878e6c
-  data.tar.gz: a18f9c81c2430ba8251bdfc34e6e4e1d3da0fd3cbe4647226942469d8da1f71e00aa7e21e3162d9d89d492f98e800642c0132edc30a305515df67764c397de91
+  metadata.gz: 9eaaaf9ecff40b6eb646adeceb8cc7115dacf998357206f9192ff4d6bf912067a90a915b93649ef49c99332c5655459fc599fec3a516f11c49951442bc836219
+  data.tar.gz: 0020a6441d4da68b5a3b80b82494197b2f4c21656dd5babbd143e8ac6302fcd09599eb68d68b9a32895dcd0bd76f6cf76ba96ae66f17706b30a9dbd5f1d61131

data/.ai-assistance/conventions/code-working-tree-protocol.md

@@ -0,0 +1,176 @@
+# Code Working Tree Protocol
+
+When Claude Code needs to make changes to files **outside** `bridge/inbox/`, it must
+follow this protocol. This prevents Code's changes from mixing with in-progress CoWork
+edits and ensures a clean, traceable commit history.
+
+---
+
+## When this applies
+
+Any time Code intends to modify files in the working tree that are not bridge task files
+(i.e., not `.ai-assistance/bridge/inbox/` or `.ai-assistance/bridge/outbox/`).
+
+This includes: editing source files, updating documentation, changing scripts,
+modifying capabilities files, etc.
+
+---
+
+## Protocol
+
+### 0. Check for a lock
+
+```bash
+cat .ai-assistance/bridge/LOCK 2>/dev/null || echo "NO_LOCK"
+```
+
+- **No lock:** proceed to step 1
+- **Lock exists, EXPIRES is in the future:** stop. Tell the user:
+  > "Working tree is locked by [AGENT] ([USER]) since [ACQUIRED], working on: [INTENT].
+  > Expires at [EXPIRES]. Please wait or check if the other session is still active."
+- **Lock exists, EXPIRES is in the past:** stale lock — safe to overwrite, proceed to step 1
+
+---
+
+### 1. Acquire the lock
+
+Write `.ai-assistance/bridge/LOCK` with full watermark:
+
+```
+AGENT: code
+USER: [git config user.name, lowercased]
+ACQUIRED: [ISO 8601 now]
+EXPIRES: [ISO 8601 now + 30 minutes]
+INTENT: [one sentence — what you are about to change and why]
+FILES: [comma-separated list of files you plan to modify]
+```
+
+Example:
+```
+AGENT: code
+USER: oscar
+ACQUIRED: 2026-06-04T10:00:00Z
+EXPIRES: 2026-06-04T10:30:00Z
+INTENT: Update gitlab-mcp.md with new PAT scopes and rotation info
+FILES: .ai-assistance/integrations/gitlab-mcp.md
+```
+
+---
+
+### 2. Check for unstaged changes that overlap with your planned files
+
+```bash
+git status --short
+```
+
+If the working tree is clean, skip to step 3.
+
+If there are unstaged/staged changes, compare them against the files listed in your LOCK:
+
+```bash
+git diff --name-only HEAD
+git diff --cached --name-only
+```
+
+- **No overlap with your FILES:** proceed — the changes are unrelated and won't pollute history
+- **Overlap with one or more of your FILES:** commit the unstaged changes first.
+  Derive the commit message by running `git diff HEAD` on the overlapping files and
+  writing a short imperative summary of what actually changed — do not use a generic
+  message. Format: `wip: <what changed, e.g. "rename .claude to .ai-assistance across scripts">`
+
+```bash
+git add -A
+git commit -m "wip: <derived from actual diff>"
+```
+
+This keeps Code's subsequent commit clean and ensures both sets of changes build
+on the correct base. On a feature branch, `wip:` commits are fine — squash before MR.
+
+---
+
+### 3. Apply your changes
+
+Make the intended file edits. Stay within the scope declared in INTENT and FILES
+when you acquired the lock. If scope expands, update the LOCK file before proceeding.
+
+---
+
+### 4. Commit your changes
+
+```bash
+git add -A
+git commit -m "[descriptive message — what Code changed and why]"
+```
+
+Commit message should be specific enough that a teammate can understand the change
+without reading the diff. Example:
+```
+docs: update gitlab-mcp.md scopes and rotation info for new PAT (April 2027 expiry)
+```
+
+**Commit authorship — developer only by default:**
+
+Commits are authored by the developer alone (git's `user.name` / `user.email` config).
+Do NOT add `Co-Authored-By: Claude ...` to commit messages unless the developer
+explicitly requests it.
+
+Rationale: the commit history is the developer's professional record. Co-authorship is
+opt-in, not opt-out. If the developer wants to attribute AI involvement, they can add
+it themselves or ask Claude to include it for a specific commit.
+
+Before adding any co-authorship attribution, ask:
+> "Would you like to add AI co-authorship to this commit, or keep it as your commit alone?"
+
+Default answer if not asked: **developer only**.
+
+---
+
+### 5. Release the lock
+
+```bash
+rm .ai-assistance/bridge/LOCK
+```
+
+---
+
+## Quick reference
+
+```bash
+# 0. Check lock
+cat .ai-assistance/bridge/LOCK 2>/dev/null || echo "NO_LOCK"
+
+# 1. Acquire lock
+cat > .ai-assistance/bridge/LOCK << EOF
+AGENT: code
+USER: oscar
+ACQUIRED: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+EXPIRES: $(date -u -d "+30 minutes" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -v+30M +"%Y-%m-%dT%H:%M:%SZ")
+INTENT: <what you are changing>
+FILES: <files>
+EOF
+
+# 2. Check for overlapping unstaged changes
+git diff --name-only HEAD && git diff --cached --name-only
+# If any of those files overlap with your planned FILES → commit them first:
+git add -A && git commit -m "wip: <description of CoWork's in-progress work>"
+# If no overlap → skip, proceed directly
+
+# 3. Apply changes
+# ... make edits ...
+
+# 4. Commit your changes
+git add -A && git commit -m "<descriptive message>"
+
+# 5. Release lock
+rm .ai-assistance/bridge/LOCK
+```
+
+---
+
+## Notes
+
+- If Code crashes mid-protocol, the LOCK will expire naturally (30 min timeout)
+- The `wip:` commit prefix signals to teammates that this was an auto-committed
+  in-progress state — safe to squash or amend later
+- This protocol does not apply to bridge task processing (reading inbox, writing outbox)
+  — those are read/write of bridge files only and don't touch the working tree

data/.ai-assistance/scripts/token-logger.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+/**
+ * token-logger.js
+ *
+ * Claude Code Stop hook — fires after every AI response turn.
+ * Reads the session transcript, extracts token usage, accumulates weekly totals,
+ * and warns when approaching the project's budget allocation.
+ *
+ * Wired in .claude/settings.json:
+ *   "Stop": [{ "type": "command", "command": "node .ai-assistance/scripts/token-logger.js" }]
+ *
+ * Reads:  stdin (Stop event JSON with session_id, transcript_path, cwd)
+ *         .ai-assistance/token-budget.json
+ *         .ai-assistance/local/kpi/session-<id>.json  (running session state)
+ *         .ai-assistance/local/kpi/weekly-<YYYY-WNN>.json  (weekly totals)
+ *
+ * Writes: .ai-assistance/local/kpi/session-<id>.json  (updated state)
+ *         .ai-assistance/local/kpi/weekly-<YYYY-WNN>.json  (updated totals)
+ *         .ai-assistance/local/kpi/sessions-<YYYY-WNN>.jsonl  (completed turns)
+ */
+
+const fs   = require("fs");
+const path = require("path");
+const os   = require("os");
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function isoWeek(d) {
+  const jan4 = new Date(d.getFullYear(), 0, 4);
+  const startOfWeek = new Date(jan4);
+  startOfWeek.setDate(jan4.getDate() - ((jan4.getDay() + 6) % 7));
+  const weekNum = Math.ceil(((d - startOfWeek) / 86400000 + 1) / 7);
+  return `${d.getFullYear()}-W${String(weekNum).padStart(2, "0")}`;
+}
+
+function loadJson(p, fallback) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); }
+  catch { return fallback; }
+}
+
+function saveJson(p, data) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+function appendJsonl(p, obj) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.appendFileSync(p, JSON.stringify(obj) + "\n", "utf8");
+}
+
+// ── Extract token usage from transcript JSONL ──────────────────────────────
+
+function extractUsageFromTranscript(transcriptPath) {
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) return null;
+
+  let inputTokens = 0, outputTokens = 0, cacheReadTokens = 0, cacheCreateTokens = 0;
+  let toolCalls = 0, turns = 0, found = false;
+
+  try {
+    const lines = fs.readFileSync(transcriptPath, "utf8").split("\n").filter(Boolean);
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        // Extract usage from any entry that has it
+        const usage = entry.usage || entry.message?.usage;
+        if (usage) {
+          inputTokens      += usage.input_tokens              || 0;
+          outputTokens     += usage.output_tokens             || 0;
+          cacheReadTokens  += usage.cache_read_input_tokens   || 0;
+          cacheCreateTokens+= usage.cache_creation_input_tokens|| 0;
+          found = true;
+        }
+        // Count tool uses
+        if (entry.type === "tool_use" || entry.tool_name) toolCalls++;
+        // Count assistant turns
+        if (entry.role === "assistant" || entry.type === "assistant") turns++;
+      } catch { /* skip malformed lines */ }
+    }
+  } catch { return null; }
+
+  if (!found) return null;
+  return { inputTokens, outputTokens, cacheReadTokens, cacheCreateTokens, toolCalls, turns };
+}
+
+// ── Estimate tokens when transcript doesn't have usage data ───────────────
+
+function estimateFromTranscript(transcriptPath) {
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+    return { inputTokens: 0, outputTokens: 0, toolCalls: 0, turns: 0, estimated: true };
+  }
+  let inputChars = 0, outputChars = 0, toolCalls = 0, turns = 0;
+  try {
+    const lines = fs.readFileSync(transcriptPath, "utf8").split("\n").filter(Boolean);
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        const content = JSON.stringify(entry.content || entry.text || "");
+        if (entry.role === "user" || entry.type === "user")           { inputChars += content.length; }
+        if (entry.role === "assistant" || entry.type === "assistant") { outputChars += content.length; turns++; }
+        if (entry.type === "tool_use" || entry.tool_name)             { toolCalls++; inputChars += 500 * 4; }
+      } catch { /* skip */ }
+    }
+  } catch {}
+  return {
+    inputTokens:  Math.round(inputChars / 4),
+    outputTokens: Math.round(outputChars / 4),
+    cacheReadTokens: 0, cacheCreateTokens: 0,
+    toolCalls, turns, estimated: true
+  };
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+async function main() {
+  let event = {};
+  try {
+    const raw = fs.readFileSync("/dev/stdin", "utf8");
+    event = JSON.parse(raw);
+  } catch { /* no stdin or parse error — use empty event */ }
+
+  const cwd            = event.cwd || process.cwd();
+  const sessionId      = event.session_id || `unknown-${Date.now()}`;
+  const transcriptPath = event.transcript_path;
+
+  const budgetFile  = path.join(cwd, ".ai-assistance", "token-budget.json");
+  const kpiDir      = path.join(cwd, ".ai-assistance", "local", "kpi");
+  const weekId      = isoWeek(new Date());
+  const sessionFile = path.join(kpiDir, `session-${sessionId}.json`);
+  const weeklyFile  = path.join(kpiDir, `weekly-${weekId}.json`);
+  const turnLogFile = path.join(kpiDir, `sessions-${weekId}.jsonl`);
+
+  const budget  = loadJson(budgetFile, {});
+  const project = (budget.project?.name || path.basename(cwd));
+  const priority= (budget.project?.priority || "medium");
+  const targetPct = (budget.weekly_quota?.target_utilization_pct || 75) / 100;
+  const warnAt    = (budget.session_logging?.warn_at_pct || 80) / 100;
+
+  // Extract usage from transcript
+  const transcriptUsage = extractUsageFromTranscript(transcriptPath)
+    || estimateFromTranscript(transcriptPath);
+
+  // Load previous session state (accumulate across turns in a session)
+  const prevSession = loadJson(sessionFile, {
+    session_id: sessionId, project, priority,
+    started_at: new Date().toISOString(),
+    week_id: weekId,
+    input_tokens: 0, output_tokens: 0,
+    cache_read_tokens: 0, cache_create_tokens: 0,
+    tool_calls: 0, turns: 0, estimated: false,
+  });
+
+  // Use transcript totals (they accumulate naturally) not deltas
+  const sessionNow = {
+    ...prevSession,
+    input_tokens:       transcriptUsage.inputTokens,
+    output_tokens:      transcriptUsage.outputTokens,
+    cache_read_tokens:  transcriptUsage.cacheReadTokens  || 0,
+    cache_create_tokens:transcriptUsage.cacheCreateTokens || 0,
+    tool_calls:         transcriptUsage.toolCalls,
+    turns:              transcriptUsage.turns,
+    estimated:          transcriptUsage.estimated || false,
+    last_updated_at:    new Date().toISOString(),
+  };
+
+  saveJson(sessionFile, sessionNow);
+
+  // Update weekly totals — replace session contribution (re-compute from sessions)
+  const weekly = loadJson(weeklyFile, { week_id: weekId, projects: {}, total_tokens: 0 });
+  const sessionTotal = sessionNow.input_tokens + sessionNow.output_tokens;
+  const prevContrib  = (weekly.projects[sessionId]?.tokens || 0);
+  weekly.projects[sessionId] = {
+    project, priority, tokens: sessionTotal,
+    tool_calls: sessionNow.tool_calls, turns: sessionNow.turns,
+    updated_at: new Date().toISOString()
+  };
+  weekly.total_tokens = Object.values(weekly.projects).reduce((s, p) => s + p.tokens, 0);
+  saveJson(weeklyFile, weekly);
+
+  // Log the turn to the weekly JSONL (for cross-session analysis)
+  appendJsonl(turnLogFile, {
+    ts: new Date().toISOString(), session_id: sessionId, project, priority, week_id: weekId,
+    turn_tokens: sessionTotal - prevContrib,
+    session_total_tokens: sessionTotal,
+    tool_calls: sessionNow.tool_calls,
+    estimated: sessionNow.estimated,
+  });
+
+  // ── Budget warnings ────────────────────────────────────────────────────
+
+  const totalTokens = budget.weekly_quota?.total_tokens;
+  if (totalTokens) {
+    const usedPct = weekly.total_tokens / totalTokens;
+    const targetTokens = totalTokens * targetPct;
+
+    // Priority-based soft allocation
+    const weights  = budget.project_allocation?.priority_weights || { high: 50, medium: 30, low: 20 };
+    const myWeight = (weights[priority] || 30) / 100;
+    const myBudget = totalTokens * targetPct * myWeight;
+    const myUsed   = Object.values(weekly.projects)
+      .filter(p => p.project === project)
+      .reduce((s, p) => s + p.tokens, 0);
+    const myPct = myBudget > 0 ? myUsed / myBudget : 0;
+
+    if (usedPct >= warnAt) {
+      process.stderr.write(
+        `\n[token-budget] ⚠  Week ${weekId}: ${Math.round(usedPct * 100)}% of quota used` +
+        ` (${weekly.total_tokens.toLocaleString()}/${totalTokens.toLocaleString()} tokens)` +
+        ` — target was ${Math.round(targetPct * 100)}%\n`
+      );
+    }
+    if (myPct >= warnAt) {
+      process.stderr.write(
+        `[token-budget] ⚠  Project "${project}" (${priority}): ${Math.round(myPct * 100)}% of allocation` +
+        ` (${myUsed.toLocaleString()}/${Math.round(myBudget).toLocaleString()} tokens)\n`
+      );
+    }
+  }
+}
+
+main().catch(() => { /* never crash the hook */ });

data/.ai-assistance/scripts/token-report.ts

@@ -0,0 +1,158 @@
+/**
+ * token-report.ts
+ *
+ * Cross-project token usage report. Reads weekly session logs from all aligned
+ * projects (via local/paths.md) and produces a management-ready summary.
+ *
+ * Usage:
+ *   npx ts-node .ai-assistance/scripts/token-report.ts
+ *   npx ts-node .ai-assistance/scripts/token-report.ts --week 2026-W24
+ *   npx ts-node .ai-assistance/scripts/token-report.ts --format json
+ *
+ * Output: Markdown table (default) or JSON (--format json)
+ * The report is printed to stdout — redirect to a file or pipe to your reporting tool.
+ */
+
+import * as fs   from "fs";
+import * as path from "path";
+
+const SCRIPTS_DIR = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1"));
+const AI_DIR      = path.join(SCRIPTS_DIR, "..");
+const CWD         = path.join(AI_DIR, "..", "..");
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function isoWeek(d: Date): string {
+  const jan4 = new Date(d.getFullYear(), 0, 4);
+  const s = new Date(jan4); s.setDate(jan4.getDate() - ((jan4.getDay() + 6) % 7));
+  return `${d.getFullYear()}-W${String(Math.ceil(((d.getTime() - s.getTime()) / 86400000 + 1) / 7)).padStart(2, "0")}`;
+}
+
+function loadJson<T>(p: string, fb: T): T {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return fb; }
+}
+
+interface ProjectPath { alias: string; localPath: string; }
+
+function loadProjectPaths(): ProjectPath[] {
+  const pathsFile = path.join(AI_DIR, "local", "paths.md");
+  if (!fs.existsSync(pathsFile)) return [{ alias: path.basename(CWD), localPath: CWD }];
+  const projects: ProjectPath[] = [];
+  const seen = new Set<string>();
+  for (const line of fs.readFileSync(pathsFile, "utf8").split("\n")) {
+    const m = line.match(/\|\s*`([^`]+)`\s*\|\s*`([^`]+)`/);
+    if (!m) continue;
+    const [, alias, rawPath] = m;
+    const localPath = rawPath.replace(/\//g, path.sep);
+    const real = fs.existsSync(localPath) ? fs.realpathSync(localPath) : localPath;
+    if (!seen.has(real) && fs.existsSync(localPath)) { projects.push({ alias, localPath }); seen.add(real); }
+  }
+  return projects.length ? projects : [{ alias: path.basename(CWD), localPath: CWD }];
+}
+
+interface WeeklyData {
+  week_id: string;
+  total_tokens: number;
+  projects: Record<string, { project: string; priority: string; tokens: number; tool_calls: number; turns: number; }>;
+}
+
+interface SessionTurn {
+  ts: string; session_id: string; project: string; priority: string;
+  week_id: string; turn_tokens: number; session_total_tokens: number;
+  tool_calls: number; estimated: boolean;
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+const args    = process.argv.slice(2);
+const weekArg = args.includes("--week") ? args[args.indexOf("--week") + 1] : null;
+const format  = args.includes("--format") ? args[args.indexOf("--format") + 1] : "text";
+const weekId  = weekArg || isoWeek(new Date());
+
+const projects = loadProjectPaths();
+
+// Aggregate across all projects
+const byProject: Record<string, {
+  tokens: number; tool_calls: number; turns: number;
+  priority: string; sessions: number; estimated: number;
+}> = {};
+
+let grandTotal = 0;
+
+for (const { localPath } of projects) {
+  const kpiDir     = path.join(localPath, ".ai-assistance", "local", "kpi");
+  const weeklyFile = path.join(kpiDir, `weekly-${weekId}.json`);
+  const budget     = loadJson<any>(path.join(localPath, ".ai-assistance", "token-budget.json"), {});
+  const projectName= budget.project?.name || path.basename(localPath);
+  const priority   = budget.project?.priority || "medium";
+
+  if (!fs.existsSync(weeklyFile)) continue;
+
+  const weekly = loadJson<WeeklyData>(weeklyFile, { week_id: weekId, total_tokens: 0, projects: {} });
+
+  // Sum sessions for this project
+  let tokens = 0, toolCalls = 0, turns = 0, sessions = 0, estimated = 0;
+  for (const s of Object.values(weekly.projects)) {
+    if (s.project === projectName) {
+      tokens    += s.tokens;
+      toolCalls += s.tool_calls || 0;
+      turns     += s.turns || 0;
+      sessions++;
+    }
+  }
+
+  // Count estimated sessions from JSONL
+  const jsonl = path.join(kpiDir, `sessions-${weekId}.jsonl`);
+  if (fs.existsSync(jsonl)) {
+    const lines = fs.readFileSync(jsonl, "utf8").split("\n").filter(Boolean);
+    estimated = lines.filter(l => { try { return JSON.parse(l).estimated; } catch { return false; } }).length;
+  }
+
+  if (tokens > 0) {
+    byProject[projectName] = { tokens, tool_calls: toolCalls, turns, priority, sessions, estimated };
+    grandTotal += tokens;
+  }
+}
+
+if (format === "json") {
+  console.log(JSON.stringify({ week_id: weekId, grand_total_tokens: grandTotal, projects: byProject }, null, 2));
+  process.exit(0);
+}
+
+// ── Text report ────────────────────────────────────────────────────────────
+
+const sortedProjects = Object.entries(byProject)
+  .sort(([, a], [, b]) => b.tokens - a.tokens);
+
+console.log(`\n${"=".repeat(70)}`);
+console.log(`  Token Usage Report — ${weekId}`);
+console.log(`  Generated: ${new Date().toISOString().slice(0, 16)}`);
+console.log(`${"=".repeat(70)}\n`);
+console.log(`  Grand total: ${grandTotal.toLocaleString()} tokens across ${sortedProjects.length} project(s)\n`);
+
+console.log(`  ${"Project".padEnd(30)} ${"Priority".padEnd(10)} ${"Tokens".padStart(10)} ${"Share".padStart(7)} ${"Tool calls".padStart(12)} ${"Turns".padStart(6)}`);
+console.log(`  ${"-".repeat(78)}`);
+
+for (const [name, data] of sortedProjects) {
+  const share = grandTotal > 0 ? Math.round((data.tokens / grandTotal) * 100) : 0;
+  const est   = data.estimated > 0 ? " ~" : "  ";
+  console.log(`  ${name.padEnd(30)} ${data.priority.padEnd(10)} ${est}${data.tokens.toLocaleString().padStart(8)} ${`${share}%`.padStart(7)} ${data.tool_calls.toString().padStart(12)} ${data.turns.toString().padStart(6)}`);
+}
+
+console.log(`\n  ~ = some sessions used token estimation (transcript had no usage data)`);
+
+// Priority allocation analysis
+const targetPct = 75;
+const weights   = { high: 50, medium: 30, low: 20 };
+console.log(`\n  Priority allocation vs actuals (target utilization: ${targetPct}%):`);
+for (const priority of ["high", "medium", "low"]) {
+  const w = (weights as any)[priority];
+  const actual = Object.values(byProject)
+    .filter(p => p.priority === priority)
+    .reduce((s, p) => s + p.tokens, 0);
+  const actualPct = grandTotal > 0 ? Math.round((actual / grandTotal) * 100) : 0;
+  const projects  = Object.entries(byProject).filter(([, p]) => p.priority === priority).map(([n]) => n).join(", ") || "(none)";
+  console.log(`    ${priority.padEnd(8)} target ~${w}%  actual ${`${actualPct}%`.padStart(4)}  — ${projects}`);
+}
+
+console.log(`\n${"=".repeat(70)}\n`);

data/.ai-assistance/scripts/token-session-start.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * token-session-start.js
+ *
+ * Claude Code SessionStart hook.
+ * Checks current week's token usage, warns if over allocation,
+ * and shows the budget status for this project.
+ *
+ * Wired in .claude/settings.json:
+ *   "SessionStart": [{ "type": "command", "command": "node .ai-assistance/scripts/token-session-start.js" }]
+ */
+
+const fs   = require("fs");
+const path = require("path");
+
+function isoWeek(d) {
+  const jan4 = new Date(d.getFullYear(), 0, 4);
+  const s = new Date(jan4); s.setDate(jan4.getDate() - ((jan4.getDay() + 6) % 7));
+  return `${d.getFullYear()}-W${String(Math.ceil(((d - s) / 86400000 + 1) / 7)).padStart(2, "0")}`;
+}
+function loadJson(p, fb) { try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return fb; } }
+
+async function main() {
+  let event = {};
+  try { event = JSON.parse(fs.readFileSync("/dev/stdin", "utf8")); } catch {}
+
+  const cwd     = event.cwd || process.cwd();
+  const weekId  = isoWeek(new Date());
+  const budget  = loadJson(path.join(cwd, ".ai-assistance", "token-budget.json"), {});
+  const weekly  = loadJson(path.join(cwd, ".ai-assistance", "local", "kpi", `weekly-${weekId}.json`), { total_tokens: 0, projects: {} });
+
+  const project  = budget.project?.name || path.basename(cwd);
+  const priority = budget.project?.priority || "medium";
+  const total    = budget.weekly_quota?.total_tokens;
+  const targetPct= (budget.weekly_quota?.target_utilization_pct || 75);
+
+  // My project's tokens this week across all sessions
+  const myTokens = Object.values(weekly.projects)
+    .filter(p => p.project === project)
+    .reduce((s, p) => s + p.tokens, 0);
+
+  const lines = [`\n[token-budget] Week ${weekId} | Project: ${project} (${priority})`];
+  lines.push(`  All projects this week: ${weekly.total_tokens.toLocaleString()} tokens`);
+  lines.push(`  This project this week: ${myTokens.toLocaleString()} tokens`);
+
+  if (total) {
+    const usedPct = Math.round((weekly.total_tokens / total) * 100);
+    const weights = budget.project_allocation?.priority_weights || { high: 50, medium: 30, low: 20 };
+    const myAlloc = Math.round(total * (targetPct / 100) * ((weights[priority] || 30) / 100));
+    const myPct   = myAlloc > 0 ? Math.round((myTokens / myAlloc) * 100) : 0;
+    lines.push(`  Week quota: ${usedPct}% used (target ${targetPct}%) | This project: ${myPct}% of ${myAlloc.toLocaleString()} alloc`);
+    if (usedPct >= targetPct) lines.push(`  !! Over weekly target — consider deferring low-priority work`);
+    if (myPct >= 90)          lines.push(`  !! This project near allocation limit`);
+  }
+
+  process.stderr.write(lines.join("\n") + "\n");
+
+  // Also run bridge-init if it exists
+  const bridgeInit = path.join(cwd, ".ai-assistance", "scripts", "bridge-init.sh");
+  if (fs.existsSync(bridgeInit)) {
+    const { execSync } = require("child_process");
+    try { execSync(`bash "${bridgeInit}"`, { stdio: "inherit" }); } catch {}
+  }
+}
+
+main().catch(() => {});