instar 1.1.3 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.1.3",
+  "version": "1.2.1",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -105,6 +105,7 @@
     "moltbridge": "^0.1.6",
     "picocolors": "^1.0.0",
     "proper-lockfile": "^4.1.2",
+    "telegram": "^2.26.22",
     "ws": "^8.19.0",
     "zod": "^4.3.6"
   },

package/scripts/check-repo-invariants.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * Repository-state invariants — CI safety net (Layer 4 of the
+ * test-env-isolation defense).
+ *
+ * Asserts properties of the checked-out tree that would otherwise be
+ * easy to clobber without anyone noticing on a code-review pass:
+ *
+ *   1. README.md is at least MIN_README_LINES (default: 100). The
+ *      "# Test Project" stub-on-main incident (PRs #130/#277) cut it
+ *      to 1 line and shipped to npm.
+ *   2. No fixture stowaway files at the repo root. file-0.txt and
+ *      seed are signature artifacts of the test-fixture pollution
+ *      class; they should never exist on main.
+ *
+ * Exit 0 = invariants hold. Exit 1 = at least one violated; the
+ * specific failures are printed to stderr.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ROOT = process.cwd();
+const MIN_README_LINES = Number(process.env.INSTAR_README_MIN_LINES || 100);
+
+const failures = [];
+
+// ── README.md size floor ──────────────────────────────────────────
+const readmePath = path.join(ROOT, 'README.md');
+if (!fs.existsSync(readmePath)) {
+  failures.push(`README.md is missing from repo root.`);
+} else {
+  const lines = fs.readFileSync(readmePath, 'utf-8').split('\n').length;
+  if (lines < MIN_README_LINES) {
+    failures.push(
+      `README.md has ${lines} lines, below the ${MIN_README_LINES}-line floor. ` +
+      `Likely test-fixture pollution clobbered the file. Restore from git history.`,
+    );
+  }
+}
+
+// ── Fixture stowaway files at repo root ───────────────────────────
+const FIXTURE_STOWAWAYS = ['file-0.txt', 'seed'];
+for (const name of FIXTURE_STOWAWAYS) {
+  const p = path.join(ROOT, name);
+  if (fs.existsSync(p)) {
+    const stat = fs.statSync(p);
+    if (stat.isFile()) {
+      failures.push(
+        `Fixture stowaway "${name}" exists at repo root. ` +
+        `This is the signature of a test committing into the real repo. ` +
+        `Delete the file and rebuild the test that produced it with sanitizedGitEnv().`,
+      );
+    }
+  }
+}
+
+if (failures.length === 0) {
+  console.log('✅ Repository invariants hold.');
+  process.exit(0);
+}
+
+process.stderr.write('\n🚫 Repository invariants violated:\n\n');
+for (const f of failures) {
+  process.stderr.write(`  - ${f}\n`);
+}
+process.stderr.write('\n');
+process.exit(1);

package/scripts/lib/telegram-historian.mjs

@@ -0,0 +1,224 @@
+/**
+ * TelegramHistorian — gramjs-based MTProto backfill for instar topic-memory.
+ *
+ * Built 2026-05-20 in response to topic 10873 incident: Echo's
+ * topic-memory.db was truncated during a Node 22→25 native-module cascade,
+ * losing the local mirror of multiple Telegram topics. Telegram's Bot API
+ * is forward-only — bots cannot fetch chat history. A user-account MTProto
+ * session can. This module is the gramjs half of the recovery path.
+ *
+ * Authority posture (read carefully before extending):
+ *   - This module authenticates AS the operator's Telegram account. It is
+ *     not a bot. It can read everything the operator's account can read,
+ *     including DMs and private groups. That power requires discipline.
+ *   - Permitted operations: iterMessages (read), getDialogs (read),
+ *     getMessages (read). No send/edit/delete is ever issued from here.
+ *   - The session string is the long-lived credential. It must live behind
+ *     mode-0600 file permissions, outside any git-tracked path, and be
+ *     migrated into a real secret store as soon as one is available.
+ *   - Auth requires interactive SMS code entry by the operator. The
+ *     onCode/onPassword callbacks here are the only interactive surface.
+ *
+ * Forum topics: in a Telegram forum supergroup, each topic is identified
+ * by the message id of its topic-header message. Replies and posts in a
+ * topic carry reply_to.forum_topic = true and reply_to.reply_to_top_id =
+ * <topic_id>. gramjs surfaces this via the `replyTo` option to
+ * iterMessages — a value matching the topic id filters to that topic.
+ */
+
+import { TelegramClient } from 'telegram';
+import { StringSession } from 'telegram/sessions/index.js';
+import { Api } from 'telegram';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * @typedef {Object} HistorianCredentials
+ * @property {number} apiId
+ * @property {string} apiHash
+ * @property {string} sessionFilePath  Absolute path to the session string file
+ */
+
+/**
+ * @typedef {Object} AuthPrompts
+ * @property {() => Promise<string>} onPhoneNumber       Required if no saved session
+ * @property {() => Promise<string>} onCode              Required if no saved session
+ * @property {() => Promise<string>} [onPassword]        Optional 2FA password
+ * @property {(error: Error) => void} [onError]
+ */
+
+const CONNECTION_RETRIES = 5;
+
+export class TelegramHistorian {
+  /**
+   * @param {HistorianCredentials} creds
+   * @param {{ verbose?: boolean }} [opts]
+   */
+  constructor(creds, opts = {}) {
+    this.creds = creds;
+    this.verbose = opts.verbose ?? false;
+    this.client = null;
+  }
+
+  _loadSavedSession() {
+    if (!this.creds.sessionFilePath) return '';
+    if (!fs.existsSync(this.creds.sessionFilePath)) return '';
+    return fs.readFileSync(this.creds.sessionFilePath, 'utf8').trim();
+  }
+
+  _saveSession(sessionStr) {
+    if (!this.creds.sessionFilePath) return;
+    fs.mkdirSync(path.dirname(this.creds.sessionFilePath), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(this.creds.sessionFilePath, sessionStr, { mode: 0o600 });
+  }
+
+  /**
+   * Connect and authenticate. If a saved session string exists at
+   * creds.sessionFilePath, reuses it (no SMS needed). Otherwise drives
+   * the interactive auth flow through the provided callbacks.
+   *
+   * @param {AuthPrompts} prompts
+   */
+  async connect(prompts) {
+    const saved = this._loadSavedSession();
+    const session = new StringSession(saved);
+    this.client = new TelegramClient(session, this.creds.apiId, this.creds.apiHash, {
+      connectionRetries: CONNECTION_RETRIES,
+    });
+
+    await this.client.start({
+      phoneNumber: prompts.onPhoneNumber,
+      phoneCode: prompts.onCode,
+      password: prompts.onPassword ?? (async () => {
+        throw new Error('2FA password required but no onPassword callback provided');
+      }),
+      onError: prompts.onError ?? ((err) => {
+        // eslint-disable-next-line no-console
+        console.error('[TelegramHistorian] auth error:', err.message);
+      }),
+    });
+
+    const sessionStr = this.client.session.save();
+    if (sessionStr && sessionStr !== saved) {
+      this._saveSession(sessionStr);
+      if (this.verbose) {
+        // eslint-disable-next-line no-console
+        console.error('[TelegramHistorian] session saved to', this.creds.sessionFilePath);
+      }
+    }
+  }
+
+  async disconnect() {
+    if (this.client) {
+      await this.client.disconnect();
+      this.client = null;
+    }
+  }
+
+  _ensureConnected() {
+    if (!this.client) throw new Error('TelegramHistorian: not connected — call connect() first');
+  }
+
+  /**
+   * Resolve a supergroup reference (numeric id like -1003742343280, or
+   * @username) to a gramjs entity.
+   * @param {string | number | bigint} chatRef
+   */
+  async resolveChat(chatRef) {
+    this._ensureConnected();
+    return await this.client.getEntity(chatRef);
+  }
+
+  /**
+   * List forum topics in a supergroup. Returns each topic's id, title, and
+   * top_message id.
+   * @param {string | number | bigint} chatRef
+   * @returns {Promise<Array<{ id: number, title: string, topMessageId: number, closed: boolean }>>}
+   */
+  async listForumTopics(chatRef) {
+    this._ensureConnected();
+    const entity = await this.resolveChat(chatRef);
+    const result = await this.client.invoke(
+      new Api.channels.GetForumTopics({
+        channel: entity,
+        offsetDate: 0,
+        offsetId: 0,
+        offsetTopic: 0,
+        limit: 100,
+      }),
+    );
+    const topics = [];
+    for (const t of result.topics) {
+      // ForumTopic vs ForumTopicDeleted
+      if (t.className === 'ForumTopic') {
+        topics.push({
+          id: Number(t.id),
+          title: t.title,
+          topMessageId: Number(t.topMessage ?? t.id),
+          closed: Boolean(t.closed),
+        });
+      }
+    }
+    return topics;
+  }
+
+  /**
+   * Iterate all messages in a single forum topic, oldest-first. Yields
+   * one BackfillMessage at a time. Handles FloodWait via gramjs's
+   * built-in retry. Caller is responsible for importing.
+   *
+   * @param {string | number | bigint} chatRef
+   * @param {number} topicId  forum topic id
+   * @param {{ minMessageId?: number, batchSize?: number }} [opts]
+   */
+  async *iterTopicMessages(chatRef, topicId, opts = {}) {
+    this._ensureConnected();
+    const entity = await this.resolveChat(chatRef);
+    const batchSize = opts.batchSize ?? 100;
+    const minMessageId = opts.minMessageId ?? 0;
+
+    const iter = this.client.iterMessages(entity, {
+      replyTo: topicId,
+      limit: undefined,
+      reverse: true,
+      minId: minMessageId,
+      filter: undefined,
+    });
+
+    let pageCount = 0;
+    let yielded = 0;
+    for await (const msg of iter) {
+      if (!msg) continue;
+      const text = typeof msg.message === 'string' ? msg.message : '';
+      const sender = msg.sender ?? null;
+      const fromUser = msg.out === true ? 1 : 0;
+      const ts = new Date(Number(msg.date) * 1000).toISOString();
+
+      yield {
+        messageId: Number(msg.id),
+        topicId,
+        text,
+        timestamp: ts,
+        fromUser,
+        senderName: sender?.firstName
+          ? [sender.firstName, sender.lastName].filter(Boolean).join(' ')
+          : null,
+        senderUsername: sender?.username ?? null,
+        telegramUserId: sender?.id != null ? Number(sender.id) : null,
+        userId: null,
+        sessionName: null,
+        privacyScope: 'private',
+      };
+      yielded++;
+      if (yielded % batchSize === 0) {
+        pageCount++;
+        if (this.verbose) {
+          // eslint-disable-next-line no-console
+          console.error(
+            `[TelegramHistorian] topic ${topicId}: page ${pageCount} (${yielded} so far)`,
+          );
+        }
+      }
+    }
+  }
+}

package/scripts/lib/topic-memory-importer.mjs

@@ -0,0 +1,132 @@
+/**
+ * topic-memory-importer — idempotent import of Telegram messages into
+ * .instar/topic-memory.db.
+ *
+ * Built 2026-05-20 after the local topic-memory.db was truncated to 4
+ * messages during the Node 22→25 better-sqlite3 cascade recovery (incident
+ * recorded in topic 10873). Bots cannot fetch Telegram history; only a
+ * user-account MTProto session can. This module is the storage half of
+ * that backfill path — gramjs fetches, this writes.
+ *
+ * The schema (read 2026-05-20 from a live agent home):
+ *
+ *   messages(id PK auto, message_id, topic_id, text, from_user, timestamp,
+ *            session_name, sender_name, sender_username, telegram_user_id,
+ *            user_id, privacy_scope, UNIQUE(message_id, topic_id))
+ *
+ * The UNIQUE(message_id, topic_id) constraint is the idempotency primitive.
+ * `INSERT OR IGNORE` is the only sanctioned write path here — re-running
+ * the importer against the same input is a no-op.
+ *
+ * Concurrency: the instar server (echo's own process) holds topic-memory.db
+ * open under WAL mode. SQLite serializes writes across processes via WAL,
+ * so this importer can write while the server is reading without
+ * corruption. The FTS triggers maintain the FTS index automatically.
+ */
+
+import Database from 'better-sqlite3';
+
+/**
+ * @typedef {Object} BackfillMessage
+ * @property {number} messageId         Telegram message id (per chat)
+ * @property {number} topicId           Forum topic id (= message id of the
+ *                                       topic-header message in the supergroup)
+ * @property {string} text              Message text. Empty string for
+ *                                       service messages / media-only.
+ * @property {string} timestamp         ISO 8601 UTC
+ * @property {number} [fromUser]        1 if message was sent by the user
+ *                                       (justin), 0 if from any agent
+ * @property {string} [senderName]      Display name
+ * @property {string} [senderUsername]  @handle, no leading @
+ * @property {number} [telegramUserId]  Numeric Telegram user id
+ * @property {string} [userId]          instar user id, if known
+ * @property {string} [sessionName]     instar session name, if known
+ * @property {string} [privacyScope]    Defaults to 'private'
+ */
+
+/**
+ * @typedef {Object} ImportResult
+ * @property {number} inserted
+ * @property {number} skipped
+ * @property {Set<number>} touchedTopics
+ */
+
+export class TopicMemoryImporter {
+  /**
+   * @param {string} dbPath absolute path to topic-memory.db
+   * @param {{ readonly?: boolean, journalMode?: 'wal' | 'delete' }} [opts]
+   */
+  constructor(dbPath, opts = {}) {
+    this.db = new Database(dbPath, { readonly: opts.readonly ?? false });
+    this.db.pragma(`journal_mode = ${opts.journalMode ?? 'wal'}`);
+    this.db.pragma('busy_timeout = 5000');
+
+    this._insert = this.db.prepare(`
+      INSERT OR IGNORE INTO messages (
+        message_id, topic_id, text, from_user, timestamp,
+        session_name, sender_name, sender_username, telegram_user_id,
+        user_id, privacy_scope
+      ) VALUES (
+        @messageId, @topicId, @text, @fromUser, @timestamp,
+        @sessionName, @senderName, @senderUsername, @telegramUserId,
+        @userId, @privacyScope
+      )
+    `);
+
+    this._countByTopic = this.db.prepare(
+      `SELECT topic_id, COUNT(*) AS n FROM messages GROUP BY topic_id`,
+    );
+  }
+
+  close() {
+    this.db.close();
+  }
+
+  /**
+   * Import a batch of messages. All-or-nothing per call (wrapped in a
+   * transaction). Safe to retry — the UNIQUE(message_id, topic_id)
+   * constraint plus INSERT OR IGNORE means duplicates are silently dropped.
+   *
+   * @param {BackfillMessage[]} messages
+   * @returns {ImportResult}
+   */
+  importBatch(messages) {
+    const touched = new Set();
+    let inserted = 0;
+    let skipped = 0;
+    const tx = this.db.transaction((batch) => {
+      for (const m of batch) {
+        const row = this._insert.run({
+          messageId: m.messageId,
+          topicId: m.topicId,
+          text: m.text ?? '',
+          fromUser: m.fromUser ?? 0,
+          timestamp: m.timestamp,
+          sessionName: m.sessionName ?? null,
+          senderName: m.senderName ?? null,
+          senderUsername: m.senderUsername ?? null,
+          telegramUserId: m.telegramUserId ?? null,
+          userId: m.userId ?? null,
+          privacyScope: m.privacyScope ?? 'private',
+        });
+        if (row.changes === 1) inserted++;
+        else skipped++;
+        touched.add(m.topicId);
+      }
+    });
+    tx(messages);
+    return { inserted, skipped, touchedTopics: touched };
+  }
+
+  /**
+   * Current message counts keyed by topic_id.
+   * @returns {Map<number, number>}
+   */
+  countsByTopic() {
+    const m = new Map();
+    for (const row of this._countByTopic.all()) {
+      m.set(row.topic_id, row.n);
+    }
+    return m;
+  }
+}

package/scripts/pre-push-fixture-guard.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// safe-git-allow: pre-push critical path — must stay lightweight, no SafeGitExecutor audit-log writes from the hook.
+/**
+ * Pre-push guard: reject test-fixture commits before they ship.
+ *
+ * Git invokes pre-push hooks with GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE
+ * set in the env. When the hook runs `npm run test:smoke`, the test
+ * suite inherits those overrides, and any test that spawns `git init`
+ * + `git commit` in a tmpdir without sanitizing env ends up committing
+ * into the real repo on whichever branch is currently checked out.
+ *
+ * That's how PRs #130 and #277 picked up "Initial commit" / "seed" /
+ * "Worktree commit N" stowaways that overwrote README.md on main.
+ *
+ * Layer 1 (vitest-setup.ts strip) closes the root cause. This guard is
+ * the second line of defense: even if a future test reintroduces a raw
+ * git call without sanitizing env, the resulting commit can never reach
+ * the remote because this hook refuses to push it.
+ *
+ * Behavior:
+ *   - Scans commits on HEAD that aren't yet on origin/main.
+ *   - Fails the push if any of them match the fixture-pollution signature
+ *     (author email test@instar.local / t@t.com / t@e.com, or commit
+ *     messages "Initial commit" / "seed" / "Worktree commit <N>").
+ *   - Prints what it found so the author can `git reset` past the bad
+ *     commits and re-push.
+ *
+ * Escape hatch (for legitimate fixture commits in test-only branches
+ * that will never merge): INSTAR_PRE_PUSH_FIXTURE_GUARD_SKIP=1
+ *
+ * Exit codes: 0 = clean (or skipped), 1 = pollution detected.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+const SKIP = process.env.INSTAR_PRE_PUSH_FIXTURE_GUARD_SKIP === '1';
+if (SKIP) {
+  console.log('⏭️  INSTAR_PRE_PUSH_FIXTURE_GUARD_SKIP=1 — fixture guard bypassed.');
+  process.exit(0);
+}
+
+// Strip the same env overrides we accuse of causing the bug. Otherwise
+// our own `git log` here would be subject to the same redirection.
+const env = { ...process.env };
+delete env.GIT_DIR;
+delete env.GIT_WORK_TREE;
+delete env.GIT_INDEX_FILE;
+delete env.GIT_OBJECT_DIRECTORY;
+delete env.GIT_COMMON_DIR;
+
+function git(args) {
+  return execFileSync('git', args, { encoding: 'utf-8', env, stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+let baseRef;
+try {
+  // Prefer upstream tracking branch if one is configured.
+  baseRef = git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}']).trim();
+} catch {
+  // No upstream — fall back to whichever remote main we can resolve.
+  for (const candidate of ['upstream/main', 'origin/main']) {
+    try {
+      git(['rev-parse', '--verify', '--quiet', candidate]);
+      baseRef = candidate;
+      break;
+    } catch { /* try next */ }
+  }
+}
+
+if (!baseRef) {
+  // No remote main to compare against — likely a fresh repo. Skip silently.
+  process.exit(0);
+}
+
+// `<base>..HEAD` lists commits on HEAD that aren't on base. NUL-separated
+// records of "<sha>\t<author_email>\t<author_name>\t<subject>" — using \0
+// between records lets us survive commit messages that contain newlines.
+let log;
+try {
+  log = git([
+    'log',
+    `${baseRef}..HEAD`,
+    '--pretty=format:%H%x09%ae%x09%an%x09%s%x00',
+  ]);
+} catch (err) {
+  // Couldn't compute the range. Don't block the push — a real failure
+  // would surface elsewhere; we'd rather miss a guard than wedge pushes
+  // on every fresh repo / unborn branch.
+  process.exit(0);
+}
+
+const records = log.split('\0').map((r) => r.trim()).filter(Boolean);
+
+const BAD_EMAILS = new Set([
+  'test@instar.local',
+  't@t.com',
+  't@e.com',
+  'test@test.com',
+]);
+
+const BAD_SUBJECT_PATTERNS = [
+  /^Initial commit$/,
+  /^seed$/,
+  /^Worktree commit \d+$/,
+  /^init$/,
+];
+
+const violations = [];
+for (const record of records) {
+  const [sha, email, name, subject] = record.split('\t');
+  const reasons = [];
+  if (BAD_EMAILS.has(email)) {
+    reasons.push(`fixture-identity author <${email}>`);
+  }
+  for (const pattern of BAD_SUBJECT_PATTERNS) {
+    if (pattern.test(subject)) {
+      reasons.push(`fixture commit message "${subject}"`);
+      break;
+    }
+  }
+  if (reasons.length > 0) {
+    violations.push({ sha: sha.slice(0, 10), name, email, subject, reasons });
+  }
+}
+
+if (violations.length === 0) {
+  process.exit(0);
+}
+
+const lines = [];
+lines.push('');
+lines.push('🚫 pre-push-fixture-guard: refusing to push test-fixture commits.');
+lines.push('');
+lines.push('These commits look like test-fixture pollution (test wrote into');
+lines.push('the real repo because GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE');
+lines.push('leaked from this pre-push hook into a child test process):');
+lines.push('');
+for (const v of violations) {
+  lines.push(`  ${v.sha}  ${v.name} <${v.email}>  "${v.subject}"`);
+  for (const r of v.reasons) {
+    lines.push(`            → ${r}`);
+  }
+}
+lines.push('');
+lines.push('How to recover:');
+lines.push(`  1. Inspect the commits:  git log ${baseRef}..HEAD`);
+lines.push(`  2. Drop them:            git reset --hard <last good sha>`);
+lines.push('  3. Force-push the cleaned branch.');
+lines.push('');
+lines.push('If this is intentional (e.g. a test-only branch you do not plan');
+lines.push('to merge), bypass with INSTAR_PRE_PUSH_FIXTURE_GUARD_SKIP=1.');
+lines.push('');
+
+process.stderr.write(lines.join('\n'));
+process.exit(1);