pikiloop 0.4.0

package/dist/core/constants.js

@@ -0,0 +1,400 @@
+/**
+ * constants.ts — Centralized timeout, retry, and numeric constants.
+ *
+ * Grouped by domain / module so each subsystem can import only the
+ * bucket it needs.
+ */
+import path from 'node:path';
+// ---------------------------------------------------------------------------
+// MCP bridge
+// ---------------------------------------------------------------------------
+/** Timeouts for the per-stream MCP callback server and tool operations. */
+export const MCP_TIMEOUTS = {
+    /** Max time to wait for the sendFile callback to complete. */
+    sendFile: 60_000,
+    /** Max time to receive the HTTP request body on the callback server. */
+    requestBody: 10_000,
+    /** Server-level: max time for an entire request lifecycle. */
+    serverRequest: 90_000,
+    /** Server-level: max time to receive request headers. */
+    serverHeaders: 10_000,
+    /** Timeout for `codex mcp add` registration commands. */
+    codexMcpAdd: 10_000,
+    /** Timeout for `codex mcp remove` cleanup commands. */
+    codexMcpRemove: 5_000,
+};
+/** Maximum artifact file size the MCP bridge will accept (20 MB). */
+export const MCP_ARTIFACT_MAX_BYTES = 20 * 1024 * 1024;
+// ---------------------------------------------------------------------------
+// Dashboard
+// ---------------------------------------------------------------------------
+/** Timeouts used by the dashboard HTTP server and its status endpoints. */
+export const DASHBOARD_TIMEOUTS = {
+    /** Timeout for agent model discovery (Codex cold-start can be slow). */
+    agentStatusModels: 4_000,
+    /** Timeout for agent usage data fetch. */
+    agentStatusUsage: 1_500,
+    /** Timeout for channel credential validation requests. */
+    channelStatusValidation: 3_000,
+    /** How long validated channel states are cached before re-checking. */
+    channelStatusCacheTtl: 20_000,
+    /** How long the full agent-status response is cached (SWR). */
+    agentStatusCacheTtl: 30_000,
+    /** Timeout for agent npm install via the dashboard. */
+    agentInstall: 10 * 60_000,
+    /** Default timeout for dashboard-spawned shell commands. */
+    runCommand: 30_000,
+};
+// ---------------------------------------------------------------------------
+// Browser automation
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Brand / state-dir / env identifiers — single source of truth
+// ---------------------------------------------------------------------------
+/** Home state directory name: `~/.pikiloop`. */
+export const STATE_DIR_NAME = '.pikiloop';
+/** Env var prefix for all pikiloop-specific variables. */
+export const ENV_PREFIX = 'PIKILOOP_';
+/**
+ * Pre-rename (pikiclaw) identifiers. Kept ONLY for the one-time state-dir
+ * migration, the env-var fallback (see core/legacy-compat.ts) and project-skill
+ * discovery, so installs created before the rename are never orphaned. Safe to
+ * delete a couple of releases after the rename has propagated.
+ */
+export const LEGACY_STATE_DIR_NAME = '.pikiclaw';
+export const LEGACY_ENV_PREFIX = 'PIKICLAW_';
+/**
+ * Stable relative path for the managed Chrome profile under the home directory.
+ * Keep this outside config-specific directories so `npm run dev` and the main
+ * runtime share the same browser login state.
+ */
+export const MANAGED_BROWSER_PROFILE_SUBPATH = path.join(STATE_DIR_NAME, 'browser', 'chrome-profile');
+/** Base Playwright MCP args for the managed browser integration. */
+export const PLAYWRIGHT_MCP_PACKAGE_NAME = '@playwright/mcp';
+export const PLAYWRIGHT_MCP_PACKAGE_VERSION = '0.0.75';
+export const PLAYWRIGHT_MCP_PACKAGE_SPEC = `${PLAYWRIGHT_MCP_PACKAGE_NAME}@${PLAYWRIGHT_MCP_PACKAGE_VERSION}`;
+export const PLAYWRIGHT_MCP_BROWSER_ARGS = ['--browser', 'chrome', '--viewport-size', '1920x1080'];
+/**
+ * Env var name for pointing pikiloop at an external Chrome DevTools Protocol
+ * endpoint (e.g. `http://chromium:9222`) instead of launching a local Chrome.
+ * Primary use cases: Docker deployments that run a sidecar like
+ * `lscr.io/linuxserver/chromium`, or attaching to a remote browser the user
+ * already manages. When set, browser-supervisor skips every local-launch
+ * codepath (no Chrome detection, no pid SIGKILL on restart) and pipes the URL
+ * through to Playwright MCP's `--cdp-endpoint`.
+ */
+export const PIKILOOP_BROWSER_CDP_URL_ENV = 'PIKILOOP_BROWSER_CDP_URL';
+/** Dashboard session pagination limits. */
+export const DASHBOARD_PAGINATION = {
+    defaultPageSize: 6,
+    maxPageSize: 30,
+};
+/** Timeouts for macOS permission checks and JXA scripts (dashboard). */
+export const DASHBOARD_PERMISSION_TIMEOUTS = {
+    /** Default timeout for osascript / JXA calls. */
+    jxaDefault: 5_000,
+    /** Timeout for screencapture permission probe. */
+    screenRecordingProbe: 5_000,
+    /** Timeout for CGPreflight screen capture check. */
+    screenRecordingPreflight: 4_000,
+    /** Timeout for CGRequest screen capture request. */
+    screenRecordingRequest: 6_000,
+    /** Timeout for `open` command to launch System Preferences. */
+    openSystemPreferences: 3_000,
+    /** Timeout for parent process tree detection. */
+    detectTerminal: 3_000,
+};
+/**
+ * TTL for cached dashboard permission / host-terminal probes. `/api/state` is
+ * polled (~1.5s while a channel validates) and each probe spawns subprocesses
+ * (screencapture, an `ls` shell, a `ps` process-tree walk), so the raw checks
+ * must not run per request. The host terminal is immutable per process;
+ * permission grants change rarely and `requestPermission` invalidates the cache
+ * on user action, so a short TTL surfaces grants without per-request spawns.
+ */
+export const DASHBOARD_PERMISSION_CACHE_TTL_MS = 30_000;
+// ---------------------------------------------------------------------------
+// CLI / Daemon
+// ---------------------------------------------------------------------------
+/** Daemon (watchdog) restart timing constants. */
+export const DAEMON_TIMEOUTS = {
+    /** Initial delay before restarting a crashed child. */
+    restartDelay: 3_000,
+    /** Maximum back-off delay for repeated rapid crashes. */
+    maxRestartDelay: 60_000,
+    /** If the child runs shorter than this, treat it as a rapid crash. */
+    rapidCrashWindow: 10_000,
+    /** Polling interval while waiting for dashboard config to become ready. */
+    configPollInterval: 1_000,
+};
+// ---------------------------------------------------------------------------
+// Bot orchestration / shutdown
+// ---------------------------------------------------------------------------
+/** Time to wait before force-exiting during bot shutdown. */
+export const BOT_SHUTDOWN_FORCE_EXIT_MS = 3_000;
+// ---------------------------------------------------------------------------
+// Bot runtime
+// ---------------------------------------------------------------------------
+/** Bot-level timing constants. */
+export const BOT_TIMEOUTS = {
+    /** Default run timeout for agent streams (seconds). */
+    defaultRunTimeoutS: 7200,
+    /** Interval for macOS user-activity caffeinate pulses. */
+    macosUserActivityPulseInterval: 20_000,
+    /** Timeout (seconds) for the caffeinate assertion per pulse. */
+    macosUserActivityPulseTimeoutS: 30,
+};
+// ---------------------------------------------------------------------------
+// Live preview (stream feedback)
+// ---------------------------------------------------------------------------
+/** Timing constants for the channel-agnostic live preview controller. */
+export const STREAM_PREVIEW_TIMEOUTS = {
+    /** Interval between heartbeat edits that refresh the elapsed timer. */
+    heartbeat: 5_000,
+    /** Interval between typing indicator pulses. */
+    typing: 4_000,
+    /** After this idle time, a "stalled" notice is shown. */
+    stalledNotice: 15_000,
+};
+// ---------------------------------------------------------------------------
+// Channels — Telegram
+// ---------------------------------------------------------------------------
+/** Telegram channel transport constants. */
+export const TELEGRAM_LIMITS = {
+    /** Maximum text length per Telegram message. */
+    maxMessageLength: 4096,
+    /** Maximum file size for send/receive (20 MB). */
+    fileMaxBytes: 20 * 1024 * 1024,
+    /** Maximum back-off delay for polling/connect retries. */
+    maxRetryDelay: 60_000,
+};
+// ---------------------------------------------------------------------------
+// Channels — Feishu
+// ---------------------------------------------------------------------------
+/** Feishu channel transport constants. */
+export const FEISHU_LIMITS = {
+    /** Card markdown budget (card JSON limit ~30 KB). */
+    cardMax: 28_000,
+    /** Maximum file size for send/receive (20 MB). */
+    fileMaxBytes: 20 * 1024 * 1024,
+    /** Maximum back-off delay for WebSocket reconnection retries. */
+    wsStartRetryMaxDelay: 60_000,
+    /** Initial retry delay for Feishu WebSocket connection. */
+    wsStartRetryInitialDelay: 3_000,
+};
+/** Feishu bot rendering limit for card payloads. */
+export const FEISHU_BOT_CARD_MAX = 25_000;
+// ---------------------------------------------------------------------------
+// Channels — Weixin
+// ---------------------------------------------------------------------------
+/** Weixin channel transport constants. */
+export const WEIXIN_LIMITS = {
+    /** Conservative text split budget for plain-text replies. */
+    maxMessageLength: 1200,
+    /** Long-poll timeout for getupdates. */
+    longPollTimeout: 35_000,
+    /** Maximum back-off delay for polling retries. */
+    maxRetryDelay: 60_000,
+};
+// ---------------------------------------------------------------------------
+// Channels — Slack
+// ---------------------------------------------------------------------------
+/** Slack channel transport constants. */
+export const SLACK_LIMITS = {
+    /** Slack chat.postMessage hard limit is 40000; cap at 35k for safety. */
+    maxMessageLength: 35_000,
+    /** Slack file upload size cap (1 GB); we keep parity with other channels at 20 MB. */
+    fileMaxBytes: 20 * 1024 * 1024,
+    /** Maximum back-off delay for socket-mode reconnect retries. */
+    maxRetryDelay: 60_000,
+    /** Initial back-off delay for socket-mode reconnect. */
+    initialRetryDelay: 3_000,
+};
+// ---------------------------------------------------------------------------
+// Channels — Discord
+// ---------------------------------------------------------------------------
+/** Discord channel transport constants. */
+export const DISCORD_LIMITS = {
+    /** Hard message cap is 2000 chars; leave a small buffer. */
+    maxMessageLength: 1900,
+    /** File size cap for non-Nitro guilds is 25 MB; we keep parity at 20 MB. */
+    fileMaxBytes: 20 * 1024 * 1024,
+    /** Maximum back-off delay for gateway reconnect retries. */
+    maxRetryDelay: 60_000,
+    /** Initial back-off delay for gateway reconnect. */
+    initialRetryDelay: 3_000,
+};
+// ---------------------------------------------------------------------------
+// Channels — DingTalk
+// ---------------------------------------------------------------------------
+/** DingTalk channel transport constants. */
+export const DINGTALK_LIMITS = {
+    /** Conservative text limit per message (markdown segments split here). */
+    maxMessageLength: 5_000,
+    /** Maximum back-off delay for stream reconnect retries. */
+    maxRetryDelay: 60_000,
+    /** Initial back-off delay for stream reconnect. */
+    initialRetryDelay: 3_000,
+};
+// ---------------------------------------------------------------------------
+// Channels — WeChat Work (企业微信 智能机器人)
+// ---------------------------------------------------------------------------
+/** WeChat Work Smart Bot WebSocket transport constants. */
+export const WECOM_LIMITS = {
+    /** Smart Bot text message hard cap is roughly 5KB chars. */
+    maxMessageLength: 4_000,
+    /** Heartbeat interval to keep the websocket alive. */
+    heartbeatInterval: 30_000,
+    /** Maximum back-off delay for websocket reconnect retries. */
+    maxRetryDelay: 60_000,
+    /** Initial back-off delay for websocket reconnect. */
+    initialRetryDelay: 1_000,
+    /** Default smart bot websocket endpoint. */
+    defaultEndpoint: 'wss://openws.work.weixin.qq.com/wssvr/',
+};
+// ---------------------------------------------------------------------------
+// Config validation
+// ---------------------------------------------------------------------------
+/** Timeouts for channel credential validation flows. */
+export const VALIDATION_TIMEOUTS = {
+    /** Default timeout for Feishu credential validation. */
+    feishuDefault: 15_000,
+    /** Timeout for fetching Feishu bot info after credential validation. */
+    feishuBotInfo: 5_000,
+    /** Timeout for Telegram token validation (setup wizard). */
+    telegramToken: 8_000,
+    /** Default timeout for Weixin credential validation. */
+    weixinDefault: 8_000,
+    /** Long-poll timeout for dashboard QR login wait calls. */
+    weixinQrPoll: 35_000,
+    /** Default timeout for Slack credential validation. */
+    slackDefault: 8_000,
+    /** Default timeout for Discord credential validation. */
+    discordDefault: 8_000,
+    /** Default timeout for DingTalk credential validation (gettoken endpoint). */
+    dingtalkDefault: 8_000,
+    /** Default timeout for WeChat Work bot validation handshake. */
+    wecomDefault: 8_000,
+};
+// ---------------------------------------------------------------------------
+// Agent auto-update
+// ---------------------------------------------------------------------------
+/** Timeouts for the background agent auto-update system. */
+export const AGENT_UPDATE_TIMEOUTS = {
+    /** After this duration a stale lock file is removed. */
+    lockStale: 60 * 60_000,
+    /** Maximum time for an agent update command to run. */
+    commandTimeout: 15 * 60_000,
+    /** Timeout for `npm prefix -g`. */
+    npmPrefix: 10_000,
+    /** Timeout for `npm view <pkg> version`. */
+    npmView: 20_000,
+};
+// ---------------------------------------------------------------------------
+// Code agent (shared layer)
+// ---------------------------------------------------------------------------
+/** Caching TTLs for agent detection and version lookups. */
+export const AGENT_DETECT_TIMEOUTS = {
+    /** How long a binary-detection result is cached. */
+    detectTtl: 1_000,
+    /** How long a version string is cached. */
+    versionTtl: 5 * 60_000,
+    /** Timeout for the `--version` command itself. */
+    versionCommand: 3_000,
+};
+/** Grace period added to the user-configured timeout before hard-killing the agent. */
+export const AGENT_STREAM_HARD_KILL_GRACE_MS = 10_000;
+/**
+ * On user abort, wait this long for the agent CLI to flush its session JSONL
+ * (including any `[Request interrupted]` marker) before falling back to
+ * SIGTERM. Keeps the partial assistant response persisted so the next task,
+ * resumed via --resume, can see it in the transcript.
+ */
+export const AGENT_GRACEFUL_ABORT_GRACE_MS = 2_000;
+/**
+ * claude-tui stall watchdog — claude CLI is known to freeze mid-turn (observed
+ * 2026-06-02 on 2.1.160: after a tool_result lands, the next assistant segment
+ * never starts; the process stays alive, the JSONL goes permanently quiet, no
+ * Stop hook ever fires). When every live signal (main JSONL, hook tool events,
+ * sub-agent sidecars, hook lifecycle state) is silent past the threshold the
+ * driver SIGTERMs the PTY and the dispatch wrapper auto-resumes the session
+ * once. Quiet threshold must sit safely above the longest healthy gap between
+ * JSONL events — a single max-effort inference can take a few minutes before
+ * its first content block lands.
+ */
+export const CLAUDE_TUI_STALL_QUIET_MS = 10 * 60_000;
+/**
+ * Stall threshold while a hook-reported tool is still executing (PreToolUse
+ * seen, no matching PostToolUse). Claude's own Bash timeout caps foreground
+ * commands at ~10 minutes and fires PostToolUse either way, so a pending tool
+ * silent for this long means the freeze hit mid-execution.
+ */
+export const CLAUDE_TUI_STALL_PENDING_TOOL_MS = 30 * 60_000;
+/**
+ * Fast-path stall: a healthy claude TUI repaints continuously while a turn is
+ * in flight (spinner frames, stream ticks, status line) — the PTY never goes
+ * byte-silent for minutes. If NO PTY output arrives for this long AND every
+ * structured signal is equally quiet, the process event loop itself is gone
+ * (the 2.1.160 mid-turn freeze: attachment lands → next API call never
+ * assembles). Declare the stall now instead of waiting out the 10/30-minute
+ * quiet thresholds — turns a 10-30 分钟「卡死」into a ~3 分钟自愈。
+ * False-positive safe: long thinking / long Bash keep painting frames, which
+ * refreshes the PTY signal and defers this path to the slow thresholds.
+ */
+export const CLAUDE_TUI_STALL_PTY_DEAD_MS = 3 * 60_000;
+/**
+ * Settle window after the TUI paints the "selected model is unavailable" banner
+ * (a 404 model_not_found). The notice is terminal — claude paints it then idles
+ * at the REPL forever: no JSONL is written, no Stop hook fires. We wait this
+ * brief window to cross-validate that nothing substantive followed (the banner
+ * alone is evidence, not a verdict — same discipline as resolveClaudeTuiLimitOutcome)
+ * before ending the turn, instead of waiting out the 3–10 minute stall watchdog.
+ */
+export const CLAUDE_TUI_MODEL_ERROR_SETTLE_MS = 2_500;
+/**
+ * TTL for the post-Stop `hold-background` path. The hold protects
+ * run_in_background agents living inside the claude process — but a live
+ * agent keeps emitting hook/sidecar/JSONL traffic. If the hold sees no
+ * activity on ANY channel for this long, the pending count is phantom (lost
+ * <task-notification>, agents already finished): release as a NORMAL Stop.
+ * Without this TTL the stall watchdog eventually fires instead, mislabels the
+ * cleanly-finished turn 'stalled', and injects a confusing auto-resume prompt
+ * (the「回合明明答完了还被注入 Continue」symptom).
+ */
+export const CLAUDE_TUI_STOP_HOLD_QUIET_TTL_MS = 10 * 60_000;
+/** Codex-specific grace period added to the user-configured timeout. */
+export const CODEX_STREAM_HARD_KILL_GRACE_MS = 5_000;
+/**
+ * If a session file was modified more recently than this threshold,
+ * consider the session "running". Shared across Claude, Codex, and Gemini drivers.
+ */
+export const SESSION_RUNNING_THRESHOLD_MS = 10_000;
+// ---------------------------------------------------------------------------
+// Driver — Codex
+// ---------------------------------------------------------------------------
+/** Timeout for the Codex app-server to become ready after spawn. */
+export const CODEX_APPSERVER_SPAWN_TIMEOUT_MS = 15_000;
+// ---------------------------------------------------------------------------
+// Driver — Gemini
+// ---------------------------------------------------------------------------
+/** Timeouts for Gemini usage / quota queries. */
+export const GEMINI_USAGE_TIMEOUTS = {
+    /** Max time for the curl quota request. */
+    request: 5_000,
+    /** Extra buffer added to the curl timeout for the execSync wrapper. */
+    execSyncBuffer: 3_000,
+};
+// ---------------------------------------------------------------------------
+// User config sync
+// ---------------------------------------------------------------------------
+/** Default interval for the user config file sync poll. */
+export const USER_CONFIG_SYNC_DEFAULT_INTERVAL_MS = 1_000;
+// ---------------------------------------------------------------------------
+// Git status
+// ---------------------------------------------------------------------------
+/**
+ * Upper bound for a single `git status` invocation. Bounded so a huge repo or a
+ * stuck `.git/index.lock` can never block `/status` or a workspace poll. Matches
+ * the timeout used by the existing `/api/git-changes` endpoint.
+ */
+export const GIT_STATUS_TIMEOUT_MS = 5_000;

package/dist/core/git.js

@@ -0,0 +1,145 @@
+/**
+ * Git working-tree status as a cross-platform OS primitive.
+ *
+ * One bounded `git status --porcelain=v2 --branch` invocation, parsed into a
+ * structured {@link GitStatus}. Porcelain v2 is machine-stable across git
+ * versions and locales, so we count entry lines rather than scraping human
+ * output. A single reader feeds both the IM `/status` command and the Dashboard
+ * workspace view — no git logic is duplicated in the channels or the SPA.
+ */
+import { spawnSync } from 'node:child_process';
+import { GIT_STATUS_TIMEOUT_MS } from './constants.js';
+/**
+ * Read the git status of `dir`. Returns `null` for a non-repo, a missing git
+ * binary, or a timeout — callers simply omit the git section. Never throws.
+ *
+ * Walks up from `dir` like git itself, so a workspace nested below the repo root
+ * is still recognised. Uses `GIT_OPTIONAL_LOCKS=0` to avoid contending with
+ * other git processes for the index lock.
+ */
+export function readGitStatus(dir) {
+    if (!dir)
+        return null;
+    try {
+        const result = spawnSync('git', ['status', '--porcelain=v2', '--branch', '--untracked-files=normal'], {
+            cwd: dir,
+            timeout: GIT_STATUS_TIMEOUT_MS,
+            encoding: 'utf-8',
+            env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' },
+        });
+        if (result.error || result.status !== 0 || typeof result.stdout !== 'string')
+            return null;
+        return parseGitStatusV2(result.stdout);
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse `git status --porcelain=v2 --branch` output. Exported for testing. */
+export function parseGitStatusV2(stdout) {
+    let branch = null;
+    let detached = false;
+    let shortSha = null;
+    let upstream = null;
+    let ahead = 0;
+    let behind = 0;
+    let staged = 0;
+    let unstaged = 0;
+    let untracked = 0;
+    for (const line of stdout.split('\n')) {
+        if (!line)
+            continue;
+        if (line.startsWith('# branch.head ')) {
+            const value = line.slice('# branch.head '.length).trim();
+            if (value === '(detached)') {
+                detached = true;
+                branch = null;
+            }
+            else {
+                branch = value;
+            }
+        }
+        else if (line.startsWith('# branch.oid ')) {
+            const value = line.slice('# branch.oid '.length).trim();
+            if (value && value !== '(initial)')
+                shortSha = value.slice(0, 7);
+        }
+        else if (line.startsWith('# branch.upstream ')) {
+            upstream = line.slice('# branch.upstream '.length).trim() || null;
+        }
+        else if (line.startsWith('# branch.ab ')) {
+            const m = line.match(/\+(\d+)\s+-(\d+)/);
+            if (m) {
+                ahead = parseInt(m[1], 10);
+                behind = parseInt(m[2], 10);
+            }
+        }
+        else if (line.startsWith('1 ') || line.startsWith('2 ')) {
+            // Ordinary / renamed entry: field 2 is the XY status (X=index, Y=worktree).
+            const xy = line.split(' ')[1] || '..';
+            if (xy[0] && xy[0] !== '.')
+                staged++;
+            if (xy[1] && xy[1] !== '.')
+                unstaged++;
+        }
+        else if (line.startsWith('u ')) {
+            // Unmerged (conflict) — count as a working-tree change.
+            unstaged++;
+        }
+        else if (line.startsWith('? ')) {
+            untracked++;
+        }
+    }
+    return {
+        branch,
+        detached,
+        shortSha,
+        upstream,
+        ahead,
+        behind,
+        staged,
+        unstaged,
+        untracked,
+        changed: staged + unstaged + untracked,
+    };
+}
+/**
+ * Render a {@link GitStatus} into a single friendly line (no channel-specific
+ * markup), e.g.:
+ *
+ *   main  ↑2 ↓1  ·  5 changed (3 staged · 2 untracked)
+ *   feature/x  ·  no upstream  ·  clean
+ *   (detached a1b2c3d)  ·  1 changed
+ *
+ * Returns `null` when there is no git status to show, so callers can omit the
+ * line entirely.
+ */
+export function formatGitStatusLine(git) {
+    if (!git)
+        return null;
+    const head = git.detached
+        ? `(detached${git.shortSha ? ` ${git.shortSha}` : ''})`
+        : git.branch || '(unknown)';
+    let lead = head;
+    if (git.ahead || git.behind) {
+        const ab = [git.ahead ? `↑${git.ahead}` : '', git.behind ? `↓${git.behind}` : '']
+            .filter(Boolean)
+            .join(' ');
+        lead += `  ${ab}`;
+    }
+    const segments = [lead];
+    if (!git.detached && !git.upstream)
+        segments.push('no upstream');
+    if (git.changed > 0) {
+        const detail = [
+            git.staged ? `${git.staged} staged` : '',
+            git.unstaged ? `${git.unstaged} unstaged` : '',
+            git.untracked ? `${git.untracked} untracked` : '',
+        ].filter(Boolean);
+        segments.push(`${git.changed} changed${detail.length ? ` (${detail.join(' · ')})` : ''}`);
+    }
+    else {
+        segments.push('clean');
+    }
+    return segments.join('  ·  ');
+}

package/dist/core/legacy-compat.js

@@ -0,0 +1,60 @@
+/**
+ * One-time backward-compat shims for the pikiclaw → pikiloop rename.
+ *
+ * Both run once at process startup — BEFORE any config is read or any lock /
+ * PID file is taken — so existing installs keep their settings, credentials,
+ * managed browser profile and skills with zero user action.
+ *
+ * Remove this file (and the LEGACY_* constants) a couple of releases after the
+ * rename has propagated.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { STATE_DIR_NAME, LEGACY_STATE_DIR_NAME, ENV_PREFIX, LEGACY_ENV_PREFIX, } from './constants.js';
+/**
+ * Mirror every `PIKICLAW_*` env var onto the matching `PIKILOOP_*` name when the
+ * new name is unset. Covers user-set vars (shell profiles, docker-compose,
+ * systemd units) AND internal ones a still-old parent process may have set
+ * across an upgrade boundary (e.g. PIKICLAW_DAEMON_CHILD, PIKICLAW_FROM_LAUNCHD).
+ */
+export function hydrateLegacyEnv() {
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value === undefined)
+            continue;
+        if (!key.startsWith(LEGACY_ENV_PREFIX))
+            continue;
+        const mapped = ENV_PREFIX + key.slice(LEGACY_ENV_PREFIX.length);
+        if (process.env[mapped] === undefined)
+            process.env[mapped] = value;
+    }
+}
+/**
+ * Migrate `~/.pikiclaw` → `~/.pikiloop` exactly once.
+ *
+ * No-op when the new dir already exists (migrated or fresh install) or the old
+ * one is absent (brand-new user). A same-volume rename is atomic; on a
+ * cross-device failure we fall back to a recursive copy and deliberately leave
+ * the old dir in place so a partial/failed copy can never lose user data.
+ */
+export function migrateLegacyStateDir() {
+    try {
+        const home = os.homedir();
+        const next = path.join(home, STATE_DIR_NAME);
+        const prev = path.join(home, LEGACY_STATE_DIR_NAME);
+        if (fs.existsSync(next))
+            return;
+        if (!fs.existsSync(prev))
+            return;
+        try {
+            fs.renameSync(prev, next);
+        }
+        catch {
+            // Cross-device or in-use: copy and keep the original as a safety net.
+            fs.cpSync(prev, next, { recursive: true });
+        }
+    }
+    catch {
+        // Best-effort only — never block startup on migration.
+    }
+}