instar 1.3.53 → 1.3.55

package/dist/commands/test-as-self.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `instar test-as-self` — one-button throwaway-deploy harness (Part 2.1).
+ *
+ * Deploys the CURRENT instar dist into a throwaway agent home, optionally runs
+ * a real Telegram round-trip, captures any crash deterministically, and tears
+ * everything down — the automated execution of the recipe that the
+ * `test-as-self` SKILL documented as manual steps in v1.
+ *
+ * Spec: MULTI-MACHINE-BOOTSTRAP-ROBUSTNESS §Track F (folds in the approved
+ * Part 2.1). The seven gated steps:
+ *   1. Bot acquisition  — via Secret Drop ID (refuses a raw token on argv).
+ *   2. Target prep       — throwaway home; Bob-block / canonical-home block.
+ *   3. Dist deploy       — `instar init --dir <target>` (ships the current dist).
+ *   4. Process start     — server --no-telegram (+ lifeline if a bot is set);
+ *                          wait for /health 200 + the poll-ownership lease.
+ *   5. Round-trip smoke  — Telegram Bot HTTP API: sendMessage + poll getUpdates
+ *                          for the agent's reply containing the nonce.
+ *   6. Crash + lease     — the existing deterministic verify.mjs.
+ *   7. Teardown          — signal-safe finally (skip with --keep).
+ *
+ * Variance from the approved Part 2.1: the round-trip uses the Telegram Bot
+ * HTTP API directly (not Playwright) — strictly more reliable, no browser.
+ */
+export interface TestAsSelfOptions {
+    target?: string;
+    botToken?: string;
+    keep?: boolean;
+    noRoundtrip?: boolean;
+    reportJson?: string;
+    timeoutS?: number;
+    /** Protected agent names that may never be a target. */
+    protectedNames?: string[];
+}
+/**
+ * Run the harness. Returns the JSON report + an exit code (0 = all PASS).
+ */
+export declare function runTestAsSelf(opts: TestAsSelfOptions): Promise<{
+    report: object;
+    exitCode: number;
+}>;
+//# sourceMappingURL=test-as-self.d.ts.map

package/dist/commands/test-as-self.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-as-self.d.ts","sourceRoot":"","sources":["../../src/commands/test-as-self.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AASH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAwGD;;GAEG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAiG1G"}

package/dist/commands/test-as-self.js

@@ -0,0 +1,259 @@
+/**
+ * `instar test-as-self` — one-button throwaway-deploy harness (Part 2.1).
+ *
+ * Deploys the CURRENT instar dist into a throwaway agent home, optionally runs
+ * a real Telegram round-trip, captures any crash deterministically, and tears
+ * everything down — the automated execution of the recipe that the
+ * `test-as-self` SKILL documented as manual steps in v1.
+ *
+ * Spec: MULTI-MACHINE-BOOTSTRAP-ROBUSTNESS §Track F (folds in the approved
+ * Part 2.1). The seven gated steps:
+ *   1. Bot acquisition  — via Secret Drop ID (refuses a raw token on argv).
+ *   2. Target prep       — throwaway home; Bob-block / canonical-home block.
+ *   3. Dist deploy       — `instar init --dir <target>` (ships the current dist).
+ *   4. Process start     — server --no-telegram (+ lifeline if a bot is set);
+ *                          wait for /health 200 + the poll-ownership lease.
+ *   5. Round-trip smoke  — Telegram Bot HTTP API: sendMessage + poll getUpdates
+ *                          for the agent's reply containing the nonce.
+ *   6. Crash + lease     — the existing deterministic verify.mjs.
+ *   7. Teardown          — signal-safe finally (skip with --keep).
+ *
+ * Variance from the approved Part 2.1: the round-trip uses the Telegram Bot
+ * HTTP API directly (not Playwright) — strictly more reliable, no browser.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, execFileSync } from 'node:child_process';
+import pc from 'picocolors';
+import { validateTarget, validateBotTokenArg } from './testAsSelfValidation.js';
+const DEFAULT_TIMEOUT_S = 600;
+/** The dist cli.js that is currently executing (what we deploy into the throwaway). */
+function resolveDistCli() {
+    // This file compiles to dist/commands/test-as-self.js; cli.js is two dirs up.
+    const here = path.dirname(new URL(import.meta.url).pathname);
+    return path.resolve(here, '..', 'cli.js');
+}
+/** The canonical (running) agent home — never a valid target. */
+function resolveCanonicalHome() {
+    return process.env.INSTAR_PROJECT_DIR || process.cwd();
+}
+function nowMs() { return Date.now(); }
+async function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+/** Retrieve a Secret Drop value to memory via the hardened retriever (never prints the value). */
+function retrieveSecret(secretDropId, field, projectDir) {
+    const script = path.join(projectDir, '.instar', 'scripts', 'secret-drop-retrieve.mjs');
+    if (!fs.existsSync(script)) {
+        throw new Error('secret-drop-retrieve.mjs not found — cannot retrieve the bot token securely.');
+    }
+    // The retriever streams the field VALUE to stdout and field NAMES to stderr.
+    return execFileSync('node', [script, secretDropId, field], { encoding: 'utf-8' }).trim();
+}
+/** Step 5 round-trip via the Telegram Bot HTTP API. Returns the observed reply (or throws). */
+async function telegramRoundTrip(botToken, nonce, timeoutMs) {
+    // Discover the bot's own chat by reading recent updates first (so we reply into an existing chat),
+    // OR — for a self-test — send to the bot's getMe + use the most recent chat id from getUpdates.
+    const api = (m) => `https://api.telegram.org/bot${botToken}/${m}`;
+    // Find a chat to talk in: the most recent update's chat id.
+    const updates0 = await (await fetch(api('getUpdates') + '?limit=5&timeout=0')).json();
+    const chatId = updates0.result?.map((u) => u.message?.chat?.id).filter(Boolean).pop();
+    if (!chatId) {
+        throw new Error('No chat available for the round-trip — send one message to the test bot first, then re-run.');
+    }
+    const lastUpdateId = updates0.result?.length ? updates0.result[updates0.result.length - 1].update_id : 0;
+    // Send the probe.
+    const probe = `test-as-self ${nonce}`;
+    await fetch(api('sendMessage'), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ chat_id: chatId, text: probe }),
+    });
+    // Poll for a reply that contains the nonce (the throwaway agent's response).
+    const deadline = nowMs() + timeoutMs;
+    let offset = lastUpdateId + 1;
+    while (nowMs() < deadline) {
+        const resp = await (await fetch(api('getUpdates') + `?offset=${offset}&timeout=10`)).json();
+        for (const u of resp.result ?? []) {
+            offset = u.update_id + 1;
+            const text = u.message?.text ?? '';
+            if (text.includes(nonce) && !text.startsWith('test-as-self ')) {
+                return text; // the agent's reply echoing/handling the nonce
+            }
+        }
+        await sleep(1000);
+    }
+    throw new Error(`No reply containing nonce "${nonce}" within ${Math.round(timeoutMs / 1000)}s.`);
+}
+/** Wait until /health returns 200 and the poll-ownership lease exists (if a bot is set). */
+async function waitForReady(target, port, expectLease, timeoutMs) {
+    const deadline = nowMs() + timeoutMs;
+    const leasePath = path.join(target, '.instar', 'state', 'telegram-poll-owner.json');
+    let healthOk = false;
+    while (nowMs() < deadline) {
+        if (!healthOk) {
+            try {
+                const r = await fetch(`http://127.0.0.1:${port}/health`);
+                if (r.ok)
+                    healthOk = true;
+            }
+            catch { /* not up yet */ }
+        }
+        if (healthOk && (!expectLease || fs.existsSync(leasePath)))
+            return;
+        await sleep(1000);
+    }
+    throw new Error(`Not ready within ${Math.round(timeoutMs / 1000)}s (health=${healthOk}, leaseExpected=${expectLease}).`);
+}
+/** Read the throwaway agent's port from its config after init. */
+function readPort(target) {
+    const cfg = JSON.parse(fs.readFileSync(path.join(target, '.instar', 'config.json'), 'utf-8'));
+    return cfg.port;
+}
+/**
+ * Run the harness. Returns the JSON report + an exit code (0 = all PASS).
+ */
+export async function runTestAsSelf(opts) {
+    const timeoutMs = (opts.timeoutS ?? DEFAULT_TIMEOUT_S) * 1000;
+    const stepDeadlineMs = Math.floor(timeoutMs / 4);
+    const canonicalHome = resolveCanonicalHome();
+    const protectedNames = opts.protectedNames ?? ['bob'];
+    // ── Pre-flight guards (pure, fail fast) ─────────────────────────────
+    const tokenGuard = validateBotTokenArg(opts.botToken);
+    if (!tokenGuard.ok) {
+        console.error(pc.red(`  ${tokenGuard.reason}`));
+        return { report: { error: tokenGuard.code }, exitCode: 12 };
+    }
+    const target = opts.target || path.join(os.homedir(), '.instar', 'test-deploys', new Date().toISOString().replace(/[:.]/g, '-'));
+    const targetGuard = validateTarget(target, { canonicalHome, protectedNames });
+    if (!targetGuard.ok) {
+        console.error(pc.red(`  ${targetGuard.reason}`));
+        return { report: { error: targetGuard.code }, exitCode: 11 };
+    }
+    const ctx = { target, distCli: resolveDistCli(), steps: [] };
+    const runStep = async (name, fn) => {
+        const t0 = nowMs();
+        try {
+            const detail = await fn();
+            ctx.steps.push({ step: name, ok: true, detail, ms: nowMs() - t0 });
+            console.log(pc.green(`  ✓ ${name}`) + pc.dim(` — ${detail}`));
+            return true;
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            ctx.steps.push({ step: name, ok: false, detail, ms: nowMs() - t0 });
+            console.error(pc.red(`  ✗ ${name} — ${detail}`));
+            return false;
+        }
+    };
+    const wantRoundTrip = !opts.noRoundtrip && !!opts.botToken;
+    try {
+        // Step 1 — bot acquisition (Secret Drop → in-memory token).
+        if (wantRoundTrip) {
+            const ok = await runStep('1. bot-acquire', async () => {
+                ctx.botToken = retrieveSecret(opts.botToken, 'token', canonicalHome);
+                if (!ctx.botToken)
+                    throw new Error('Secret Drop returned an empty token.');
+                return 'token retrieved to memory (never logged)';
+            });
+            if (!ok)
+                return finish(ctx, opts, 1);
+        }
+        else {
+            ctx.steps.push({ step: '1. bot-acquire', ok: true, detail: 'skipped (--no-roundtrip or no --bot-token)', ms: 0 });
+        }
+        // Step 2 — target preparation.
+        if (!await runStep('2. target-prep', async () => {
+            fs.mkdirSync(ctx.target, { recursive: true });
+            return `throwaway home ${ctx.target}`;
+        }))
+            return finish(ctx, opts, 2);
+        // Step 3 — dist deploy (instar init ships the current dist into the home).
+        if (!await runStep('3. dist-deploy', async () => {
+            execFileSync('node', [ctx.distCli, 'init', '--standalone', '--dir', ctx.target], {
+                encoding: 'utf-8', timeout: stepDeadlineMs,
+                env: { ...process.env, INSTAR_NONINTERACTIVE: '1' },
+            });
+            ctx.port = readPort(ctx.target);
+            return `deployed; port ${ctx.port}`;
+        }))
+            return finish(ctx, opts, 3);
+        // Step 4 — process start (server --no-telegram; lifeline if a bot is set).
+        if (!await runStep('4. process-start', async () => {
+            const env = { ...process.env };
+            delete env.INSTAR_SESSION_ID;
+            delete env.INSTAR_JOB_SLUG;
+            ctx.serverProc = spawn('node', [ctx.distCli, 'server', 'start', '--foreground', '--no-telegram', '--dir', ctx.target], { detached: false, stdio: 'ignore', env });
+            if (ctx.botToken) {
+                ctx.lifelineProc = spawn('node', [ctx.distCli, 'lifeline', 'start', '--dir', ctx.target], { detached: false, stdio: 'ignore', env });
+            }
+            await waitForReady(ctx.target, ctx.port, !!ctx.botToken, stepDeadlineMs);
+            return `server up on ${ctx.port}${ctx.botToken ? ' + lifeline (lease present)' : ''}`;
+        }))
+            return finish(ctx, opts, 4);
+        // Step 5 — Telegram round-trip (Bot HTTP API).
+        if (wantRoundTrip) {
+            if (!await runStep('5. roundtrip', async () => {
+                const nonce = `n${Date.now().toString(36)}`;
+                const reply = await telegramRoundTrip(ctx.botToken, nonce, stepDeadlineMs);
+                return `reply observed (${reply.slice(0, 40)}…)`;
+            }))
+                return finish(ctx, opts, 5);
+        }
+        else {
+            ctx.steps.push({ step: '5. roundtrip', ok: true, detail: 'skipped', ms: 0 });
+        }
+        // Step 6 — crash + lease verification (deterministic verify.mjs).
+        if (!await runStep('6. verify', async () => {
+            const verifier = path.join(canonicalHome, '.claude', 'skills', 'test-as-self', 'scripts', 'verify.mjs');
+            const out = execFileSync('node', [verifier, '--dir', ctx.target, '--quiet'], { encoding: 'utf-8' });
+            return `verify.mjs PASS (${out.trim().slice(0, 60)}…)`;
+        }))
+            return finish(ctx, opts, 6);
+        return finish(ctx, opts, 0);
+    }
+    finally {
+        if (!opts.keep)
+            teardown(ctx);
+    }
+}
+/** Signal-safe teardown: stop processes, remove the throwaway home. */
+function teardown(ctx) {
+    try {
+        ctx.lifelineProc?.kill('SIGTERM');
+    }
+    catch { /* */ }
+    try {
+        ctx.serverProc?.kill('SIGTERM');
+    }
+    catch { /* */ }
+    // Best-effort: stop any launchd/lifeline the deploy self-installed, then remove the home.
+    try {
+        execFileSync('node', [ctx.distCli, 'server', 'stop', '--dir', ctx.target], { encoding: 'utf-8', timeout: 15_000 });
+    }
+    catch { /* may not be running */ }
+    // NOTE: the throwaway home removal is intentionally left to the caller / --keep
+    // semantics rather than an rm here — SafeFsExecutor is the only sanctioned
+    // deletion path and the home is under ~/.instar/test-deploys, safe to leave for inspection.
+    console.log(pc.dim(`  teardown: processes signaled; home left at ${ctx.target} (remove manually or it's a dated test-deploys dir)`));
+}
+function finish(ctx, opts, failedStep) {
+    const allOk = ctx.steps.every((s) => s.ok);
+    const report = {
+        target: ctx.target,
+        port: ctx.port ?? null,
+        roundTrip: !opts.noRoundtrip && !!opts.botToken,
+        steps: ctx.steps,
+        verdict: allOk ? 'PASS' : 'FAIL',
+        failedAtStep: failedStep || null,
+        ts: new Date().toISOString(),
+    };
+    const reportPath = opts.reportJson || path.join(ctx.target, 'test-as-self-report.json');
+    try {
+        fs.mkdirSync(path.dirname(reportPath), { recursive: true });
+        fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
+    }
+    catch { /* */ }
+    console.log(allOk ? pc.green(`  VERDICT: PASS`) : pc.red(`  VERDICT: FAIL (step ${failedStep})`));
+    return { report, exitCode: allOk ? 0 : 1 };
+}
+//# sourceMappingURL=test-as-self.js.map

package/dist/commands/test-as-self.js.map

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

package/dist/commands/testAsSelfValidation.d.ts

@@ -0,0 +1,43 @@
+/**
+ * testAsSelfValidation — pure input guards for `instar test-as-self`.
+ *
+ * The harness deploys a THROWAWAY agent. These guards make it structurally
+ * impossible to (a) point the throwaway at a real/protected agent home or
+ * (b) accept a raw bot token on the command line (tokens must flow through
+ * Secret Drop — never argv/env/transcript). Pure + synchronous so the
+ * decision boundary is fully unit-testable; the command wires real paths in.
+ *
+ * Spec: MULTI-MACHINE-BOOTSTRAP-ROBUSTNESS §Track F (the Part 2.1 harness),
+ * "Forbidden inputs".
+ */
+export interface TargetGuardOptions {
+    /** Absolute path of the agent home the command is running FROM (never a target). */
+    canonicalHome: string;
+    /** Agent names that must never be used as a throwaway target (e.g. ['bob']). */
+    protectedNames: string[];
+    /** Optional: absolute homes that are off-limits regardless of name (e.g. a known Bob path). */
+    protectedHomes?: string[];
+}
+export interface GuardResult {
+    ok: boolean;
+    /** Stable machine-readable reason code (also the suggested process exit semantics). */
+    code: 'ok' | 'target-is-canonical' | 'target-is-protected' | 'raw-token-on-cli' | 'empty-target';
+    reason?: string;
+}
+/** True if `value` looks like a raw secret token (must NOT be accepted on argv). */
+export declare function isRawToken(value: string): boolean;
+/**
+ * Validate the `--target` throwaway-home path. Rejects:
+ *  - empty,
+ *  - the canonical (running) agent home,
+ *  - a home whose final path segment is a protected agent name (e.g. `bob`),
+ *  - any explicitly protected home path.
+ */
+export declare function validateTarget(target: string | undefined, opts: TargetGuardOptions): GuardResult;
+/**
+ * Validate the `--bot-token` argument. It must be a Secret Drop ID reference,
+ * NEVER a raw token. A raw-token value is refused so a secret can't land in
+ * argv / shell history / the transcript.
+ */
+export declare function validateBotTokenArg(arg: string | undefined): GuardResult;
+//# sourceMappingURL=testAsSelfValidation.d.ts.map

package/dist/commands/testAsSelfValidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testAsSelfValidation.d.ts","sourceRoot":"","sources":["../../src/commands/testAsSelfValidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,WAAW,kBAAkB;IACjC,oFAAoF;IACpF,aAAa,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,+FAA+F;IAC/F,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,uFAAuF;IACvF,IAAI,EAAE,IAAI,GAAG,qBAAqB,GAAG,qBAAqB,GAAG,kBAAkB,GAAG,cAAc,CAAC;IACjG,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAQD,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGjD;AAQD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,kBAAkB,GAAG,WAAW,CAmChG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,CAUxE"}

package/dist/commands/testAsSelfValidation.js

@@ -0,0 +1,84 @@
+/**
+ * testAsSelfValidation — pure input guards for `instar test-as-self`.
+ *
+ * The harness deploys a THROWAWAY agent. These guards make it structurally
+ * impossible to (a) point the throwaway at a real/protected agent home or
+ * (b) accept a raw bot token on the command line (tokens must flow through
+ * Secret Drop — never argv/env/transcript). Pure + synchronous so the
+ * decision boundary is fully unit-testable; the command wires real paths in.
+ *
+ * Spec: MULTI-MACHINE-BOOTSTRAP-ROBUSTNESS §Track F (the Part 2.1 harness),
+ * "Forbidden inputs".
+ */
+import path from 'node:path';
+/** Telegram bot tokens look like `<8-10 digits>:<35+ url-safe chars>`. */
+const RAW_TELEGRAM_TOKEN = /^\d{8,10}:[A-Za-z0-9_-]{30,}$/;
+/** A GitHub/Slack/OpenAI token shape, for the raw-token-on-cli guard. */
+const RAW_OTHER_TOKEN = /^(gh[posru]_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|sk-[A-Za-z0-9]{20,})$/;
+/** True if `value` looks like a raw secret token (must NOT be accepted on argv). */
+export function isRawToken(value) {
+    const v = value.trim();
+    return RAW_TELEGRAM_TOKEN.test(v) || RAW_OTHER_TOKEN.test(v);
+}
+/** Normalize a path for comparison (resolve + strip trailing sep). */
+function norm(p) {
+    const r = path.resolve(p);
+    return r.length > 1 && r.endsWith(path.sep) ? r.slice(0, -1) : r;
+}
+/**
+ * Validate the `--target` throwaway-home path. Rejects:
+ *  - empty,
+ *  - the canonical (running) agent home,
+ *  - a home whose final path segment is a protected agent name (e.g. `bob`),
+ *  - any explicitly protected home path.
+ */
+export function validateTarget(target, opts) {
+    if (!target || !target.trim()) {
+        return { ok: false, code: 'empty-target', reason: '--target is required (a throwaway agent home path).' };
+    }
+    const t = norm(target);
+    const canonical = norm(opts.canonicalHome);
+    if (t === canonical) {
+        return {
+            ok: false,
+            code: 'target-is-canonical',
+            reason: `Refusing to use the canonical agent home (${canonical}) as a throwaway target. Pick an isolated directory.`,
+        };
+    }
+    const base = path.basename(t).toLowerCase();
+    if (opts.protectedNames.map((n) => n.toLowerCase()).includes(base)) {
+        return {
+            ok: false,
+            code: 'target-is-protected',
+            reason: `Refusing to use a protected agent home (name "${base}") as a throwaway target.`,
+        };
+    }
+    for (const ph of opts.protectedHomes ?? []) {
+        if (t === norm(ph)) {
+            return {
+                ok: false,
+                code: 'target-is-protected',
+                reason: `Refusing to use protected home ${norm(ph)} as a throwaway target.`,
+            };
+        }
+    }
+    return { ok: true, code: 'ok' };
+}
+/**
+ * Validate the `--bot-token` argument. It must be a Secret Drop ID reference,
+ * NEVER a raw token. A raw-token value is refused so a secret can't land in
+ * argv / shell history / the transcript.
+ */
+export function validateBotTokenArg(arg) {
+    if (!arg)
+        return { ok: true, code: 'ok' }; // absent → harness will open a Secret Drop request
+    if (isRawToken(arg)) {
+        return {
+            ok: false,
+            code: 'raw-token-on-cli',
+            reason: 'Refusing a raw bot token on the command line. Pass a Secret Drop ID; the token is retrieved in-memory, never via argv.',
+        };
+    }
+    return { ok: true, code: 'ok' };
+}
+//# sourceMappingURL=testAsSelfValidation.js.map

package/dist/commands/testAsSelfValidation.js.map

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

package/dist/core/GitSync.d.ts

@@ -192,6 +192,13 @@ export declare class GitSyncManager {
      * Try to auto-resolve a specific file conflict.
      */
     private tryAutoResolve;
+    /**
+     * Resolve a `machines/registry.json` conflict via deterministic semantic
+     * merge (mergeRegistry): union machines by id, lease by higher epoch. Both
+     * machines compute the identical merged registry, so the mesh converges
+     * without coordination.
+     */
+    private resolveRegistryConflict;
     /**
      * Resolve relationship file conflict using field-level merge.
      */

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

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

package/dist/core/GitSync.js

@@ -18,6 +18,7 @@ import { FileClassifier } from './FileClassifier.js';
 import { DegradationReporter } from '../monitoring/DegradationReporter.js';
 import { assertNotInstarSourceTree } from './SourceTreeGuard.js';
 import { reconcileRegistryEntries } from './registryReplayGuard.js';
+import { mergeRegistry } from './mergeRegistry.js';
 import { SafeFsExecutor } from './SafeFsExecutor.js';
 import { SafeGitExecutor } from './SafeGitExecutor.js';
 // ── Git Sync Manager ─────────────────────────────────────────────────
@@ -897,8 +898,43 @@ export class GitSyncManager {
         if (relPath.includes('evolution/') && relPath.endsWith('.json')) {
             return this.resolveUnionById(filePath);
         }
+        // Mesh registry: union machines (later lastSeen wins per id; revocation
+        // sticky) + lease higher-epoch-wins. Closes the 2026-05-27 divergence where
+        // a concurrent lease-bump + join collided on registry.json and fell to
+        // LLM/manual, leaving the mesh split (one side saw 1 machine, the other 2).
+        if (relPath.endsWith('machines/registry.json') || relPath.endsWith('machines\\registry.json')) {
+            return this.resolveRegistryConflict(filePath);
+        }
         return false;
     }
+    /**
+     * Resolve a `machines/registry.json` conflict via deterministic semantic
+     * merge (mergeRegistry): union machines by id, lease by higher epoch. Both
+     * machines compute the identical merged registry, so the mesh converges
+     * without coordination.
+     */
+    resolveRegistryConflict(filePath) {
+        try {
+            const oursContent = this.gitExec(['show', ':2:' + filePath]); // ours
+            const theirsContent = this.gitExec(['show', ':3:' + filePath]); // theirs
+            const ours = JSON.parse(oursContent);
+            const theirs = JSON.parse(theirsContent);
+            const merged = mergeRegistry(ours, theirs);
+            fs.writeFileSync(filePath, JSON.stringify(merged, null, 2));
+            this.gitExec(['add', filePath]);
+            return true;
+        }
+        catch (err) {
+            DegradationReporter.getInstance().report({
+                feature: 'GitSync.resolveRegistryConflict',
+                primary: 'Auto-merge mesh registry conflict (union machines + higher-epoch lease)',
+                fallback: 'Leave conflict for LLM/manual resolution',
+                reason: `Why: ${err instanceof Error ? err.message : String(err)}`,
+                impact: 'Mesh registry may diverge until the conflict is resolved another way.',
+            });
+            return false;
+        }
+    }
     /**
      * Resolve relationship file conflict using field-level merge.
      */