instar 0.28.112 → 0.28.114

package/dist/core/FeatureRegistry.d.ts

@@ -22,7 +22,7 @@ export interface EnableAction {
 }
 export interface DataImplication {
     dataType: string;
-    destination: 'local' | 'anthropic-api' | 'cloudflare' | 'custom';
+    destination: 'local' | 'anthropic-cli' | 'cloudflare' | 'custom';
     retention?: string;
     description: string;
 }

package/dist/core/IdentityRenderer.d.ts

@@ -0,0 +1,125 @@
+/**
+ * IdentityRenderer — render framework-specific identity files from the
+ * canonical AGENT.md source.
+ *
+ * Provider-portability v1.0.0: AGENT.md is the single source of truth
+ * for an agent's identity (who I am, what I'm working on, who I'm
+ * working with). Frameworks have their own conventions for the file
+ * they auto-load at session start:
+ *
+ *   - Claude Code → CLAUDE.md at the project root
+ *   - OpenAI Codex → AGENTS.md at the project root
+ *   - Gemini CLI → GEMINI.md at the project root
+ *   - (extend the renderer when new frameworks land)
+ *
+ * The shadow files are deterministically rendered from AGENT.md. They
+ * are NOT the source of truth and should NOT be hand-edited — edits get
+ * overwritten on the next render. Each shadow file ships with a header
+ * banner saying so.
+ *
+ * This file does not write anything until you call render(); it's safe
+ * to import without side effects.
+ */
+/**
+ * Known framework conventions. Maps a framework id to the shadow filename
+ * it expects at the project root.
+ *
+ * Extending: add a new entry here. The renderer picks it up automatically.
+ */
+export declare const FRAMEWORK_SHADOW_FILES: Record<string, string>;
+export interface RenderIdentityOptions {
+    /** Project root where shadow files are written. */
+    projectDir: string;
+    /**
+     * Frameworks to render shadows for. Defaults to every entry in
+     * FRAMEWORK_SHADOW_FILES (i.e. all known frameworks). Pass a subset
+     * for installs that only use one framework — saves a file write.
+     */
+    frameworks?: ReadonlyArray<string>;
+    /**
+     * Path to the canonical source. Defaults to `<projectDir>/.instar/AGENT.md`.
+     * The renderer also accepts `<projectDir>/AGENT.md` (root-level) as a
+     * fallback for installs that keep identity at the project root.
+     */
+    sourcePath?: string;
+    /**
+     * When true, append a framework-aware Telegram-relay reminder section to
+     * the rendered shadow. Codex CLI has no SessionStart-hook analog to the
+     * Claude Code shell hook that injects "MANDATORY: relay back" — so the
+     * reminder has to live in AGENTS.md to survive past the first message
+     * within a long-running session. Defaults to false; callers that know
+     * Telegram is configured should pass true. Detection logic stays in the
+     * caller — the renderer just emits the markdown.
+     */
+    appendTelegramRelayBlock?: boolean;
+}
+export interface RenderIdentityResult {
+    /** Path of the source file actually read. */
+    source: string;
+    /** Paths of shadow files written. */
+    shadowsWritten: ReadonlyArray<string>;
+    /** Frameworks skipped because their shadow path was missing in the map. */
+    skipped: ReadonlyArray<string>;
+}
+export declare class IdentityRendererError extends Error {
+    constructor(message: string);
+}
+/**
+ * Render framework-specific shadow files from the canonical AGENT.md.
+ *
+ * Workflow:
+ *   1. Locate source (preferred: `.instar/AGENT.md`; fallback: root `AGENT.md`).
+ *   2. Read source content.
+ *   3. For each requested framework, write `<projectDir>/<shadowFilename>`
+ *      with the source content prefixed by the auto-generation banner.
+ *
+ * Throws IdentityRendererError if source can't be located or read.
+ */
+export declare function renderIdentity(options: RenderIdentityOptions): RenderIdentityResult;
+/**
+ * Detect framework from an existing project layout. Used for legacy
+ * installs that have CLAUDE.md but no AGENT.md — we can infer which
+ * framework was configured and seed AGENT.md from the shadow content.
+ *
+ * Returns null when no framework-specific file is found.
+ */
+export declare function detectFrameworkFromShadowFiles(projectDir: string): string | null;
+/**
+ * Ensure the shadow file a framework expects exists at the project root,
+ * bootstrapping the canonical AGENT.md from any legacy shadow first if
+ * needed.
+ *
+ * Lifecycle:
+ *   - If `<projectDir>/<framework-shadow>` already exists, no-op.
+ *   - If `.instar/AGENT.md` exists, render the requested framework's
+ *     shadow from it.
+ *   - If neither exists but a different shadow does (e.g., legacy
+ *     CLAUDE.md without AGENT.md), bootstrap AGENT.md from that shadow,
+ *     then render the requested shadow.
+ *   - If nothing exists, no-op — the project has no identity content
+ *     to seed from.
+ *
+ * Returns the path of the written shadow file, or null when the operation
+ * was a no-op.
+ *
+ * Idempotent. Safe to call before every spawn — checks file existence
+ * first and only writes when there's something useful to do.
+ */
+export declare function ensureFrameworkIdentityFile(projectDir: string, framework: string, options?: {
+    stateDir?: string;
+    appendTelegramRelayBlock?: boolean;
+}): string | null;
+/**
+ * Bootstrap AGENT.md from a legacy CLAUDE.md (or other shadow file).
+ *
+ * Used during migration when a project has a CLAUDE.md but no AGENT.md.
+ * Reads the shadow, strips the auto-generation banner if present, and
+ * writes the canonical AGENT.md.
+ *
+ * Returns the absolute path of the written AGENT.md, or null if no
+ * shadow file could be found.
+ */
+export declare function bootstrapAgentMdFromShadow(projectDir: string, options?: {
+    stateDir?: string;
+}): string | null;
+//# sourceMappingURL=IdentityRenderer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IdentityRenderer.d.ts","sourceRoot":"","sources":["../../src/core/IdentityRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AASH;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAIzD,CAAC;AAwBF,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACnC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;OAQG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,MAAM,WAAW,oBAAoB;IACnC,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,2EAA2E;IAC3E,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAChC;AAED,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,oBAAoB,CAiCnF;AA2DD;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKhF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,wBAAwB,CAAC,EAAE,OAAO,CAAA;CAAO,GACtE,MAAM,GAAG,IAAI,CA4Cf;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,MAAM,GAAG,IAAI,CAkBf"}

package/dist/core/IdentityRenderer.js

@@ -0,0 +1,264 @@
+/**
+ * IdentityRenderer — render framework-specific identity files from the
+ * canonical AGENT.md source.
+ *
+ * Provider-portability v1.0.0: AGENT.md is the single source of truth
+ * for an agent's identity (who I am, what I'm working on, who I'm
+ * working with). Frameworks have their own conventions for the file
+ * they auto-load at session start:
+ *
+ *   - Claude Code → CLAUDE.md at the project root
+ *   - OpenAI Codex → AGENTS.md at the project root
+ *   - Gemini CLI → GEMINI.md at the project root
+ *   - (extend the renderer when new frameworks land)
+ *
+ * The shadow files are deterministically rendered from AGENT.md. They
+ * are NOT the source of truth and should NOT be hand-edited — edits get
+ * overwritten on the next render. Each shadow file ships with a header
+ * banner saying so.
+ *
+ * This file does not write anything until you call render(); it's safe
+ * to import without side effects.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+// ---------------------------------------------------------------------------
+// Framework conventions
+// ---------------------------------------------------------------------------
+/**
+ * Known framework conventions. Maps a framework id to the shadow filename
+ * it expects at the project root.
+ *
+ * Extending: add a new entry here. The renderer picks it up automatically.
+ */
+export const FRAMEWORK_SHADOW_FILES = {
+    'claude-code': 'CLAUDE.md',
+    'codex-cli': 'AGENTS.md',
+    'gemini-cli': 'GEMINI.md',
+};
+// ---------------------------------------------------------------------------
+// Banner that prefixes every rendered shadow
+// ---------------------------------------------------------------------------
+function bannerFor(framework, sourceRelPath) {
+    return [
+        `<!--`,
+        `  AUTO-GENERATED by Instar's IdentityRenderer.`,
+        `  Source of truth: ${sourceRelPath}`,
+        `  Framework: ${framework}`,
+        ``,
+        `  Do NOT hand-edit this file. Edits will be overwritten on the next`,
+        `  identity render. Edit the source file instead.`,
+        `-->`,
+        ``,
+    ].join('\n');
+}
+export class IdentityRendererError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IdentityRendererError';
+    }
+}
+/**
+ * Render framework-specific shadow files from the canonical AGENT.md.
+ *
+ * Workflow:
+ *   1. Locate source (preferred: `.instar/AGENT.md`; fallback: root `AGENT.md`).
+ *   2. Read source content.
+ *   3. For each requested framework, write `<projectDir>/<shadowFilename>`
+ *      with the source content prefixed by the auto-generation banner.
+ *
+ * Throws IdentityRendererError if source can't be located or read.
+ */
+export function renderIdentity(options) {
+    const source = resolveSource(options.projectDir, options.sourcePath);
+    if (source === null) {
+        throw new IdentityRendererError(`No canonical identity source found. Expected `
+            + `${path.join(options.projectDir, '.instar', 'AGENT.md')} or `
+            + `${path.join(options.projectDir, 'AGENT.md')}`);
+    }
+    const content = fs.readFileSync(source, 'utf-8');
+    const sourceRel = path.relative(options.projectDir, source);
+    const requestedFrameworks = options.frameworks ?? Object.keys(FRAMEWORK_SHADOW_FILES);
+    const shadowsWritten = [];
+    const skipped = [];
+    for (const framework of requestedFrameworks) {
+        const filename = FRAMEWORK_SHADOW_FILES[framework];
+        if (!filename) {
+            skipped.push(framework);
+            continue;
+        }
+        const target = path.join(options.projectDir, filename);
+        const banner = bannerFor(framework, sourceRel);
+        const relayAppendix = options.appendTelegramRelayBlock
+            ? '\n\n' + buildPersistentRelayAppendix(framework)
+            : '';
+        fs.writeFileSync(target, banner + content + relayAppendix, 'utf-8');
+        shadowsWritten.push(target);
+    }
+    return { source, shadowsWritten, skipped };
+}
+/**
+ * Markdown appendix that lives at the bottom of AGENTS.md / CLAUDE.md when
+ * Telegram is configured. The wording mirrors the bootstrap-message helper
+ * (`buildTelegramRelayBlock`) but is phrased for the system-prompt context
+ * rather than the per-message turn.
+ *
+ * For Claude Code, the SessionStart shell hook already injects "MANDATORY:
+ * After EVERY response, relay…" — but rendering it into CLAUDE.md too is
+ * harmless redundancy that survives hook removal or misconfiguration.
+ *
+ * For Codex CLI, this is the ONLY persistent mechanism — Codex has no
+ * SessionStart hook system, so the AGENTS.md content has to carry the
+ * relay convention across every turn.
+ */
+function buildPersistentRelayAppendix(framework) {
+    const isCodex = framework === 'codex-cli';
+    return [
+        `## Telegram Relay (MANDATORY)`,
+        ``,
+        `Every Telegram message you receive arrives prefixed \`[telegram:N "topic name" from User]\`. After responding, you MUST run this exact bash command to send the user your reply — without it, the user only sees sentinel messages and thinks you ignored them:`,
+        ``,
+        '```bash',
+        `cat <<'EOF' | .claude/scripts/telegram-reply.sh N`,
+        `Your conversational response text here.`,
+        `EOF`,
+        '```',
+        ``,
+        `(Replace \`N\` with the topic id from the prefix.)`,
+        ``,
+        `Rules:`,
+        `- Strip the \`[telegram:N]\` prefix before interpreting the message.`,
+        `- Relay ONLY conversational text — not tool output, raw logs, or internal reasoning.`,
+        `- Send a short ACK first ("Got it, looking into this…"), then do the work, then send the full reply.`,
+        isCodex
+            ? `- Codex CLI specifically: this convention applies to EVERY turn in a Telegram-spawned session, not just the first one. There's no per-turn reminder beyond this AGENTS.md section.`
+            : `- Claude Code specifically: the SessionStart hook reinforces this on session start; this section is the durable backup.`,
+    ].join('\n');
+}
+/**
+ * Resolve the canonical AGENT.md path. Searches the explicit override
+ * first, then `.instar/AGENT.md`, then root-level `AGENT.md`. Returns
+ * null if none is found.
+ */
+function resolveSource(projectDir, override) {
+    const candidates = [
+        override,
+        path.join(projectDir, '.instar', 'AGENT.md'),
+        path.join(projectDir, 'AGENT.md'),
+    ].filter((p) => p !== undefined);
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Detect framework from an existing project layout. Used for legacy
+ * installs that have CLAUDE.md but no AGENT.md — we can infer which
+ * framework was configured and seed AGENT.md from the shadow content.
+ *
+ * Returns null when no framework-specific file is found.
+ */
+export function detectFrameworkFromShadowFiles(projectDir) {
+    for (const [framework, filename] of Object.entries(FRAMEWORK_SHADOW_FILES)) {
+        if (fs.existsSync(path.join(projectDir, filename)))
+            return framework;
+    }
+    return null;
+}
+/**
+ * Ensure the shadow file a framework expects exists at the project root,
+ * bootstrapping the canonical AGENT.md from any legacy shadow first if
+ * needed.
+ *
+ * Lifecycle:
+ *   - If `<projectDir>/<framework-shadow>` already exists, no-op.
+ *   - If `.instar/AGENT.md` exists, render the requested framework's
+ *     shadow from it.
+ *   - If neither exists but a different shadow does (e.g., legacy
+ *     CLAUDE.md without AGENT.md), bootstrap AGENT.md from that shadow,
+ *     then render the requested shadow.
+ *   - If nothing exists, no-op — the project has no identity content
+ *     to seed from.
+ *
+ * Returns the path of the written shadow file, or null when the operation
+ * was a no-op.
+ *
+ * Idempotent. Safe to call before every spawn — checks file existence
+ * first and only writes when there's something useful to do.
+ */
+export function ensureFrameworkIdentityFile(projectDir, framework, options = {}) {
+    const filename = FRAMEWORK_SHADOW_FILES[framework];
+    if (!filename)
+        return null;
+    const targetPath = path.join(projectDir, filename);
+    // When the shadow exists, check whether the Telegram-relay appendix is
+    // missing. If callers asked for it (Telegram is configured) and the
+    // existing file predates the appendix, re-render so Codex sessions get
+    // the durable relay convention without requiring a manual edit.
+    if (fs.existsSync(targetPath)) {
+        if (options.appendTelegramRelayBlock) {
+            try {
+                const existing = fs.readFileSync(targetPath, 'utf-8');
+                if (existing.includes('## Telegram Relay (MANDATORY)')) {
+                    return null; // already up to date
+                }
+            }
+            catch {
+                // unreadable — fall through to re-render
+            }
+            // Fall through to render below
+        }
+        else {
+            return null;
+        }
+    }
+    // Ensure AGENT.md exists as the canonical source. If it doesn't,
+    // try to bootstrap from a legacy shadow file (e.g., CLAUDE.md).
+    const sourcePath = resolveSource(projectDir, options.stateDir
+        ? path.join(options.stateDir, 'AGENT.md')
+        : undefined);
+    if (sourcePath === null) {
+        const bootstrapped = bootstrapAgentMdFromShadow(projectDir, options);
+        if (bootstrapped === null)
+            return null;
+    }
+    const result = renderIdentity({
+        projectDir,
+        frameworks: [framework],
+        sourcePath: options.stateDir
+            ? path.join(options.stateDir, 'AGENT.md')
+            : undefined,
+        appendTelegramRelayBlock: options.appendTelegramRelayBlock,
+    });
+    return result.shadowsWritten[0] ?? null;
+}
+/**
+ * Bootstrap AGENT.md from a legacy CLAUDE.md (or other shadow file).
+ *
+ * Used during migration when a project has a CLAUDE.md but no AGENT.md.
+ * Reads the shadow, strips the auto-generation banner if present, and
+ * writes the canonical AGENT.md.
+ *
+ * Returns the absolute path of the written AGENT.md, or null if no
+ * shadow file could be found.
+ */
+export function bootstrapAgentMdFromShadow(projectDir, options = {}) {
+    const framework = detectFrameworkFromShadowFiles(projectDir);
+    if (!framework)
+        return null;
+    const shadowFilename = FRAMEWORK_SHADOW_FILES[framework];
+    const shadowPath = path.join(projectDir, shadowFilename);
+    let content = fs.readFileSync(shadowPath, 'utf-8');
+    // Strip an existing banner if present so we don't end up with nested
+    // "AUTO-GENERATED" notices.
+    content = content.replace(/^<!--[\s\S]*?-->\n+/, '');
+    const stateDir = options.stateDir ?? path.join(projectDir, '.instar');
+    if (!fs.existsSync(stateDir)) {
+        fs.mkdirSync(stateDir, { recursive: true });
+    }
+    const agentMdPath = path.join(stateDir, 'AGENT.md');
+    fs.writeFileSync(agentMdPath, content, 'utf-8');
+    return agentMdPath;
+}
+//# sourceMappingURL=IdentityRenderer.js.map

package/dist/core/IdentityRenderer.js.map

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

package/dist/core/PostUpdateMigrator.d.ts

@@ -72,6 +72,8 @@ export declare class PostUpdateMigrator {
      * each migration is idempotent.
      */
     migrate(): MigrationResult;
+    private migrateProviderPortability;
+    private migrateFleetWatchdog;
     private migrateContextDeathAntiPattern;
     /**
      * Read `.instar/identity-pins.json` if present. Returns an object

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

@@ -1 +1 @@
-{"version":3,"file":"PostUpdateMigrator.d.ts","sourceRoot":"","sources":["../../src/core/PostUpdateMigrator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"PostUpdateMigrator.d.ts","sourceRoot":"","sources":["../../src/core/PostUpdateMigrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA8BH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAIjC,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,kCAAkC;IAClC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAiB;IAC/B;;;;;;OAMG;IACH,OAAO,CAAC,UAAU,CAAiC;gBAEvC,MAAM,EAAE,cAAc;IAIlC;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAItC;;;;;;OAMG;IACG,eAAe,CACnB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,qBAAqB,CAAC;IAIjC,OAAO,CAAC,aAAa;IAOrB;;;OAGG;IACH,OAAO,IAAI,eAAe;IA4C1B,OAAO,CAAC,0BAA0B;IAkElC,OAAO,CAAC,oBAAoB;IAqH5B,OAAO,CAAC,8BAA8B;IA2EtC;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,0BAA0B;IA8BlC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAW5B;;;;;;;;;OASG;IACH,OAAO,CAAC,kBAAkB;IA2B1B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,OAAO,CAAC,yBAAyB;IA4HjC;6EACyE;IACzE,OAAO,CAAC,wBAAwB;IAShC;sDACkD;IAClD,OAAO,CAAC,wBAAwB;IAQhC;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAiKpB;;;;;;;;OAQG;IACH,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IA6CvE;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IA+DzB;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAkChC;;;;;;;;;OASG;IACH,OAAO,CAAC,wBAAwB;IAoEhC;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAiE5B;;;;;OAKG;IACH,OAAO,CAAC,2BAA2B;IA8BnC;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;IAwGhC;;;;;;OAMG;IACH,OAAO,CAAC,8BAA8B;IAwDtC,OAAO,CAAC,0BAA0B;IA8DlC;;;OAGG;IACH,OAAO,CAAC,eAAe;IAgXvB;;;OAGG;IACH,OAAO,CAAC,cAAc;IA0FtB;;;OAGG;IACH,OAAO,CAAC,eAAe;IA0NvB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAqFrB;;;OAGG;IACH;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAqChC,OAAO,CAAC,gBAAgB;IAiBxB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,OAAO,CAAC,qBAAqB;IAkE7B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,0BAA0B;IAgDlC;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAkC5B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,kBAAkB;IA2C1B;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IA+BzB,OAAO,CAAC,oBAAoB;IAgC5B;;;OAGG;IACH,OAAO,CAAC,aAAa;IAyBrB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAqC9B;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,qBAAqB,GAAG,yBAAyB,GAAG,mBAAmB,GAAG,wBAAwB,GAAG,8BAA8B,GAAG,2BAA2B,GAAG,4BAA4B,GAAG,iBAAiB,GAAG,0BAA0B,GAAG,wBAAwB,GAAG,iBAAiB,GAAG,0BAA0B,GAAG,uBAAuB,GAAG,iBAAiB,GAAG,MAAM;IAoB3Z,oFAAoF;IACpF,iCAAiC,IAAI,MAAM;IAI3C,6EAA6E;IAC7E,yBAAyB,IAAI,MAAM;IAInC,OAAO,CAAC,mBAAmB;IA0V3B,OAAO,CAAC,wBAAwB;IAmEhC,OAAO,CAAC,2BAA2B;IA0DnC,OAAO,CAAC,yBAAyB;IAuGjC,OAAO,CAAC,2BAA2B;IAsHnC,OAAO,CAAC,qBAAqB;IAqP7B,OAAO,CAAC,uBAAuB;IA6H/B,OAAO,CAAC,2BAA2B;IA8GnC,OAAO,CAAC,iCAAiC;IA6DzC,OAAO,CAAC,4BAA4B;IA4LpC;;;;;;;;;;OAUG;IACH;;;;;;;;;;;OAWG;IAEH,gBAAuB,iCAAiC,EAAE,WAAW,CAAC,MAAM,CAAC,CA4B1E;IAEH;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,8BAA8B;IAiHtC,OAAO,CAAC,uBAAuB;IA4B/B;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,sBAAsB;IAwC9B,OAAO,CAAC,iBAAiB;IAwBzB,OAAO,CAAC,mBAAmB;IAoB3B,OAAO,CAAC,8BAA8B;IAoHtC,OAAO,CAAC,+BAA+B;IAmJvC,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,qBAAqB;IA4N7B,OAAO,CAAC,qBAAqB;IA4H7B,OAAO,CAAC,6BAA6B;IAyKrC,OAAO,CAAC,0BAA0B;IAgClC,OAAO,CAAC,gBAAgB;IAqFxB,OAAO,CAAC,6BAA6B;CAoCtC"}

package/dist/core/PostUpdateMigrator.js

@@ -20,6 +20,8 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
 import crypto from 'node:crypto';
 import { SafeGitExecutor } from './SafeGitExecutor.js';
 import { fileURLToPath } from 'node:url';
@@ -107,8 +109,187 @@ export class PostUpdateMigrator {
         this.migrateSoulMd(result);
         this.migrateAgentMdSections(result);
         this.migrateContextDeathAntiPattern(result);
+        this.migrateProviderPortability(result);
+        this.migrateFleetWatchdog(result);
         return result;
     }
+    // ── Provider portability v1.0.0 — Phase 7 migration entry ──────────
+    //
+    // Idempotent migrator that runs on every `instar update`. Confirms the
+    // agent's config is portable-ready and records the migration in
+    // `_instar_migrations` so re-runs are no-ops. Auto-detects Codex CLI
+    // presence and surfaces it in the result for the user-visible upgrade
+    // path. No config mutation beyond the migration marker — the runtime
+    // frameworkBinaryPaths population in Config.ts is the load-bearing
+    // piece, and it runs at every boot.
+    //
+    // What this migrator INTENTIONALLY does NOT do:
+    //  - Flip an existing Claude-only agent to a different framework
+    //    default (operator choice via /route or topicFrameworks config).
+    //  - Force-install Codex CLI (user's package-manager choice).
+    //  - Write any credentials (Spec 12 Rule 1 — subscription-only path).
+    migrateProviderPortability(result) {
+        const configPath = path.join(this.config.stateDir, 'config.json');
+        if (!fs.existsSync(configPath)) {
+            result.skipped.push('provider-portability: config.json not found');
+            return;
+        }
+        let config;
+        try {
+            config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        }
+        catch (err) {
+            result.errors.push(`provider-portability: config.json read failed: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        const migrations = (config._instar_migrations ?? []);
+        const marker = 'provider-portability-v1.0.0';
+        const alreadyMigrated = migrations.some(m => m.startsWith(marker));
+        if (alreadyMigrated) {
+            result.skipped.push('provider-portability: already migrated');
+            return;
+        }
+        // Best-effort backup snapshot. The BackupManager handles the actual
+        // snapshot; we just record a migration marker. If a future
+        // hard-refuse phase ever rolls back, the user can restore the
+        // pre-migration state.
+        const detectedCodex = (() => {
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports
+                const { detectCodexPath } = require('./Config.js');
+                return detectCodexPath();
+            }
+            catch {
+                return null;
+            }
+        })();
+        // Mark migration complete. No config field mutations — frameworkBinaryPaths
+        // is rebuilt at every server boot from live detection.
+        migrations.push(`${marker}-${new Date().toISOString()}`);
+        config._instar_migrations = migrations;
+        try {
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+            const codexNote = detectedCodex
+                ? `Codex CLI detected at ${detectedCodex} — portable to Codex via /route or topicFrameworks config.`
+                : 'Codex CLI not detected — install via `npm i -g @openai/codex` to enable Codex routing.';
+            result.upgraded.push(`provider-portability: v1.0.0 migration recorded. ${codexNote}`);
+        }
+        catch (err) {
+            result.errors.push(`provider-portability: config.json write failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // ── Fleet watchdog (lifeline-shadow-install-self-heal spec) ──────────
+    //
+    // The user-machine fleet watchdog supervises ALL instar agents on the host.
+    // It used to be a hand-rolled script at ~/.instar/instar-watchdog.sh with no
+    // source-of-truth or migration path. It now ships from
+    // `src/templates/scripts/instar-watchdog.sh` and is overwritten on every
+    // update so existing agents pick up improvements (PATH fixes, peer
+    // escalation, etc.).
+    //
+    // This migration runs in every agent's PostUpdateMigrator pass, but the
+    // installation it performs is per-machine (singleton). Multiple agents
+    // updating concurrently will produce identical writes — acceptable.
+    //
+    // Skipped on non-darwin (launchd plist is macOS-specific).
+    migrateFleetWatchdog(result) {
+        if (process.platform !== 'darwin') {
+            result.skipped.push('fleet-watchdog: non-darwin platform');
+            return;
+        }
+        const scriptPath = path.join(os.homedir(), '.instar', 'instar-watchdog.sh');
+        const plistPath = path.join(os.homedir(), 'Library', 'LaunchAgents', 'ai.instar.watchdog.plist');
+        // Locate the template (dev: src/core/ → ../../src/templates/...
+        //                     dist: dist/core/ → ../templates/...)
+        const candidates = [
+            path.resolve(__dirname, '..', 'templates', 'scripts', 'instar-watchdog.sh'),
+            path.resolve(__dirname, '..', '..', 'src', 'templates', 'scripts', 'instar-watchdog.sh'),
+        ];
+        let scriptBody = '';
+        for (const cand of candidates) {
+            if (fs.existsSync(cand)) {
+                scriptBody = fs.readFileSync(cand, 'utf-8');
+                break;
+            }
+        }
+        if (!scriptBody) {
+            result.skipped.push('fleet-watchdog: template not found in dist or src');
+            return;
+        }
+        const launchdPath = '/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin';
+        const stdoutPath = path.join(os.homedir(), '.instar', 'watchdog-launchd.log');
+        const stderrPath = path.join(os.homedir(), '.instar', 'watchdog-launchd.err');
+        const escapeXml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+        const plistBody = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>ai.instar.watchdog</string>
+    <key>ProgramArguments</key>
+    <array>
+      <string>/bin/bash</string>
+      <string>${escapeXml(scriptPath)}</string>
+    </array>
+    <key>StartInterval</key>
+    <integer>300</integer>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>${escapeXml(stdoutPath)}</string>
+    <key>StandardErrorPath</key>
+    <string>${escapeXml(stderrPath)}</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>${escapeXml(launchdPath)}</string>
+    </dict>
+</dict>
+</plist>`;
+        try {
+            // Compare against current contents to avoid noisy re-installs.
+            const scriptCurrent = fs.existsSync(scriptPath) ? fs.readFileSync(scriptPath, 'utf-8') : '';
+            const plistCurrent = fs.existsSync(plistPath) ? fs.readFileSync(plistPath, 'utf-8') : '';
+            const scriptChanged = scriptCurrent !== scriptBody;
+            const plistChanged = plistCurrent !== plistBody;
+            if (!scriptChanged && !plistChanged) {
+                result.skipped.push('fleet-watchdog: already up to date');
+                return;
+            }
+            fs.mkdirSync(path.dirname(scriptPath), { recursive: true });
+            fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+            if (scriptChanged)
+                fs.writeFileSync(scriptPath, scriptBody, { mode: 0o755 });
+            if (plistChanged)
+                fs.writeFileSync(plistPath, plistBody);
+            // Validate plist before triggering launchd
+            try {
+                execFileSync('plutil', ['-lint', plistPath], { stdio: 'pipe' });
+            }
+            catch (err) {
+                const stderr = err instanceof Error && 'stderr' in err ? String(err.stderr) : '';
+                result.errors.push(`fleet-watchdog: plist validation failed: ${stderr}`);
+                return;
+            }
+            // Reload only if plist changed (script-only changes don't need launchd touch).
+            if (plistChanged) {
+                const uid = process.getuid?.() ?? 501;
+                try {
+                    execFileSync('launchctl', ['bootout', `gui/${uid}`, plistPath], { stdio: 'ignore' });
+                }
+                catch { /* not loaded */ }
+                try {
+                    execFileSync('launchctl', ['bootstrap', `gui/${uid}`, plistPath], { stdio: 'ignore' });
+                }
+                catch { /* non-fatal */ }
+            }
+            result.upgraded.push(`fleet-watchdog: updated (script=${scriptChanged}, plist=${plistChanged})`);
+        }
+        catch (err) {
+            result.errors.push(`fleet-watchdog: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     // ── Context-death anti-pattern (PR1 — context-death-pitfall-
     //    prevention spec § (a)) ────────────────────────────────────────
     //