@axplusb/kepler 2.0.7 → 2.2.0

package/src/core/tool-executor.mjs

@@ -9,12 +9,13 @@
  */
 
 import { createToolRegistry } from '../tools/registry.mjs';
-import { filterOutput } from './output-filter.mjs';
+import { detectCommandType, filterOutput } from './output-filter.mjs';
 import { validatePath, validateDelete, validateShellCommand, validateWrite } from './safety.mjs';
 import { classifyCommand, isExitCodeError } from '../permissions/command-classifier.mjs';
 import { analyzeCode } from '../context/ast-parser.mjs';
 import { ProjectRegistry } from '../tools/project-overview.mjs';
 import { SkillsLoader } from '../skills/loader.mjs';
+import { HookRunner } from '../config/hook-runner.mjs';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { execSync } from 'node:child_process';
@@ -29,6 +30,7 @@ export function createToolExecutor({
     projectRegistry = new ProjectRegistry(),
     skillsLoader = new SkillsLoader().load(process.cwd()),
     checkpoints = null,
+    hookRunner = null,
 } = {}) {
     const occRegistry = createToolRegistry();
     const skillTool = occRegistry.get('Skill');
@@ -49,6 +51,43 @@ export function createToolExecutor({
         return resolvePath(args.cwd || null, args);
     }
 
+    function longRunningObservationTimeoutMs() {
+        const configured = Number(process.env.KEPLER_LONG_RUNNING_TIMEOUT_MS);
+        return Number.isFinite(configured) && configured > 0 ? configured : 15_000;
+    }
+
+    function isLikelyLongRunningCommand(command) {
+        const cmd = String(command || '').trim();
+        if (!cmd) return false;
+        if (/^(?:timeout|gtimeout)\s+\S+\s+/i.test(cmd)) return false;
+        if (/(?:^|[;&|]\s*)(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:dev|start|serve|preview)\b/i.test(cmd)) return true;
+        if (/(?:^|[;&|]\s*)(?:vite|next|nuxt|astro|webpack-dev-server)\b/i.test(cmd)) return true;
+        if (/\b(?:uvicorn|gunicorn|flask\s+run|rails\s+server|bin\/rails\s+server|django-admin\s+runserver|manage\.py\s+runserver)\b/i.test(cmd)) return true;
+        if (/\b(?:python|python3)\s+-m\s+http\.server\b/i.test(cmd)) return true;
+        if (/\bnode\b[\s\S]*(?:setInterval|\.listen\s*\(|createServer\s*\()/i.test(cmd)) return true;
+        if (/\b(?:docker\s+compose|docker-compose)\s+up\b(?![\s\S]*\s-d\b)/i.test(cmd)) return true;
+        if (/\btail\s+-f\b/i.test(cmd)) return true;
+        if (/\b(?:--watch|watch)\b/i.test(cmd)) return true;
+        return false;
+    }
+
+    function limitTail(text, maxChars = 8000) {
+        const value = String(text || '');
+        if (value.length <= maxChars) return value;
+        return `... (tail truncated)\n${value.slice(value.length - maxChars)}`;
+    }
+
+    function formatObservationTimeoutOutput(rawOutput, timeoutMs) {
+        const tail = String(rawOutput || '')
+            .replace(/^Error:\s*Command timed out after \d+ms\s*/i, '')
+            .trim();
+        const body = tail || '(no output captured before timeout)';
+        return limitTail(
+            `Observation timeout after ${timeoutMs}ms for a likely long-running command. ` +
+            `The process was stopped after collecting the output tail.\n${body}`
+        );
+    }
+
     function updateProjectIndex(filePath) {
         try {
             projectRegistry.projectForPath(filePath)?.retriever.updateFile(filePath);
@@ -215,20 +254,31 @@ export function createToolExecutor({
                 }
             }
 
+            const observationTimeout = args.timeout == null && isLikelyLongRunningCommand(args.command);
+            const effectiveTimeout = observationTimeout ? longRunningObservationTimeoutMs() : args.timeout;
             const result = await occRegistry.call('Bash', {
                 command: args.command,
-                timeout: args.timeout,
+                timeout: effectiveTimeout,
                 description: args.description || `Run: ${(args.command || '').slice(0, 50)}`,
                 cwd,
             });
             const rawOutput = typeof result === 'string' ? result : String(result);
+            const timedOut = /^Error:\s*Command timed out after \d+ms/i.test(rawOutput);
             const exitMatch = rawOutput.match(/Exit code: (\d+)/);
-            const exitCode = exitMatch ? parseInt(exitMatch[1]) : 0;
+            const exitCode = timedOut ? 124 : (exitMatch ? parseInt(exitMatch[1]) : 0);
             // Semantic exit code: grep returns 1 for "no matches" (not an error)
-            const success = !isExitCodeError(args.command, exitCode);
+            const success = observationTimeout && timedOut ? true : (!timedOut && !isExitCodeError(args.command, exitCode));
 
             // Apply smart filtering based on command type
-            const filtered = filterOutput(rawOutput, args.command, success);
+            const filtered = observationTimeout && timedOut
+                ? {
+                    output: formatObservationTimeoutOutput(rawOutput, effectiveTimeout),
+                    commandType: detectCommandType(args.command),
+                    truncated: false,
+                    originalLines: rawOutput.split('\n').length,
+                    filteredLines: rawOutput.split('\n').length,
+                }
+                : filterOutput(rawOutput, args.command, success);
 
             return {
                 success,
@@ -238,6 +288,9 @@ export function createToolExecutor({
                 _classification: args._classification,
                 _commandType: filtered.commandType,
                 _filtered: filtered.truncated || filtered.originalLines !== filtered.filteredLines,
+                _timed_out: timedOut,
+                _observation_timeout: observationTimeout && timedOut,
+                _observation_timeout_ms: observationTimeout && timedOut ? effectiveTimeout : undefined,
             };
         },
 
@@ -875,8 +928,21 @@ print('OK: replaced')
             if (!handler) {
                 return { success: false, output: `Unknown tool: ${name}`, _tool: name };
             }
+            const hooks = hookRunner || new HookRunner({ cwd: process.cwd() });
             try {
-                return await handler(args);
+                const pre = await hooks.run('PreToolUse', { toolName: name, input: args || {} });
+                if (pre.blocked) {
+                    return { success: false, output: `BLOCKED by hook: ${pre.message}`, _tool: name, _blocked: true };
+                }
+                let result = await handler(args);
+                const post = await hooks.run('PostToolUse', { toolName: name, input: args || {}, result });
+                for (const item of post.results || []) {
+                    if (item.parsed?.modifiedResult !== undefined) result = item.parsed.modifiedResult;
+                    if (item.parsed?.feedback && result && typeof result === 'object') {
+                        result.output = `${result.output || ''}\n\n--- Hook Feedback ---\n${item.parsed.feedback}`.trim();
+                    }
+                }
+                return result;
             } catch (err) {
                 return { success: false, output: `Tool error (${name}): ${err.message}`, _tool: name };
             }

package/src/core/trust.mjs

@@ -0,0 +1,158 @@
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { TIERS } from './risk-tier.mjs';
+
+function trustPath(cwd) {
+  return path.join(cwd, '.kepler', 'trust.json');
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function commandShape(command) {
+  const parts = String(command || '').trim().split(/\s+/).filter(Boolean);
+  return parts.slice(0, 2).join(' ');
+}
+
+function shellPattern(args) {
+  const shape = commandShape(args?.command);
+  return shape ? `${shape}*` : '*';
+}
+
+function pathPattern(args) {
+  const p = String(args?.file_path || args?.path || '').trim();
+  if (!p) return '*';
+  const dir = path.dirname(p);
+  return dir === '.' ? p : path.join(dir, '**');
+}
+
+export function patternFor(tool, args = {}) {
+  if (tool === 'shell') return shellPattern(args);
+  return pathPattern(args);
+}
+
+function matches(pattern, value) {
+  if (!pattern || pattern === '*') return true;
+  if (pattern.endsWith('*')) return String(value || '').startsWith(pattern.slice(0, -1));
+  if (pattern.endsWith('/**')) return String(value || '').startsWith(pattern.slice(0, -3));
+  return pattern === value;
+}
+
+function valueFor(tool, args = {}) {
+  if (tool === 'shell') return String(args.command || '');
+  return String(args.file_path || args.path || '');
+}
+
+export class TrustStore {
+  constructor({ cwd = process.cwd(), policy = {} } = {}) {
+    this.cwd = cwd;
+    this.policy = policy;
+    this.sessionRules = [];
+  }
+
+  loadProjectRules() {
+    try {
+      const file = trustPath(this.cwd);
+      if (!fs.existsSync(file)) return [];
+      const data = JSON.parse(fs.readFileSync(file, 'utf-8'));
+      return Array.isArray(data.rules) ? data.rules : [];
+    } catch {
+      return [];
+    }
+  }
+
+  saveProjectRules(rules) {
+    const file = trustPath(this.cwd);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({ version: 1, rules }, null, 2) + '\n');
+  }
+
+  allRules() {
+    return [...this.sessionRules, ...this.loadProjectRules()];
+  }
+
+  find(tool, args = {}, tier = '') {
+    const value = valueFor(tool, args);
+    const rules = this.allRules().filter(rule => rule.tool === tool && matches(rule.pattern, value));
+    const deny = rules.find(rule => rule.decision === 'deny');
+    if (deny) return { decision: 'deny', rule: deny };
+    const allow = rules.find(rule => rule.decision === 'allow');
+    if (!allow) return null;
+
+    const reask = this.shouldReask(allow, args, tier);
+    if (reask) return { decision: 'reask', rule: allow, reason: reask };
+    return { decision: 'allow', rule: allow };
+  }
+
+  shouldReask(rule, args = {}, tier = '') {
+    const reask = rule.reask || {};
+    const after = reask.after_minutes ?? this.policy.hitl?.reaskAfterMinutes;
+    if (after && rule.created_at) {
+      const ageMs = Date.now() - Date.parse(rule.created_at);
+      if (Number.isFinite(ageMs) && ageMs > after * 60 * 1000) {
+        return `approval expired after ${after}m`;
+      }
+    }
+    if ((reask.on_risk_increase ?? this.policy.hitl?.reaskOnRiskIncrease) && rule.tier && tier) {
+      const order = [TIERS.READ, TIERS.SHELL_SAFE, TIERS.LOCAL_EDIT, TIERS.SHELL_MEDIUM, TIERS.NETWORK, TIERS.SHELL_DANGEROUS, TIERS.DESTRUCTIVE];
+      if (order.indexOf(tier) > order.indexOf(rule.tier)) return 'risk tier increased';
+    }
+    if ((this.policy.hitl?.alwaysAskForDangerous ?? true) && (tier === TIERS.SHELL_DANGEROUS || tier === TIERS.DESTRUCTIVE)) {
+      return 'dangerous tier requires fresh approval';
+    }
+    if ((reask.on_command_shape_change ?? this.policy.hitl?.reaskOnCommandShapeChange) && rule.command_shape && args.command) {
+      if (rule.command_shape !== commandShape(args.command)) return 'command shape changed';
+    }
+    return '';
+  }
+
+  add({ tool, args = {}, tier, scope = 'SESSION', decision = 'allow' }) {
+    const normalizedScope = String(scope || 'SESSION').toUpperCase();
+    const pattern = patternFor(tool, args);
+    const id = `${tool}-${crypto.createHash('sha1').update(pattern + normalizedScope).digest('hex').slice(0, 10)}`;
+    const ttl = this.policy.hitl?.reaskAfterMinutes ?? 30;
+    const rule = {
+      id,
+      tool,
+      pattern,
+      scope: normalizedScope,
+      decision,
+      tier,
+      command_shape: tool === 'shell' ? commandShape(args.command) : undefined,
+      created_at: nowIso(),
+      expires_at: normalizedScope === 'SESSION'
+        ? new Date(Date.now() + ttl * 60 * 1000).toISOString()
+        : undefined,
+      reask: {
+        after_minutes: ttl,
+        on_command_shape_change: this.policy.hitl?.reaskOnCommandShapeChange ?? true,
+        on_risk_increase: this.policy.hitl?.reaskOnRiskIncrease ?? true,
+        on_path_boundary_change: this.policy.hitl?.reaskOnPathBoundaryChange ?? true,
+      },
+    };
+    if (normalizedScope === 'PROJECT') {
+      const rules = this.loadProjectRules().filter(r => r.id !== id);
+      rules.push(rule);
+      this.saveProjectRules(rules);
+    } else {
+      this.sessionRules = this.sessionRules.filter(r => r.id !== id);
+      this.sessionRules.push(rule);
+    }
+    return rule;
+  }
+
+  revoke() {
+    const active = this.sessionRules.length > 0;
+    this.sessionRules = [];
+    return active;
+  }
+
+  summary() {
+    return {
+      sessionRules: this.sessionRules.length,
+      projectRules: this.loadProjectRules().length,
+    };
+  }
+}

package/src/onboarding/preflight.mjs

@@ -30,6 +30,7 @@ import { URL } from 'node:url';
 import { paint } from '../ui/palette.mjs';
 import { icons } from '../ui/icons.mjs';
 import { term } from '../ui/term.mjs';
+import { formatMessageWindow, lowWindowStatus } from '../core/rate-limit-display.mjs';
 
 const OK   = (s) => `${paint.state.success('[✓]')} ${s}`;
 const WARN = (s) => `${paint.state.warn('[⚠]')} ${s}`;
@@ -37,18 +38,22 @@ const FAIL = (s) => `${paint.state.danger('[✗]')} ${s}`;
 
 // ── Individual checks (each returns { status, label, hint? }) ──────────
 
-async function checkAuthAndBackend(auth, { timeoutMs = 2500 } = {}) {
+export async function checkAuthAndBackend(auth, { timeoutMs } = {}) {
   const creds = auth.loadCredentials();
   const hasToken = !!creds.token;
   const url = creds.backendUrl;
+  // Local Docker backends round-trip Supabase and often take 2–4s. Give them
+  // more headroom so preflight doesn't falsely report Offline.
+  const isLocal = /^https?:\/\/(127\.0\.0\.1|localhost)(:|$|\/)/i.test(url || '');
+  timeoutMs = timeoutMs ?? (isLocal ? 8000 : 2500);
 
   // No token: just probe whether the backend is reachable so we can hint
   // /login when it makes sense.
   if (!hasToken) {
     const reachable = url ? await ping(url, timeoutMs).catch(() => false) : false;
     return reachable
-      ? { status: 'warn', label: 'Not signed in · backend ready', hint: '/login to sign in' }
-      : { status: 'warn', label: 'Not signed in · backend offline', hint: '/login once the network is back' };
+      ? { status: 'warn', label: 'Online', hint: '/login to sign in' }
+      : { status: 'warn', label: 'Offline' };
   }
 
   // Token present: real authenticated round-trip against /api/user/me.
@@ -66,15 +71,14 @@ async function checkAuthAndBackend(auth, { timeoutMs = 2500 } = {}) {
 
     if (resp.ok) {
       const user = await resp.json().catch(() => null);
-      const who = user?.github_username || user?.email || 'user';
-      return { status: 'ok', label: `Signed in as ${who} · connected`, user };
+      return { status: 'ok', label: 'Online', user };
     }
     if (resp.status === 401 || resp.status === 403) {
-      return { status: 'warn', label: 'Token expired · connected', hint: '/login again to refresh' };
+      return { status: 'warn', label: 'Online', hint: '/login again to refresh' };
     }
-    return { status: 'warn', label: `Backend returned ${resp.status}`, hint: 'try again shortly' };
+    return { status: 'warn', label: 'Offline' };
   } catch {
-    return { status: 'warn', label: 'Signed in · backend offline', hint: 'check network or try again shortly' };
+    return { status: 'warn', label: 'Offline' };
   }
 }
 
@@ -86,7 +90,7 @@ async function checkAuthAndBackend(auth, { timeoutMs = 2500 } = {}) {
  *   { status, label }                 — shown as a preflight row
  *   null                              — silent (e.g. BYOK or no signal)
  */
-async function checkCreditsAndPlan(auth, { timeoutMs = 2000 } = {}) {
+export async function checkCreditsAndPlan(auth, { timeoutMs = 2000 } = {}) {
   const creds = auth.loadCredentials();
   if (!creds.token || !creds.backendUrl) return null;
   try {
@@ -103,10 +107,22 @@ async function checkCreditsAndPlan(auth, { timeoutMs = 2000 } = {}) {
     const data = await resp.json().catch(() => null);
     if (!data) return null;
 
+    const tier = (data.tier || 'free').toUpperCase();
+    const windowLabel = formatMessageWindow(data.rate_limit);
+    if (windowLabel) {
+      const status = lowWindowStatus(data.rate_limit);
+      if (status === 'exhausted') {
+        return { status: 'fail', label: windowLabel, hint: 'message window exhausted — try again after reset' };
+      }
+      if (status === 'low') {
+        return { status: 'warn', label: windowLabel, hint: 'low message window — codekepler.ai/pricing' };
+      }
+      return { status: 'ok', label: windowLabel };
+    }
+
     if (data.byok_enabled) {
-      return { status: 'ok', label: `Plan: ${(data.tier || 'byok').toUpperCase()} · billed by your provider` };
+      return { status: 'ok', label: `Plan: ${tier || 'BYOK'} · billed by your provider` };
     }
-    const tier = (data.tier || 'free').toUpperCase();
     const remaining = data.balance?.total;
     if (typeof remaining !== 'number') {
       return { status: 'ok', label: `Plan: ${tier}` };

package/src/permissions/command-classifier.mjs

@@ -144,6 +144,41 @@ function containsCommandSubstitution(command) {
     return false;
 }
 
+function isQuotedMessage(text) {
+    const value = String(text || '').trim();
+    return /^echo\s+(?:"[^"]*"|'[^']*'|[A-Za-z0-9_ .:-]+)$/.test(value);
+}
+
+function isNumericKillCommand(command) {
+    const trimmed = String(command || '').trim();
+    return /^kill\s+(?:-(?:\d+|[A-Z]+)\s+)?\d+(?:\s+\d+)*\s*(?:2>\s*\/dev\/null)?$/.test(trimmed);
+}
+
+function isPortLsofKillSubstitution(command) {
+    const trimmed = String(command || '').trim();
+    return /^kill\s+(?:-(?:\d+|[A-Z]+)\s+)?\$\(\s*lsof\s+-ti:?\d+\s*\)\s*(?:2>\s*\/dev\/null)?$/.test(trimmed);
+}
+
+function isPortLsofXargsKill(command) {
+    const trimmed = String(command || '').trim();
+    return /^lsof\s+-ti:?\d+\s*\|\s*xargs\s+kill(?:\s+-(?:\d+|[A-Z]+))?\s*(?:2>\s*\/dev\/null)?(?:\s*;\s*echo\s+(?:"[^"]*"|'[^']*'|[A-Za-z0-9_ .:-]+))?$/.test(trimmed);
+}
+
+function isApprovedProcessCleanupCommand(command) {
+    const trimmed = String(command || '').trim();
+    if (!trimmed) return false;
+    if (isPortLsofXargsKill(trimmed)) return true;
+    const segments = splitCommand(trimmed);
+    if (segments.length === 0) return false;
+    return segments.every(segment => {
+        const sub = segment.trim();
+        return isNumericKillCommand(sub) ||
+            isPortLsofKillSubstitution(sub) ||
+            isPortLsofXargsKill(sub) ||
+            isQuotedMessage(sub);
+    });
+}
+
 // ═══════════════════════════════════════════════════════════════════
 // Section 3: Read-Only Command Allowlist
 // ═══════════════════════════════════════════════════════════════════
@@ -207,6 +242,10 @@ const COMMAND_ALLOWLIST = {
     find: { flags: { '-name': 'string', '-iname': 'string', '-path': 'string', '-ipath': 'string', '-type': 'string', '-maxdepth': 'number', '-mindepth': 'number', '-newer': 'string', '-size': 'string', '-mtime': 'string', '-atime': 'string', '-ctime': 'string', '-perm': 'string', '-user': 'string', '-group': 'string', '-not': 'none', '!': 'none', '-or': 'none', '-o': 'none', '-and': 'none', '-a': 'none', '-print': 'none', '-print0': 'none', '-empty': 'none', '-readable': 'none', '-writable': 'none', '-executable': 'none', '-follow': 'none', '-L': 'none', '-P': 'none', '-H': 'none', '-xdev': 'none', '-mount': 'none', '-daystart': 'none', '-regextype': 'string', '-regex': 'string', '-iregex': 'string' },
         blocked: ['-exec', '-execdir', '-ok', '-okdir', '-delete', '-fprint', '-fprint0', '-fls', '-fprintf'] },
 
+    // ── sed (read-only subset — NO -i/--in-place) ──
+    sed: { flags: { '-n': 'none', '--quiet': 'none', '--silent': 'none', '-E': 'none', '-r': 'none', '--regexp-extended': 'none', '-e': 'string', '--expression': 'string', '-f': 'string', '--file': 'string', '-l': 'number', '--line-length': 'number', '-u': 'none', '--unbuffered': 'none' },
+        blocked: ['-i', '--in-place', '-z', '--null-data', '-s', '--separate'] },
+
     // ── ls ──
     ls: { flags: { '-l': 'none', '-a': 'none', '-A': 'none', '-h': 'none', '--human-readable': 'none', '-R': 'none', '--recursive': 'none', '-S': 'none', '-t': 'none', '-r': 'none', '--reverse': 'none', '-1': 'none', '-d': 'none', '--directory': 'none', '-F': 'none', '--classify': 'none', '-i': 'none', '--inode': 'none', '-s': 'none', '--size': 'none', '--color': 'string', '--sort': 'string', '--time': 'string', '--group-directories-first': 'none', '-p': 'none', '-G': 'none', '-n': 'none', '--numeric-uid-gid': 'none' } },
 
@@ -295,6 +334,7 @@ const BLOCKED_PATTERNS = [
     /curl.*\|\s*(ba)?sh/,                                     // pipe curl to shell
     /wget.*\|\s*(ba)?sh/,                                     // pipe wget to shell
     /eval\s*\$\(/,                                            // eval command substitution
+    /\bfind\s+\/(?:\s|$)/,                                    // find / scans the whole VM
     /find\s.*-exec/,                                           // find with -exec (code execution)
     /find\s.*-delete/,                                         // find with -delete
 ];
@@ -349,6 +389,7 @@ function validateFlags(tokens, startIdx, config) {
         if (blocked) {
             for (const b of blocked) {
                 if (token === b || token.startsWith(b + '=')) return false;
+                if (/^-[A-Za-z]$/.test(b) && token.startsWith(b) && token.length > b.length) return false;
             }
         }
 
@@ -449,6 +490,14 @@ export function classifyCommand(command) {
 
     const trimmed = command.trim();
 
+    if (isApprovedProcessCleanupCommand(trimmed)) {
+        return {
+            classification: 'contained',
+            reason: 'Process cleanup by numeric PID or lsof port lookup; requires approval',
+            highRisk: true,
+        };
+    }
+
     // ── Step 1: Check for always-blocked patterns ──
     for (const pattern of BLOCKED_PATTERNS) {
         if (pattern.test(trimmed)) {
@@ -461,6 +510,10 @@ export function classifyCommand(command) {
         return { classification: 'blocked', reason: 'Contains command substitution (backticks or $())' };
     }
 
+    if (containsUnsafeOutputRedirection(trimmed)) {
+        return { classification: 'contained', reason: 'Writes shell output via redirection' };
+    }
+
     // ── Step 3: Split compound commands and classify each ──
     const subcommands = splitCommand(trimmed);
 
@@ -500,6 +553,31 @@ export function classifyCommand(command) {
     };
 }
 
+function containsUnsafeOutputRedirection(command) {
+    let inSingle = false;
+    let inDouble = false;
+    let escaped = false;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (escaped) { escaped = false; continue; }
+        if (ch === '\\' && !inSingle) { escaped = true; continue; }
+        if (ch === "'" && !inDouble) { inSingle = !inSingle; continue; }
+        if (ch === '"' && !inSingle) { inDouble = !inDouble; continue; }
+        if (inSingle || inDouble || ch !== '>') continue;
+
+        const prev = command[i - 1] || '';
+        const next = command[i + 1] || '';
+        if (next === '&') continue;
+        let cursor = next === '>' ? i + 2 : i + 1;
+        while (/\s/.test(command[cursor] || '')) cursor++;
+        const target = command.slice(cursor).match(/^[^\s;&|]+/)?.[0] || '';
+        if (target === '/dev/null') continue;
+        if (prev === '2' && target === '/dev/null') continue;
+        return true;
+    }
+    return false;
+}
+
 /**
  * Classify a single (non-compound) command.
  */

package/src/terminal/init.mjs

@@ -0,0 +1,145 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const FILES = {
+  'README.md': `# .kepler/ - project agent context
+
+Kepler reads and writes here to keep state between sessions.
+
+## Files Kepler writes
+- \`plan.md\` - current agent plan
+- \`goal.md\` - durable session goal
+- \`tasks/\` - task list
+- \`reports/*.md\` - end-of-turn mission reports
+- \`sessions/*.jsonl\` - turn transcripts
+- \`commands.log\` - command executions
+- \`approvals.log\` - HITL decisions
+- \`trust.json\` - approved patterns
+
+## Files you can write
+- \`config.json\` - project policy
+- \`project.md\` - durable project context
+- \`style.md\` - codebase conventions
+- \`hitl.md\` - approval guidance
+- \`skills/<name>/SKILL.md\` - reusable domain skills
+
+Format v1. Markdown files are intentionally hand-editable.
+`,
+  'config.json': JSON.stringify({
+    version: 1,
+    context: {
+      loadEveryTurn: ['KEPLER.md', 'project.md', 'style.md', 'goal.md', 'plan.md', 'tasks/*.md'],
+      showReloadNotice: true,
+    },
+    planning: { owner: 'auto', onUserEditedPlan: 'prefer_user_plan' },
+    tasks: { storage: 'project_markdown', syncTodoWrite: true, resumePrompt: true },
+    hitl: {
+      defaultScope: 'once',
+      allowSessionTrust: true,
+      allowProjectTrust: false,
+      reaskAfterMinutes: 30,
+    },
+    commands: {
+      enabled: ['map', 'probe', 'footprint', 'heal', 'align', 'distill', 'brief', 'rewind'],
+      dryRunDefault: false,
+    },
+  }, null, 2) + '\n',
+  'settings.json': JSON.stringify({
+    env: {},
+    permissions: {
+      shellAllowlist: ['git', 'npm', 'pnpm'],
+      editDenylist: ['**/*.env', 'secrets/**'],
+    },
+    hooks: {
+      UserPromptSubmit: [],
+      PreToolUse: [],
+      PostToolUse: [],
+      Stop: [],
+    },
+  }, null, 2) + '\n',
+  'KEPLER.md': `# Project
+
+## Quick Facts
+- Stack:
+- Test command:
+- Lint command:
+- Build command:
+
+## Key Directories
+
+## Code Style
+
+## Critical Rules
+`,
+  'project.md': '# Project Context\n\nAdd durable project context here.\n',
+  'style.md': '# Style\n\nAdd code and communication conventions here.\n',
+  'hitl.md': '# HITL Guidance\n\nAdd project-specific approval guidance here.\n',
+  'trust.json': JSON.stringify({ version: 1, rules: [] }, null, 2) + '\n',
+  'tasks/README.md': `# Kepler Tasks
+
+Checklist files are read every turn.
+
+- \`backlog.md\` - pending tasks
+- \`active.md\` - current task
+- \`done.md\` - completed tasks
+- \`blocked.md\` - waiting on input
+`,
+  'tasks/backlog.md': '# Backlog\n\n',
+  'tasks/active.md': '# Active\n\n',
+  'tasks/done.md': '# Done\n\n',
+  'tasks/blocked.md': '# Blocked\n\n',
+  'skills/starter/SKILL.md': `---
+name: starter
+description: Project-specific conventions and setup notes. Use when onboarding to this repo.
+---
+
+# Starter Skill
+
+Add reusable project knowledge here.
+`,
+  'commands/onboard.md': `---
+name: onboard
+description: Explore the project and record onboarding notes.
+---
+
+# Onboard
+
+Context:
+$ARGUMENTS
+
+Explore the codebase, ask clarifying questions, and record useful notes in .kepler/tasks/active.md.
+`,
+};
+
+export function scaffoldKeplerProject({ cwd = process.cwd(), force = false } = {}) {
+  const root = path.join(cwd, '.kepler');
+  const written = [];
+  const skipped = [];
+  for (const [rel, content] of Object.entries(FILES)) {
+    const filePath = path.join(root, rel);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    if (fs.existsSync(filePath) && !force) {
+      skipped.push(filePath);
+      continue;
+    }
+    fs.writeFileSync(filePath, content);
+    written.push(filePath);
+  }
+
+  const gitignore = path.join(root, '.gitignore');
+  if (!fs.existsSync(gitignore) || force) {
+    fs.writeFileSync(gitignore, 'settings.local.json\nsessions/\nreports/\n*.log\n');
+    written.push(gitignore);
+  }
+
+  return { root, written, skipped };
+}
+
+export async function runInitCommand(args = [], { cwd = process.cwd() } = {}) {
+  const force = args.includes('--force');
+  const result = scaffoldKeplerProject({ cwd, force });
+  process.stderr.write(`\x1b[32m✓\x1b[0m Initialized .kepler at ${result.root}\n`);
+  process.stderr.write(`  wrote ${result.written.length} files`);
+  if (result.skipped.length) process.stderr.write(`, skipped ${result.skipped.length} existing files`);
+  process.stderr.write('\n');
+}

package/src/terminal/main.mjs

@@ -47,6 +47,12 @@ async function main() {
     return;
   }
 
+  if (subcommand === 'init') {
+    const { runInitCommand } = await import('./init.mjs');
+    await runInitCommand(subcommandArgs);
+    return;
+  }
+
   if (subcommand === 'skills' || subcommand === 'skill') {
     const { runSkillsCommand } = await import('./skills.mjs');
     try {
@@ -103,6 +109,7 @@ async function main() {
     kepler dashboard          Open Kepler Pulse analytics dashboard
     kepler login              Sign in via browser
     kepler logout             Sign out and clear credentials
+    kepler init               Scaffold .kepler config, memory, hooks, tasks
     kepler version            Show version
 
   \x1b[1mAnalytics:\x1b[0m