instar 1.0.13 → 1.1.1

package/dist/core/AgentWorktreeDetector.js

@@ -0,0 +1,329 @@
+// safe-git-allow: detector reads worktree list against a pre-validated
+//   instar repo via execFileSync. SafeGitExecutor.readSync would invoke
+//   the source-tree guard which refuses operations targeting the instar
+//   source tree — exactly the path the detector is here to inspect. The
+//   call is bounded (read-only verb, fixed args, 2s timeout, validated
+//   repo path) so direct execFileSync is the right level here.
+/**
+ * AgentWorktreeDetector — Layer 4 of the agent worktree convention.
+ *
+ * Runs once per agent startup as part of the lifeline health-check surface.
+ * Inspects the canonical instar repo's worktree list and emits an
+ * AttentionItem (or, when no Telegram adapter is configured, appends to a
+ * dedicated JSONL fallback) for every worktree that lives outside an
+ * agent's `<agent_home>/.worktrees/` area.
+ *
+ * Signal-only by design. Never blocks, never moves, never deletes. The
+ * operator decides what to do with each surfaced item — `git worktree
+ * move` to the safe location or accept the residual.
+ *
+ * Spec: docs/specs/AGENT-WORKTREE-CONVENTION-SPEC.md §"Layer 4 — Lifeline
+ * detector (in v1, signal only)".
+ *
+ * Signal vs authority: the detector's only decision rule is path-based
+ * (`worktree_path` starts with `realpath(<agent_home>/.worktrees)` for
+ * some registered agent). The audit ledger from Layer 1 is **not**
+ * consumed as an allowlist — the rule lives here and only here, so future
+ * maintainers can't drift it into ledger-membership.
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { resolveInstarRepo, worktreeDedupeKey } from './InstarWorktreeManager.js';
+import { loadRegistry } from './AgentRegistry.js';
+// ── Helpers ──────────────────────────────────────────────────────────────
+const DEFAULT_GIT_TIMEOUT_MS = 2000;
+const DEDUPE_WINDOW_MS = 24 * 60 * 60 * 1000;
+const AUDIT_DIR_NAME = 'audit';
+const FALLBACK_BASENAME = 'worktree-detector.jsonl';
+function realpathOrInput(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        // @silent-fallback-ok — git's worktree list reports stale entries; we
+        //   return the raw path so the caller's filter (existsSync below) can
+        //   classify them as stale and skip them.
+        return p;
+    }
+}
+function parseWorktreeListPorcelain(output) {
+    // Format:
+    //   worktree /abs/path
+    //   HEAD <sha> | branch <ref>
+    //   [bare]
+    //   <blank>
+    // Each record ends with a blank line; the last record may not.
+    const entries = [];
+    const lines = output.split('\n');
+    let current = null;
+    for (const line of lines) {
+        if (line.startsWith('worktree ')) {
+            if (current)
+                entries.push(current);
+            current = { path: line.slice('worktree '.length).trim(), bare: false };
+        }
+        else if (line.trim() === 'bare' && current) {
+            current.bare = true;
+        }
+        else if (line.trim() === '' && current) {
+            entries.push(current);
+            current = null;
+        }
+    }
+    if (current)
+        entries.push(current);
+    return entries;
+}
+function isUnderAnySafeRoot(worktreeReal, safeRoots) {
+    for (const root of safeRoots) {
+        const rootWithSep = root.endsWith(path.sep) ? root : root + path.sep;
+        if (worktreeReal === root || worktreeReal.startsWith(rootWithSep))
+            return true;
+    }
+    return false;
+}
+function appendFallback(fallbackPath, line) {
+    const dir = path.dirname(fallbackPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const flags = fs.constants.O_APPEND | fs.constants.O_CREAT | fs.constants.O_WRONLY |
+        fs.constants.O_NOFOLLOW;
+    let fd;
+    try {
+        fd = fs.openSync(fallbackPath, flags, 0o600);
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'ELOOP') {
+            throw new Error(`detector fallback: ${fallbackPath} is a symlink — refused`);
+        }
+        throw err;
+    }
+    try {
+        const st = fs.fstatSync(fd);
+        const euid = process.geteuid?.() ?? -1;
+        if (euid !== -1 && st.uid !== euid) {
+            throw new Error(`detector fallback: ${fallbackPath} owner uid ${st.uid} != euid ${euid}`);
+        }
+        if ((st.mode & 0o077) !== 0) {
+            throw new Error(`detector fallback: ${fallbackPath} mode 0${(st.mode & 0o777).toString(8)} grants group/other access`);
+        }
+        fs.writeSync(fd, JSON.stringify(line) + '\n');
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function readRecentDedupeKeys(fallbackPath) {
+    if (!fs.existsSync(fallbackPath))
+        return new Set();
+    const keys = new Set();
+    const cutoff = Date.now() - DEDUPE_WINDOW_MS;
+    let content;
+    try {
+        content = fs.readFileSync(fallbackPath, 'utf-8');
+    }
+    catch {
+        // @silent-fallback-ok — unreadable fallback file means we lose dedupe
+        //   for this run, which is acceptable (worst case: a duplicate JSONL
+        //   line for an outage event). Returning empty Set is the safe fallback.
+        return keys;
+    }
+    for (const line of content.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (!parsed.dedupeKey || !parsed.ts)
+                continue;
+            const ts = Date.parse(parsed.ts);
+            if (Number.isNaN(ts) || ts < cutoff)
+                continue;
+            keys.add(parsed.dedupeKey);
+        }
+        catch {
+            // @silent-fallback-ok — tolerate torn last line per spec; skip it.
+        }
+    }
+    return keys;
+}
+// ── Detector entrypoint ──────────────────────────────────────────────────
+export async function runDetection(opts) {
+    const result = {
+        enumerated: 0,
+        skipped: 0,
+        emitted: 0,
+        deduped: 0,
+        timedOut: false,
+    };
+    let output;
+    try {
+        // safe-git-allow: detector reads worktree list against a pre-validated
+        //   instar repo; SafeGitExecutor.readSync would also work but adds the
+        //   source-tree check (which would refuse the very repo we're inspecting).
+        //   The repo path is validated by the caller via resolveInstarRepo.
+        output = execFileSync('git', ['-C', opts.instarRepo, 'worktree', 'list', '--porcelain'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: opts.gitTimeoutMs ?? DEFAULT_GIT_TIMEOUT_MS,
+        }).trim();
+    }
+    catch (err) {
+        const e = err;
+        if (e.signal === 'SIGTERM' || e.code === 'ETIMEDOUT') {
+            result.timedOut = true;
+            // Surface a single attention item so the timeout is observable.
+            await emitOrFallback({
+                id: 'worktree-detector-timeout',
+                title: 'Worktree detector skipped',
+                summary: `git worktree list against ${opts.instarRepo} did not return within ${opts.gitTimeoutMs ?? DEFAULT_GIT_TIMEOUT_MS}ms`,
+                category: 'worktree-misplaced',
+                priority: 'LOW',
+                sourceContext: opts.instarRepo,
+            }, opts, result, true);
+            return result;
+        }
+        throw err;
+    }
+    const entries = parseWorktreeListPorcelain(output);
+    result.enumerated = entries.length;
+    const instarRepoReal = realpathOrInput(opts.instarRepo);
+    const safeRootsReal = opts.safeRoots.map((r) => realpathOrInput(r));
+    for (const entry of entries) {
+        const entryReal = realpathOrInput(entry.path);
+        // Skip the main checkout entry.
+        if (entryReal === instarRepoReal) {
+            result.skipped++;
+            continue;
+        }
+        // Skip bare entries.
+        if (entry.bare) {
+            result.skipped++;
+            continue;
+        }
+        // Skip stale (no longer on disk).
+        if (!fs.existsSync(entry.path)) {
+            result.skipped++;
+            continue;
+        }
+        // Properly-placed under some agent home — skip.
+        if (isUnderAnySafeRoot(entryReal, safeRootsReal)) {
+            result.skipped++;
+            continue;
+        }
+        const dedupeKey = worktreeDedupeKey(entryReal);
+        await emitOrFallback({
+            id: dedupeKey,
+            title: 'Worktree placed outside agent home',
+            summary: `${entryReal} is not inside any registered agent's .worktrees/ — sandbox-revoke risk.`,
+            description: 'Per docs/specs/AGENT-WORKTREE-CONVENTION-SPEC.md, worktrees of the shared instar repo should live at <agent_home>/.worktrees/<slug>/. ' +
+                'Use `instar worktree create <branch>` for new worktrees, or `git worktree move <old> <new>` to relocate this one. ' +
+                'The detector does not move or delete anything.',
+            category: 'worktree-misplaced',
+            priority: 'LOW',
+            sourceContext: entryReal,
+        }, opts, result, false);
+    }
+    return result;
+}
+async function emitOrFallback(item, opts, result, skipDedupe) {
+    if (opts.emitAttention) {
+        // AttentionQueue owns dedupe via item.id collision.
+        await opts.emitAttention(item);
+        result.emitted++;
+        return;
+    }
+    const fallbackPath = opts.fallbackPath ?? path.join(opts.stateDir, AUDIT_DIR_NAME, FALLBACK_BASENAME);
+    if (!skipDedupe) {
+        const recent = readRecentDedupeKeys(fallbackPath);
+        if (recent.has(item.id)) {
+            result.deduped++;
+            return;
+        }
+    }
+    appendFallback(fallbackPath, {
+        ts: new Date().toISOString(),
+        dedupeKey: item.id,
+        category: item.category,
+        priority: item.priority,
+        title: item.title,
+        summary: item.summary,
+        description: item.description,
+        sourceContext: item.sourceContext,
+    });
+    result.emitted++;
+}
+// ── Public helper: enumerate safe roots from the registry ────────────────
+export function enumerateSafeRoots() {
+    const roots = [];
+    const instarHome = path.join(os.homedir(), '.instar');
+    for (const entry of loadRegistry().entries) {
+        // Only agents that live under ~/.instar/agents/<name>/ qualify — those
+        // are the ones the convention applies to. Project-bound agents have
+        // worktrees in the project dir, which the lifeline detector doesn't
+        // police.
+        const candidate = path.join(instarHome, 'agents', entry.name, '.worktrees');
+        try {
+            const real = fs.realpathSync(candidate);
+            roots.push(real);
+        }
+        catch {
+            // @silent-fallback-ok — agent's .worktrees/ doesn't exist yet (no
+            //   `instar worktree create` calls or no Layer 3 migrator run).
+            //   Skip — there's nothing under it to be a "safe root" for.
+        }
+    }
+    return roots;
+}
+/**
+ * Per spec: the detector uses a deterministic source (config or default
+ * chain), NOT `INSTAR_REPO` env var, because env vars can differ between
+ * lifeline boot and interactive sessions and the detector wants
+ * consistent results across both.
+ */
+export function resolveDetectorInstarRepo(opts = {}) {
+    // Read worktree.repoPath from config (deterministic operator-supplied path).
+    const resolved = opts.configPath ?? path.join(os.homedir(), '.instar', 'config.json');
+    let configRepoPath = null;
+    if (fs.existsSync(resolved)) {
+        try {
+            const raw = JSON.parse(fs.readFileSync(resolved, 'utf-8'));
+            const wt = raw.worktree;
+            if (wt && typeof wt.repoPath === 'string' && wt.repoPath.trim()) {
+                configRepoPath = wt.repoPath.trim();
+            }
+        }
+        catch {
+            // @silent-fallback-ok — config malformed; fall through to default chain.
+        }
+    }
+    const candidateChain = [];
+    if (configRepoPath)
+        candidateChain.push(configRepoPath);
+    if (opts.fallbackChain) {
+        candidateChain.push(...opts.fallbackChain);
+    }
+    else {
+        const home = opts.homeDir ?? os.homedir();
+        candidateChain.push(path.join(home, 'Documents', 'Projects', 'instar'));
+        candidateChain.push(path.join(home, 'instar'));
+    }
+    // Reuse the same integrity validation Layer 1 uses for INSTAR_REPO so
+    // the detector and the CLI never disagree about what "the instar repo"
+    // is. Skip the env-var path by passing an empty `env`.
+    try {
+        const repo = resolveInstarRepo({
+            env: {},
+            fallbackChain: candidateChain,
+            configPath: resolved,
+        });
+        return repo.repoPath;
+    }
+    catch {
+        // @silent-fallback-ok — no validated instar repo reachable; detector
+        //   simply doesn't run this tick. Caller decides whether to log/skip.
+        return null;
+    }
+}
+//# sourceMappingURL=AgentWorktreeDetector.js.map

package/dist/core/AgentWorktreeDetector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentWorktreeDetector.js","sourceRoot":"","sources":["../../src/core/AgentWorktreeDetector.ts"],"names":[],"mappings":"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"}

package/dist/core/InstarWorktreeManager.d.ts

@@ -0,0 +1,99 @@
+/**
+ * InstarWorktreeManager — Layer 1 of the Agent Worktree Convention.
+ *
+ * Creates git worktrees of the shared instar repository inside the agent's
+ * own home directory (`~/.instar/agents/<agent>/.worktrees/`). This is the
+ * only location the macOS sandbox cannot revoke mid-session.
+ *
+ * Spec: docs/specs/AGENT-WORKTREE-CONVENTION-SPEC.md (status: approved).
+ *
+ * The CLI subcommand `instar worktree create <branch>` is a thin shim over
+ * this manager. All validation, resolution, and audit-trail logic lives
+ * here so it can be unit-tested without spawning a CLI process.
+ */
+/** Default allowlist of remote-origin URLs for the canonical instar repo.
+ *  Operators can extend via `worktree.repoUrlAllowlist` in `.instar/config.json`. */
+export declare const DEFAULT_INSTAR_REPO_URL_ALLOWLIST: ReadonlyArray<string>;
+export interface ResolveAgentHomeOptions {
+    /** Override `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Override `process.cwd()`. */
+    cwd?: string;
+    /** Override the instar home root (defaults to `~/.instar`). */
+    instarHome?: string;
+    /** Override registry lookup (for tests). Returns the set of registered agent names. */
+    registryLookup?: () => Set<string>;
+}
+export interface ResolvedAgentHome {
+    /** Absolute, real (symlink-resolved) path to the agent home directory. */
+    agentHome: string;
+    /** Agent name extracted from the trailing path segment. */
+    agentName: string;
+}
+export interface ResolveInstarRepoOptions {
+    env?: NodeJS.ProcessEnv;
+    /** Path to user config (defaults to `~/.instar/config.json`). */
+    configPath?: string;
+    /** Override the URL allowlist entirely (skipping the default + config merge). */
+    urlAllowlist?: ReadonlyArray<string>;
+    /** Override the fallback chain order (for tests). */
+    fallbackChain?: ReadonlyArray<string>;
+    /** Override the home directory used for default fallbacks. */
+    homeDir?: string;
+}
+export interface ResolvedInstarRepo {
+    /** Absolute, real path to a validated instar repo. */
+    repoPath: string;
+    /** Allowlisted remote.origin.url for the resolved repo. */
+    remoteUrl: string;
+}
+export interface CreateWorktreeOptions {
+    /** Branch name to check out / create. */
+    branch: string;
+    /** Optional override for the worktree directory slug. Defaults to branch with `/` → `-`. */
+    slug?: string;
+    /** Default true (current bash-helper behavior). Pass false to skip the node_modules symlink. */
+    shareNodeModules?: boolean;
+    /** Override agent-home resolution (mainly for tests). */
+    resolveAgentHomeOpts?: ResolveAgentHomeOptions;
+    /** Override instar-repo resolution (mainly for tests). */
+    resolveInstarRepoOpts?: ResolveInstarRepoOptions;
+    /** Override the base for new branches. If omitted, resolves to origin/HEAD. */
+    baseBranch?: string;
+    /** Audit-mirror state directory (defaults to `<agent_home>/.instar`). */
+    stateDir?: string;
+}
+export interface CreateWorktreeResult {
+    worktreePath: string;
+    branch: string;
+    slug: string;
+    agentHome: string;
+    agentName: string;
+    instarRepo: string;
+    instarRepoSha: string;
+    shareNodeModules: boolean;
+    /** True if a new branch was created; false if an existing branch was checked out. */
+    createdBranch: boolean;
+}
+export declare function resolveAgentHome(opts?: ResolveAgentHomeOptions): ResolvedAgentHome;
+export declare function resolveInstarRepo(opts?: ResolveInstarRepoOptions): ResolvedInstarRepo;
+export declare function defaultSlugFor(branch: string): string;
+export declare function validateSlug(slug: string, existingSlugsLower: ReadonlySet<string>): void;
+export declare function validateBranchName(branch: string, repoPath: string): void;
+export declare function createWorktree(opts: CreateWorktreeOptions): Promise<CreateWorktreeResult>;
+export interface LedgerEntry {
+    ts: string;
+    agent: string;
+    branch: string;
+    slug: string;
+    worktreePath: string;
+    instarRepo: string;
+    instarRepoSha: string;
+    shareNodeModules: boolean;
+}
+export declare function appendLedgerEntry(worktreesDir: string, stateDir: string, entry: LedgerEntry): void;
+/** Stable hash for a worktree path — used by the (deferred) Layer 4 detector
+ *  as the AttentionQueue dedupe key. Exposed here so detector code and tests
+ *  cannot drift. */
+export declare function worktreeDedupeKey(worktreePath: string): string;
+//# sourceMappingURL=InstarWorktreeManager.d.ts.map

package/dist/core/InstarWorktreeManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InstarWorktreeManager.d.ts","sourceRoot":"","sources":["../../src/core/InstarWorktreeManager.ts"],"names":[],"mappings":"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"}