instar 0.28.76 → 0.28.78

package/dist/core/PostUpdateMigrator.js

@@ -21,13 +21,15 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { execSync } from 'node:child_process';
+import { SafeGitExecutor } from './SafeGitExecutor.js';
 import { fileURLToPath } from 'node:url';
 import { TreeGenerator } from '../knowledge/TreeGenerator.js';
 import { HTTP_HOOK_TEMPLATES, buildHttpHookSettings } from '../data/http-hook-templates.js';
 import { getMigrationDefaults, applyDefaults } from '../config/ConfigDefaults.js';
 import { installBuiltinSkills } from '../commands/init.js';
 import { ELIGIBILITY_SCHEMA_SQL, ELIGIBILITY_SCHEMA_SQL_SHA256, PUSH_GATE_SH, PUSH_GATE_SH_SHA256, INSTAR_PR_GATE_WORKFLOW_YML, INSTAR_PR_GATE_WORKFLOW_YML_SHA256, PR_GATE_SETUP_MD, PR_GATE_SETUP_MD_SHA256, } from '../data/pr-gate-artifacts.js';
+import { SafeFsExecutor } from './SafeFsExecutor.js';
+import { DegradationReporter } from '../monitoring/DegradationReporter.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export class PostUpdateMigrator {
     config;
@@ -485,8 +487,7 @@ export class PostUpdateMigrator {
             try {
                 // Move built-in hooks to instar/ — they'll be overwritten by the current
                 // migrateHooks() call anyway, but cleaning up the old location is important
-                // safe-git-allow: incremental-migration
-                fs.unlinkSync(oldPath);
+                SafeFsExecutor.safeUnlinkSync(oldPath, { operation: 'src/core/PostUpdateMigrator.ts:524' });
             }
             catch {
                 // If we can't remove, it's not critical — the new hooks will be written
@@ -1316,24 +1317,22 @@ The user has been talking to you (possibly for days). A generic greeting like "H
                 }
             }
             else {
-                try {
-                    const existing = fs.readFileSync(scriptPath, 'utf-8');
-                    // Only overwrite if the existing copy is an older version (lacks 408
-                    // handling) AND looks like the shipped version (starts with the
-                    // shipped shebang comment). Don't stomp custom user scripts.
-                    const looksShipped = existing.includes('telegram-reply.sh — Send a message back to a Telegram topic via instar server');
-                    const hasNewHandling = existing.includes('HTTP_CODE" = "408"');
-                    if (looksShipped && !hasNewHandling) {
-                        fs.writeFileSync(scriptPath, newContent, { mode: 0o755 });
-                        result.upgraded.push('scripts/telegram-reply.sh (upgraded to HTTP 408 ambiguous-outcome handling)');
-                    }
-                    else {
-                        result.skipped.push('scripts/telegram-reply.sh (already exists)');
-                    }
-                }
-                catch (err) {
-                    result.errors.push(`telegram-reply.sh migration: ${err instanceof Error ? err.message : String(err)}`);
-                }
+                // SHA-based migrator (spec § Layer 1, migration). Replaces the
+                // marker-string match — which silently overwrote any user
+                // customization that happened to keep the shipped header line.
+                // The new flow is hash-only: if the on-disk SHA matches a
+                // known prior shipped version, back up + overwrite; if it
+                // matches the new template, no-op; otherwise leave the
+                // original alone, write a `.new` candidate, and surface a
+                // degradation event so the operator sees the customization
+                // and can resolve it.
+                this.migrateReplyScriptToPortConfig({
+                    scriptPath,
+                    newContent,
+                    label: 'scripts/telegram-reply.sh',
+                    stateDir: this.config.stateDir,
+                    result,
+                });
             }
         }
         // Slack reply script — file-presence gated (migrator has no hasSlack
@@ -1933,11 +1932,11 @@ The user has been talking to you (possibly for days). A generic greeting like "H
         };
         const getRemote = (name) => {
             try {
-                // safe-git-allow: incremental-migration
-                return execSync(`git remote get-url ${name}`, {
+                return SafeGitExecutor.readSync(['remote', 'get-url', name], {
                     cwd: this.config.projectDir,
                     stdio: ['ignore', 'pipe', 'ignore'],
                     encoding: 'utf-8',
+                    operation: 'src/core/PostUpdateMigrator.ts:getRemote',
                 });
             }
             catch {
@@ -3055,12 +3054,20 @@ echo "=== END IDENTITY RECOVERY ==="
     }
     getDeferralDetectorHook() {
         return `#!/usr/bin/env node
-// Deferral detector — catches agents deferring work they could do themselves.
-// PreToolUse hook for Bash commands. Scans outgoing messages for deferral patterns.
+// Deferral detector — catches agents deferring work they could do themselves
+// AND catches agents proposing orphan-TODO follow-ups with no infrastructure.
+// PreToolUse hook for Bash commands. Scans outgoing messages for the patterns.
 // When detected, injects a due diligence checklist (does NOT block).
 //
-// Born from an agent saying "This is credential input I cannot do myself"
-// when it already had the token available via CLI tools.
+// Born from two failure modes:
+//   1) An agent saying "This is credential input I cannot do myself" when it
+//      already had the token available via CLI tools.
+//   2) An agent saying "queue for next session" / "loop back later" / "we
+//      can pick this up in a follow-up" with no /schedule cron and no
+//      /commit-action tracker — the orphan-TODO trap that makes
+//      promised follow-through evaporate (incident: 2026-04-27, when
+//      Echo proposed exactly this pattern after Layer 1 of a multi-layer
+//      build shipped without infra to ensure follow-on layers landed).
 
 let data = '';
 process.stdin.on('data', chunk => data += chunk);
@@ -3082,8 +3089,8 @@ process.stdin.on('end', () => {
     // Exempt: genuinely human-only actions
     if (/password|captcha|legal|billing|payment credential/i.test(command)) process.exit(0);
 
-    // Deferral patterns
-    const patterns = [
+    // Inability / passing-the-buck patterns (original detector scope)
+    const inabilityPatterns = [
       { re: /(?:I |i )(?:can'?t|cannot|am (?:not |un)able to)/i, type: 'inability_claim' },
       { re: /(?:this |it )(?:requires|needs) (?:your|human|manual) (?:input|intervention|action)/i, type: 'human_required' },
       { re: /you(?:'ll| will)? need to (?:do|handle|complete|input|enter|run|execute|click)/i, type: 'directing_human' },
@@ -3092,25 +3099,78 @@ process.stdin.on('end', () => {
       { re: /(?:blocker|blocking issue|can'?t proceed (?:without|until))/i, type: 'claimed_blocker' },
     ];
 
-    const matches = patterns.filter(p => p.re.test(command));
-    if (matches.length === 0) process.exit(0);
+    // Orphan-TODO patterns — proposing future-self follow-up without infrastructure.
+    // The danger: "later" without /schedule or /commit-action evaporates between
+    // sessions because there is no automatic carry-over.
+    const orphanPatterns = [
+      { re: /queue (?:them |it |this )?(?:up |for )?(?:the )?(?:next session|later|future|follow[- ]?up)/i, type: 'queue_for_later' },
+      { re: /(?:pick (?:this |it )?up|circle back|loop back|come back) (?:later|in (?:a |the )?(?:next|future|follow[- ]?up))/i, type: 'pick_up_later' },
+      { re: /(?:in |for )(?:a |the |another )?(?:follow[- ]?up|next session|future session|later session)/i, type: 'follow_up_session' },
+      { re: /(?:i'?ll |i will |i can |we (?:can|could) )(?:address|tackle|handle|fix|do|build|implement) (?:that |this |it )?(?:later|next time|in (?:the |a )?(?:future|follow[- ]?up))/i, type: 'self_promised_later' },
+      { re: /(?:deferred|defer|deferring) (?:to|until|for) (?:a |the |next |another )?(?:follow[- ]?up|session|later|future)/i, type: 'explicit_defer' },
+      { re: /(?:next time|future work|left for later|future iteration|TODO:?\\s*later)/i, type: 'future_work_marker' },
+    ];
 
-    const checklist = [
-      'DEFERRAL DETECTED — Before claiming you cannot do something, verify:',
-      '',
-      '1. Did you check --help or docs for the tool you are using?',
-      '2. Did you search for a token/API-based alternative to interactive auth?',
-      '3. Do you already have credentials/tokens that might work? (env vars, CLI auth, saved configs)',
-      '4. Can you use browser automation to complete interactive flows?',
-      '5. Is this GENUINELY beyond your access? (e.g., typing a password, solving a CAPTCHA)',
-      '',
-      'If ANY check might work — try it first.',
-      'The pattern: You are DESCRIBING work instead of DOING work.',
-      '',
-      'Detected: ' + matches.map(m => m.type).join(', '),
-    ].join('\\n');
+    // Anti-trigger: messages that DO back the deferral with infrastructure
+    // get a pass — they are not orphan TODOs. The same message that mentions
+    // /schedule, /commit-action, a cron expression, or a tracked deadline
+    // is doing it right.
+    const infrastructureBackedPatterns = [
+      /\\/schedule\\b/i,
+      /\\/commit[-_ ]?action\\b/i,
+      /commit-action\\b/i,
+      /scheduled (?:agent|run|cron|routine)/i,
+      /cron expression|cron schedule/i,
+      /tracked (?:commitment|deadline|action[- ]?item)/i,
+      /follow[- ]?up (?:PR|commit|branch)\\b/i,
+    ];
+    const isInfrastructureBacked = infrastructureBackedPatterns.some(p => p.test(command));
+
+    const inabilityMatches = inabilityPatterns.filter(p => p.re.test(command));
+    const orphanMatches = isInfrastructureBacked
+      ? []  // Backed by real infra — not an orphan TODO.
+      : orphanPatterns.filter(p => p.re.test(command));
+
+    const allMatches = [...inabilityMatches, ...orphanMatches];
+    if (allMatches.length === 0) process.exit(0);
+
+    const checklist = [];
+
+    if (inabilityMatches.length > 0) {
+      checklist.push(
+        'DEFERRAL DETECTED — Before claiming you cannot do something, verify:',
+        '',
+        '1. Did you check --help or docs for the tool you are using?',
+        '2. Did you search for a token/API-based alternative to interactive auth?',
+        '3. Do you already have credentials/tokens that might work? (env vars, CLI auth, saved configs)',
+        '4. Can you use browser automation to complete interactive flows?',
+        '5. Is this GENUINELY beyond your access? (e.g., typing a password, solving a CAPTCHA)',
+        '',
+        'If ANY check might work — try it first.',
+        'The pattern: You are DESCRIBING work instead of DOING work.',
+      );
+    }
+
+    if (orphanMatches.length > 0) {
+      if (checklist.length > 0) checklist.push('');
+      checklist.push(
+        'ORPHAN-TODO TRAP DETECTED — You proposed deferring work to "later" or "next session" without backing infrastructure.',
+        '',
+        'Without one of these, the work will not actually happen:',
+        '  - /schedule a remote agent (cron or one-shot) to do the work',
+        '  - /commit-action with a deadline so it surfaces on the work queue',
+        '  - A same-branch follow-up commit chained to merge before you stop',
+        '  - Tying the deferred work to an existing tracked spec/issue',
+        '',
+        'If none of those apply, the deferral evaporates between sessions.',
+        'Either back the deferral with infrastructure NOW, or do the work NOW.',
+        '"I will get to it next time" is not infrastructure.',
+      );
+    }
+
+    checklist.push('', 'Detected: ' + allMatches.map(m => m.type).join(', '));
 
-    process.stdout.write(JSON.stringify({ decision: 'approve', additionalContext: checklist }));
+    process.stdout.write(JSON.stringify({ decision: 'approve', additionalContext: checklist.join('\\n') }));
   } catch { /* don't break on errors */ }
   process.exit(0);
 });
@@ -3483,6 +3543,149 @@ process.stdin.on('end', async () => {
      * telegram-reply.sh migration uses similar logic inline because it ALSO
      * installs on first run (hasTelegram gate); these two are upgrade-only.
      */
+    /**
+     * Known-shipped SHA-256 hashes of `src/templates/scripts/telegram-reply.sh`.
+     *
+     * The migrator overwrites an on-disk copy only when its SHA matches one
+     * of these — meaning it is a verbatim prior shipped version. Any other
+     * content (user customization, partial edits, accidental damage) is
+     * preserved. The new template is written alongside as `.new` and a
+     * degradation event is raised so the operator can resolve it manually.
+     *
+     * Add the prior shipped SHA when shipping a new template; never remove
+     * old SHAs (they remain valid migration sources).
+     */
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    static TELEGRAM_REPLY_PRIOR_SHIPPED_SHAS = new Set([
+        // Tier-1 initial-init shipped version. Shipped at 362ff59d.
+        '98f70b86856e37f2719c39ecec152adf07ec30ce73c8134ab831b35c5b1c25b3',
+        // Rebrand to Instar (no behavioral change). Shipped at 686f5758.
+        '6ebc835e0077dc1cd52ec15820722b7059cf11bf5796775902f82034d43b29c4',
+        // Batch feedback fixes — auth headers, job topics race, session limits.
+        // Shipped at d28120f0.
+        'ce73a2fd1941381b63eb591d7c30ed761496202437a8c7fffa4926c6dfa2b7cb',
+        // Tone-gate inline check on outbound messaging (no 408 handling yet).
+        // Shipped at 2cb50a9a.
+        'f3aa0c8aae3f3275d0efb45b333ad83c14f7513a9e27c743039a9a113c0d16ff',
+        // Adds 120s timeout + HTTP 408 ambiguous-outcome path (no port-from-
+        // config yet). Shipped at a049fc5f.
+        '4f8787df1bf6384545dd7f19093fd77daa1bf993ed48a8ab02b6598d41a2007c',
+        // Pre-port-config version (HTTP 408 handling, INSTAR_PORT-or-4040 default,
+        // no agent-id header). Shipped through 2026-04-27.
+        '3d08c63c6280d0a7ba94a345c259673a461ee5c1d116cb47c95c7626c67cee23',
+        // Layer 1 shipped version (port-from-config + agent-id header, no
+        // recoverable-class detection). Shipped 2026-04-27 with the Layer 1
+        // PR #100. Adding here so the Layer 2 migration cleanly upgrades from
+        // a Layer-1-deployed copy without producing a `.new` candidate.
+        '5ec2eb19bf35310471f107cb54219097698abad1c11166eb14daf746a63a2f08',
+        // Layer 2 shipped version (durable SQLite queue + structured failure
+        // events). Shipped 2026-04-27 with the Layer 2 PR #101. Recorded here
+        // (rather than left as the implicit current-template SHA) because the
+        // verifier and lint both treat any deployed SHA matching this set as
+        // a known-shipped instar version, not user-modified content.
+        '371d7e8f4f72146bf8bd07115873bdbbaaf32e851ac6e1318ba5b8929cd06e68',
+    ]);
+    /**
+     * SHA-based migrator for telegram-reply.sh — replaces marker-string
+     * detection with content-hash detection. See spec
+     * docs/specs/telegram-delivery-robustness.md § Layer 1 "Migration".
+     *
+     * Three branches:
+     *   - on-disk SHA ∈ prior-shipped → back up and overwrite with new template.
+     *   - on-disk SHA == new-template SHA → no-op (idempotent).
+     *   - otherwise → write `<scriptPath>.new`, raise a
+     *     `relay-script-modified-locally` degradation event, leave the
+     *     original untouched.
+     */
+    migrateReplyScriptToPortConfig(opts) {
+        let existing;
+        try {
+            existing = fs.readFileSync(opts.scriptPath, 'utf-8');
+        }
+        catch (err) {
+            opts.result.errors.push(`${opts.label} migration: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        const existingSha = crypto.createHash('sha256').update(existing).digest('hex');
+        const newSha = crypto.createHash('sha256').update(opts.newContent).digest('hex');
+        if (existingSha === newSha) {
+            // Idempotent path — already on the new template. Assert this by
+            // recording a no-op result; never write, never back up.
+            opts.result.skipped.push(`${opts.label} (already current)`);
+            return;
+        }
+        if (PostUpdateMigrator.TELEGRAM_REPLY_PRIOR_SHIPPED_SHAS.has(existingSha)) {
+            // Backup-then-overwrite. Backup directory lives under the agent's
+            // state dir (so it follows backup/restore semantics already
+            // configured for .instar/).
+            const backupDir = path.join(opts.stateDir, 'backups');
+            try {
+                fs.mkdirSync(backupDir, { recursive: true });
+                const backupPath = path.join(backupDir, `telegram-reply.sh.${Date.now()}`);
+                fs.writeFileSync(backupPath, existing, { mode: 0o644 });
+                fs.writeFileSync(opts.scriptPath, opts.newContent, { mode: 0o755 });
+                opts.result.upgraded.push(`${opts.label} (upgraded to port-from-config + agent-id binding; ` +
+                    `prior version backed up to ${path.relative(opts.stateDir, backupPath)})`);
+            }
+            catch (err) {
+                opts.result.errors.push(`${opts.label} migration: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return;
+        }
+        // Unknown content (user-modified or unknown version). Write a `.new`
+        // candidate next to the original and raise a degradation event so
+        // the operator can resolve it without us stomping their changes.
+        //
+        // Idempotency: if a `.new` file already exists with byte-identical
+        // content (e.g., this is the second `instar update` against the same
+        // user-modified script), skip the rewrite and the degradation event
+        // so the operator doesn't get duplicate noise on every upgrade.
+        const candidatePath = `${opts.scriptPath}.new`;
+        let candidateAlreadyCurrent = false;
+        try {
+            const existingCandidate = fs.readFileSync(candidatePath, 'utf-8');
+            if (existingCandidate === opts.newContent) {
+                candidateAlreadyCurrent = true;
+            }
+        }
+        catch {
+            // No existing .new file — fall through to write.
+        }
+        if (!candidateAlreadyCurrent) {
+            try {
+                fs.writeFileSync(candidatePath, opts.newContent, { mode: 0o755 });
+            }
+            catch (err) {
+                opts.result.errors.push(`${opts.label} migration: ${err instanceof Error ? err.message : String(err)}`);
+                return;
+            }
+            // Only fire the degradation event the first time we detect the
+            // drift OR when the new template content has shifted since the
+            // last `.new` write. Re-running the migrator on the same unknown
+            // on-disk SHA + same new template SHA is a no-op event-wise.
+            try {
+                const reporter = DegradationReporter.getInstance();
+                if (reporter && typeof reporter.report === 'function') {
+                    reporter.report({
+                        feature: 'relay-script-modified-locally',
+                        primary: 'overwrite shipped relay script with new template',
+                        fallback: 'wrote new template alongside as .new — operator review required',
+                        reason: `${opts.label} content does not match any prior shipped SHA ` +
+                            `(found sha256:${existingSha.slice(0, 12)}…). New template ` +
+                            `written to ${path.basename(candidatePath)}.`,
+                        impact: 'Relay script keeps running with user-modified content; the ' +
+                            'port-from-config + agent-id binding fix is NOT active until ' +
+                            'the operator reconciles the .new file.',
+                    });
+                }
+            }
+            catch {
+                // DegradationReporter is best-effort; don't block migration on it.
+            }
+        }
+        opts.result.skipped.push(`${opts.label} (user-modified — new version ` +
+            `${candidateAlreadyCurrent ? 'already' : ''} written to ${path.basename(candidatePath)})`);
+    }
     migrateReplyScriptTo408(opts) {
         if (!fs.existsSync(opts.scriptPath))
             return; // Not installed — not our responsibility here