ework-daemon 0.4.14 → 0.4.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ework-daemon",
-  "version": "0.4.14",
+  "version": "0.4.16",
   "description": "Issue-driven AI development daemon. Spawns opencode subprocesses to resolve Gitea issues.",
   "module": "src/index.ts",
   "type": "module",

package/src/opencode.ts

@@ -1,4 +1,5 @@
 import { spawn, type Subprocess } from "bun";
+import { Database } from "bun:sqlite";
 import { mkdirSync, writeFileSync, readdirSync, existsSync } from "fs";
 import { join, resolve, isAbsolute } from "path";
 import { homedir } from "os";
@@ -21,9 +22,7 @@ interface TrackerRegistry {
  * the coordination layer.
  */
 export interface TakeoverStrategy {
-  /** Resolve (and ensure exists) the workdir for this session+issue. */
-  acquireWorkdir(session: OpSession, issue: Issue): Promise<string>;
-  /** Return an opencode session id to resume, or null for a fresh session. */
+  acquireWorkdir(session: OpSession, issue: Issue, cloneUrl?: string, env?: Record<string, string>): Promise<string>;
   resumeOpenCodeSession(session: OpSession): Promise<string | null>;
 }
 
@@ -92,6 +91,68 @@ export async function runHookScript(script: string | undefined, workdir: string,
   }
 }
 
+const SYSTEM_PREFIX = "[system]";
+const RECENT_BOT_REPLY_THRESHOLD_MS = 5 * 60_000; // 5 minutes
+
+/**
+ * Determine whether any non-system bot reply exists that is causally after
+ * `promptTime` (when provided) or within a 5-minute absolute window (fallback).
+ * Exported for unit testing — the causal vs absolute distinction is the P0
+ * correctness fix for preempt/nudge false-done detection.
+ */
+export function hasRecentBotReply(
+  comments: TrackerComment[],
+  isBotUser: (author: string) => boolean,
+  promptTime?: number,
+): boolean {
+  if (promptTime) {
+    return comments.some(c => {
+      if (!isBotUser(c.author) || c.body.startsWith(SYSTEM_PREFIX)) return false;
+      if (!c.createdAt) return false;
+      return new Date(c.createdAt).getTime() > promptTime;
+    });
+  }
+  const now = Date.now();
+  return comments.some(c => {
+    if (!isBotUser(c.author) || c.body.startsWith(SYSTEM_PREFIX)) return false;
+    if (!c.createdAt) return true;
+    const age = now - new Date(c.createdAt).getTime();
+    return age < RECENT_BOT_REPLY_THRESHOLD_MS;
+  });
+}
+
+/**
+ * Query the opencode SQLite DB for a session's assistant-message output tokens.
+ * Returns `{hasOutput: true}` (safe default) when the DB can't be opened or
+ * the session is undefined — this means the retry path is only triggered when
+ * we have POSITIVE evidence of 0-token output.
+ * Exported for unit testing.
+ */
+export async function checkSessionOutput(
+  dbPath: string,
+  opencodeSessionId: string | undefined,
+): Promise<{ hasOutput: boolean; tokenCount: number }> {
+  if (!opencodeSessionId) return { hasOutput: true, tokenCount: 0 };
+  let db: Database;
+  try {
+    db = new Database(dbPath, { readonly: true });
+  } catch {
+    return { hasOutput: true, tokenCount: 0 };
+  }
+  try {
+    const row = db.prepare(
+      "SELECT COUNT(*) AS n, COALESCE(SUM(CAST(json_extract(data,'$.tokens.output') AS INT)), 0) AS tokens " +
+      "FROM message WHERE session_id = ? AND json_extract(data,'$.role') = 'assistant'"
+    ).get(opencodeSessionId) as { n: number; tokens: number } | null;
+    if (!row) return { hasOutput: true, tokenCount: 0 };
+    return { hasOutput: row.n > 0 && row.tokens > 0, tokenCount: row.tokens };
+  } catch {
+    return { hasOutput: true, tokenCount: 0 };
+  } finally {
+    db.close();
+  }
+}
+
 /**
  * Default TakeoverStrategy: deterministic per-issue workdir under
  * `<baseWorkdir>/<owner>--<repo>/<issueId>/<sessionName>`, with a best-effort
@@ -101,7 +162,7 @@ export async function runHookScript(script: string | undefined, workdir: string,
 export class RecloneStrategy implements TakeoverStrategy {
   constructor(private cfg: Config) {}
 
-  async acquireWorkdir(session: OpSession, issue: Issue): Promise<string> {
+  async acquireWorkdir(session: OpSession, issue: Issue, cloneUrl?: string, env?: Record<string, string>): Promise<string> {
     if (session.workdir) {
       let dir = session.workdir;
       if (dir.startsWith("~")) dir = join(homedir(), dir.slice(1));
@@ -122,21 +183,20 @@ export class RecloneStrategy implements TakeoverStrategy {
     try {
       const entries = readdirSync(dir);
       if (entries.length === 0) {
-        const base = this.cfg.gitea.url.replace(/\/$/, "");
-        const url = `${base}/${owner}/${repo}.git`;
-        const r = Bun.spawnSync({ cmd: ["git", "clone", url, dir], stdout: "ignore", stderr: "ignore" });
-        // git clone deletes the target dir on failure (e.g. gitea shim
-        // without smart-http /info/refs 404). Re-create the workdir so
-        // Bun.spawn later doesn't throw a misleading ENOENT pointing at the
-        // opencode binary path instead of the missing cwd. Fall back to
-        // `git init` so the workdir is at least a valid git repo the agent
-        // can work in.
+        const url = cloneUrl ?? `${this.cfg.gitea.url.replace(/\/$/, "")}/${owner}/${repo}.git`;
+        const credHelper = process.env.WORK_GIT_CREDENTIAL_HELPER;
+        const gitArgs = ["git"];
+        if (credHelper) gitArgs.push("-c", `credential.helper=${credHelper}`);
+        gitArgs.push("clone", url, dir);
+        const r = Bun.spawnSync({ cmd: gitArgs, stdout: "ignore", stderr: "pipe", env: { ...process.env, ...env } });
         if (r.exitCode !== 0) {
           if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
           if (existsSync(dir) && readdirSync(dir).length === 0) {
             Bun.spawnSync({ cmd: ["git", "init", dir], stdout: "ignore", stderr: "ignore" });
           }
-          log.warn(`acquireWorkdir: git clone failed (exit ${r.exitCode}) for ${url}; fell back to empty workdir`);
+          const stderrBuf = r.stderr as Uint8Array | undefined;
+          const stderrText = stderrBuf ? new TextDecoder().decode(stderrBuf).slice(0, 500) : "";
+          log.warn(`acquireWorkdir: git clone failed (exit ${r.exitCode}) for ${url}${stderrText ? `: ${stderrText}` : ""}; fell back to empty workdir`);
         }
       }
     } catch {
@@ -227,6 +287,7 @@ export class Engine {
   private progressCommentId = new Map<string, string>();
 
   private nudgeRounds = new Map<string, number>();
+  private emptyResponseRounds = new Map<string, number>();
   private processExitNudgeRounds = new Map<string, number>();
   private stuckNudgeRounds = new Map<string, number>();
   private currentPrompt = new Map<string, string>();
@@ -241,9 +302,12 @@ export class Engine {
   private observerTimer?: ReturnType<typeof setInterval>;
 
   private groupConfigs = new Map<string, GroupConfig>();
+  private cloneUrls = new Map<string, string>();
+  private senders = new Map<string, string>();
 
   private static MAX_INLINE_SIZE = 4000;
   private static MAX_NUDGE_ROUNDS = 1;
+  private static MAX_EMPTY_RESPONSE_ROUNDS = 1;
   private static MAX_STUCK_NUDGE_ROUNDS = 1;
   private static OBSERVER_INTERVAL_MS = 5 * 60 * 1000;
   private static STUCK_THRESHOLD_MS = 30 * 60 * 1000;
@@ -334,20 +398,35 @@ export class Engine {
       mkdirSync(dir, { recursive: true });
       return dir;
     }
-    return this.takeover.acquireWorkdir(session, issue);
+    const issueMapKey = `${issue.trackerType}:${issue.trackerScopeKey}#${issue.trackerIssueId}`;
+    const cloneUrl = this.cloneUrls.get(issueMapKey);
+    const owner = String(issue.trackerScope["owner"] ?? issue.trackerScopeKey.split("/")[0] ?? "");
+    const repo = String(issue.trackerScope["repo"] ?? issue.trackerScopeKey.split("/").slice(-1)[0] ?? "");
+    const sender = this.senders.get(issueMapKey);
+    const env: Record<string, string> = {
+      EWORK_OWNER: owner,
+      EWORK_REPO: repo,
+      EWORK_ISSUE: String(issue.trackerIssueId),
+    };
+    if (sender) env.EWORK_SENDER = sender;
+    return this.takeover.acquireWorkdir(session, issue, cloneUrl, env);
   }
 
   private hookEnvFor(issue: Issue, session: OpSession, workdir: string): Record<string, string> {
     const parts = issue.trackerScopeKey.split("/");
     const owner = (issue.trackerScope["owner"] as string) || parts[0] || "";
     const repo = (issue.trackerScope["repo"] as string) || parts[parts.length - 1] || "";
-    return {
+    const issueMapKey = `${issue.trackerType}:${issue.trackerScopeKey}#${issue.trackerIssueId}`;
+    const sender = this.senders.get(issueMapKey);
+    const env: Record<string, string> = {
       EWORK_OWNER: String(owner),
       EWORK_REPO: String(repo),
       EWORK_ISSUE: String(issue.trackerIssueId),
       EWORK_SESSION: session.name,
       EWORK_WORKDIR: workdir,
     };
+    if (sender) env.EWORK_SENDER = sender;
+    return env;
   }
 
   private workdirPathFor(session: OpSession, issue: Issue): string {
@@ -415,32 +494,26 @@ export class Engine {
     return remainMin > 0 ? `${hours}h ${remainMin}m` : `${hours}h`;
   }
 
-  /** System comments are posted by the daemon itself (acks, progress, reports). They are NOT AI replies. */
-  private static SYSTEM_PREFIX = "[system]";
-  private static RECENT_BOT_REPLY_THRESHOLD_MS = 5 * 60_000; // 5 minutes
-
   private isSystemComment(comment: TrackerComment): boolean {
-    return comment.body.startsWith(Engine.SYSTEM_PREFIX);
+    return comment.body.startsWith(SYSTEM_PREFIX);
   }
 
   private countAIReplies(comments: TrackerComment[], tracker: IssueTracker): number {
     return comments.filter(c => tracker.isBotUser(c.author) && !this.isSystemComment(c)).length;
   }
 
-  private hasRecentBotReply(comments: TrackerComment[], tracker: IssueTracker): boolean {
-    const now = Date.now();
-    return comments.some(c => {
-      if (!tracker.isBotUser(c.author) || this.isSystemComment(c)) return false;
-      if (!c.createdAt) return true; // no timestamp — assume recent to avoid false nudges
-      const age = now - new Date(c.createdAt).getTime();
-      return age < Engine.RECENT_BOT_REPLY_THRESHOLD_MS;
-    });
+  private hasRecentBotReply(comments: TrackerComment[], tracker: IssueTracker, promptTime?: number): boolean {
+    return hasRecentBotReply(comments, (a) => tracker.isBotUser(a), promptTime);
   }
 
   private lastBotReply(comments: TrackerComment[], tracker: IssueTracker): TrackerComment | undefined {
     return [...comments].reverse().find(c => tracker.isBotUser(c.author) && !this.isSystemComment(c));
   }
 
+  private async checkSessionOutput(opencodeSessionId: string | undefined): Promise<{ hasOutput: boolean; tokenCount: number }> {
+    return checkSessionOutput(this.cfg.opencode.dbPath, opencodeSessionId);
+  }
+
   // ─── Event Dispatch ───
 
   async handleEvent(event: TrackerEvent, groupConfig?: GroupConfig) {
@@ -448,8 +521,15 @@ export class Engine {
     const tracker = this.getTracker(ref.trackerType);
     const scopeKey = tracker.formatScopeKey(ref.scope);
 
+    const issueMapKey = `${ref.trackerType}:${scopeKey}#${ref.issueId}`;
     if (groupConfig) {
-      this.groupConfigs.set(`${ref.trackerType}:${scopeKey}#${ref.issueId}`, groupConfig);
+      this.groupConfigs.set(issueMapKey, groupConfig);
+    }
+    if (event.cloneUrl) {
+      this.cloneUrls.set(issueMapKey, event.cloneUrl);
+    }
+    if (event.sender) {
+      this.senders.set(issueMapKey, event.sender);
     }
 
     switch (event.type) {
@@ -689,6 +769,8 @@ export class Engine {
       }
     }
     if (this.groupConfigs.get(gcKey) === gc) this.groupConfigs.delete(gcKey);
+    this.cloneUrls.delete(gcKey);
+    this.senders.delete(gcKey);
 
     log.info(`engine: issue closed, ${sessions.length} sessions paused for ${scopeKey}#${ref.issueId}`);
   }
@@ -1005,17 +1087,21 @@ export class Engine {
       log.info(`engine: finishRun aborted (superseded) for ${k}`);
       return;
     }
-    const hasRecent = this.hasRecentBotReply(commentsNow, tracker);
+    const hasRecent = this.hasRecentBotReply(commentsNow, tracker, started ?? undefined);
 
     if (hasRecent) {
-      log.info(`engine: recent [bot] reply found for ${k}, marking done`);
+      const matched = commentsNow.find(c => tracker.isBotUser(c.author) && !this.isSystemComment(c) && c.createdAt && new Date(c.createdAt).getTime() > (started ?? 0));
+      log.info(`engine: [bot] reply found for ${k} after prompt (comment ${matched?.id ?? "?"} createdAt ${matched?.createdAt ?? "?"}), marking done`);
       this.nudgeRounds.delete(k);
+      this.emptyResponseRounds.delete(k);
       await this.persistRuntimeState(session.id);
     } else {
-      const nudgeRound = this.nudgeRounds.get(k) ?? 0;
-      if (exitCode === 0 && nudgeRound < Engine.MAX_NUDGE_ROUNDS) {
-        log.info(`engine: no recent [bot] reply for ${k}, nudging (round ${nudgeRound + 1}/${Engine.MAX_NUDGE_ROUNDS})`);
-        this.nudgeRounds.set(k, nudgeRound + 1);
+      const sessionOutput = await this.checkSessionOutput(session.opencodeSessionId);
+      const emptyRound = this.emptyResponseRounds.get(k) ?? 0;
+
+      if (!sessionOutput.hasOutput && emptyRound < Engine.MAX_EMPTY_RESPONSE_ROUNDS) {
+        log.warn(`engine: empty model response for ${k} (0 tokens, round ${emptyRound + 1}/${Engine.MAX_EMPTY_RESPONSE_ROUNDS}), retrying`);
+        this.emptyResponseRounds.set(k, emptyRound + 1);
         this.currentPrompt.delete(k);
         await this.persistRuntimeState(session.id);
 
@@ -1025,10 +1111,31 @@ export class Engine {
         await this.dequeueOrIdle(k, session, issue, nudgeMsg);
         return;
       }
-      log.info(`engine: no recent [bot] reply for ${k}, marking done (nudge exhausted or process failed)`);
-      this.nudgeRounds.delete(k);
-      const detail = exitCode === 0 ? "ran but did not post a reply" : `crashed (exit ${exitCode})`;
-      await tracker.createComment(ref, `[system] ❌ **${session.name}** ${detail}. Try posting again or @${session.name} to retry.`).catch(() => {});
+
+      if (!sessionOutput.hasOutput && emptyRound >= Engine.MAX_EMPTY_RESPONSE_ROUNDS) {
+        log.error(`engine: empty model response for ${k} after ${emptyRound} retries, reporting error`);
+        this.emptyResponseRounds.delete(k);
+        this.nudgeRounds.delete(k);
+        await tracker.createComment(ref, `[system] ❌ **${session.name}** 模型返回空响应（0 token），已重试 ${emptyRound} 次。请检查模型配置或稍后重试。`).catch(() => {});
+      } else {
+        const nudgeRound = this.nudgeRounds.get(k) ?? 0;
+        if (exitCode === 0 && nudgeRound < Engine.MAX_NUDGE_ROUNDS) {
+          log.info(`engine: no [bot] reply for ${k} (promptTime=${started ?? "unknown"}), nudging (round ${nudgeRound + 1}/${Engine.MAX_NUDGE_ROUNDS})`);
+          this.nudgeRounds.set(k, nudgeRound + 1);
+          this.currentPrompt.delete(k);
+          await this.persistRuntimeState(session.id);
+
+          const instructions = tracker.getTrackerInstructions(ref);
+          const nudgePrompt = this.buildNudgePrompt(session, issue, instructions);
+          const nudgeMsg = await this.store.createMessage(session.id, nudgePrompt, undefined, undefined, this.currentModel.get(k));
+          await this.dequeueOrIdle(k, session, issue, nudgeMsg);
+          return;
+        }
+        log.info(`engine: no [bot] reply for ${k} (promptTime=${started ?? "unknown"}), marking done (nudge exhausted or process failed)`);
+        this.nudgeRounds.delete(k);
+        const detail = exitCode === 0 ? "ran but did not post a reply" : `crashed (exit ${exitCode})`;
+        await tracker.createComment(ref, `[system] ❌ **${session.name}** ${detail}. Try posting again or @${session.name} to retry.`).catch(() => {});
+      }
     }
 
     // Remove eyes on source comment; react +1/-1 on the bot's last reply (fallback: source)
@@ -1619,5 +1726,9 @@ export class Engine {
     this.stuckNudgeRounds.clear();
     this.currentPrompt.clear();
     this.generation.clear();
+    this.groupConfigs.clear();
+    this.cloneUrls.clear();
+    this.senders.clear();
+    this.emptyResponseRounds.clear();
   }
 }

package/src/sync/engine.ts

@@ -0,0 +1,129 @@
+import type { PollingTracker, SyncExternalIssue, SyncExternalComment, TrackerRef, PollResult } from "../trackers/types";
+import { log } from "../logger";
+
+const PROVENANCE_RE = /<!--\s*sync:(\w+):([^\s:]+)(?::([^\s]+))?\s*-->/;
+
+export function withProvenance(sourceType: string, externalId: string, body: string): string {
+  const marker = `<!-- sync:${sourceType}:${externalId} -->`;
+  return body.endsWith("\n") ? `${body}${marker}` : `${body}\n${marker}`;
+}
+
+export function extractProvenance(body: string): { sourceType: string; externalId: string; commentId?: string } | null {
+  const m = body.match(PROVENANCE_RE);
+  if (!m) return null;
+  return { sourceType: m[1]!, externalId: m[2]!, commentId: m[3] };
+}
+
+export function isSyncMirrored(body: string, sourceType: string): boolean {
+  const p = extractProvenance(body);
+  return p?.sourceType === sourceType;
+}
+
+export interface SyncEngineOptions {
+  tracker: PollingTracker;
+  scope: Record<string, string>;
+  webUrl: string;
+  webToken: string;
+  owner: string;
+  repo: string;
+  pollIntervalMs: number;
+  cursorFile: string;
+  botLogin: string;
+}
+
+interface CursorState {
+  issueCursor: string | null;
+  commentCursors: Record<string, string | null>;
+  issueMap: Record<string, number>;
+}
+
+async function loadCursors(path: string): Promise<CursorState> {
+  try {
+    const f = Bun.file(path);
+    if (await f.exists()) return await f.json();
+  } catch { /* first run */ }
+  return { issueCursor: null, commentCursors: {}, issueMap: {} };
+}
+
+async function saveCursors(path: string, state: CursorState): Promise<void> {
+  try {
+    await Bun.write(path, JSON.stringify(state, null, 2));
+  } catch (e) {
+    log.warn(`sync: failed to save cursors: ${(e as Error).message}`);
+  }
+}
+
+export class SyncEngine {
+  private opts: SyncEngineOptions;
+  private running = false;
+  private timer?: ReturnType<typeof setInterval>;
+
+  constructor(opts: SyncEngineOptions) {
+    this.opts = opts;
+  }
+
+  async pollOnce(): Promise<void> {
+    const state = await loadCursors(this.opts.cursorFile);
+    const { tracker, scope, webUrl, webToken, owner, repo } = this.opts;
+
+    const issueResult: PollResult<SyncExternalIssue> = await tracker.listChangedIssues(scope, state.issueCursor);
+    for (const ext of issueResult.items) {
+      const existingLocal = state.issueMap[ext.externalId];
+      if (ext.state === "open" && !existingLocal) {
+        const body = withProvenance(tracker.type, ext.externalId, ext.body);
+        const resp = await fetch(`${webUrl}/api/v1/repos/${owner}/${repo}/issues`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json", Authorization: `token ${webToken}` },
+          body: JSON.stringify({ title: ext.title, body, assignee: ext.author }),
+        });
+        if (resp.ok) {
+          const data = await resp.json() as { number: number };
+          state.issueMap[ext.externalId] = data.number;
+          log.info(`sync: created issue #${data.number} from ${tracker.type}:${ext.externalId}`);
+        } else {
+          log.warn(`sync: create issue failed: ${resp.status} ${await resp.text()}`);
+        }
+      }
+    }
+    state.issueCursor = issueResult.nextCursor ?? state.issueCursor;
+
+    for (const [extId, issueNum] of Object.entries(state.issueMap)) {
+      const ref: TrackerRef = { trackerType: tracker.type, scope, issueId: String(issueNum) };
+      const cCursor = state.commentCursors[extId] ?? null;
+      const cResult: PollResult<SyncExternalComment> = await tracker.listChangedComments(ref, cCursor);
+      for (const c of cResult.items) {
+        if (tracker.isBotUser(c.author)) continue;
+        const body = withProvenance(tracker.type, extId, c.body);
+        const resp = await fetch(`${webUrl}/api/v1/repos/${owner}/${repo}/issues/${issueNum}/comments`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json", Authorization: `token ${webToken}` },
+          body: JSON.stringify({ body }),
+        });
+        if (resp.ok) {
+          log.info(`sync: created comment on issue #${issueNum} from ${tracker.type}:${extId}:${c.externalId}`);
+        } else {
+          log.warn(`sync: create comment failed: ${resp.status}`);
+        }
+      }
+      state.commentCursors[extId] = cResult.nextCursor ?? cCursor;
+    }
+
+    await saveCursors(this.opts.cursorFile, state);
+  }
+
+  start(): void {
+    if (this.running) return;
+    this.running = true;
+    log.info(`sync: poll loop started (interval=${this.opts.pollIntervalMs}ms, source=${this.opts.tracker.type})`);
+    this.pollOnce().catch(e => log.error(`sync: poll error: ${(e as Error).message}`));
+    this.timer = setInterval(() => {
+      this.pollOnce().catch(e => log.error(`sync: poll error: ${(e as Error).message}`));
+    }, this.opts.pollIntervalMs);
+  }
+
+  stop(): void {
+    this.running = false;
+    if (this.timer) clearInterval(this.timer);
+    log.info("sync: poll loop stopped");
+  }
+}

package/src/trackers/gitea-tracker.ts

@@ -119,6 +119,9 @@ export class GiteaTracker implements IssueTracker {
     const repoName = repository.name as string;
     if (!repoOwner || !repoName) return null;
 
+    const cloneUrl = typeof repository.clone_url === "string" ? repository.clone_url : undefined;
+    const sender = (payload.sender as Record<string, string>)?.login;
+
     // ework-web extension (non-Gitea field, ignored by strict Gitea consumers).
     // Empty/missing = no model override; engine omits --model.
     const modelRaw = repository.ework_model;
@@ -143,6 +146,8 @@ export class GiteaTracker implements IssueTracker {
           author: issueUser?.login ?? "",
         },
         model,
+        cloneUrl,
+        sender,
       };
     }
 
@@ -163,6 +168,8 @@ export class GiteaTracker implements IssueTracker {
           author: commentUser?.login ?? "",
         },
         model,
+        cloneUrl,
+        sender,
       };
     }
 
@@ -177,6 +184,8 @@ export class GiteaTracker implements IssueTracker {
           author: issueUser?.login ?? "",
         },
         model,
+        cloneUrl,
+        sender,
       };
     }
 

package/src/trackers/types.ts

@@ -33,6 +33,12 @@ export interface TrackerEvent {
   // global default). Empty/undefined = no override; engine omits --model
   // and lets opencode pick per its own opencode.json + env.
   model?: string;
+  // Real clone URL from the upstream tracker (e.g. Gitea repository.clone_url).
+  // When present, RecloneStrategy uses this instead of the ework shim URL.
+  cloneUrl?: string;
+  // Webhook sender (who triggered the event). Forwarded to the daemon's
+  // task context so the AI knows who it's responding to.
+  sender?: string;
 }
 
 /** Tracker-agnostic comment */
@@ -135,6 +141,34 @@ export interface IssueTracker {
   isBotUser(userIdentifier: string): boolean;
 }
 
+// ─── Polling Tracker (Sync Source) ───
+
+export interface SyncExternalIssue {
+  externalId: string;
+  title: string;
+  body: string;
+  state: "open" | "closed";
+  author: string;
+  updatedAt: string;
+}
+
+export interface SyncExternalComment {
+  externalId: string;
+  body: string;
+  author: string;
+  createdAt: string;
+}
+
+export interface PollResult<T> {
+  items: T[];
+  nextCursor: string | null;
+}
+
+export interface PollingTracker extends IssueTracker {
+  listChangedIssues(scope: Record<string, string>, cursor: string | null): Promise<PollResult<SyncExternalIssue>>;
+  listChangedComments(ref: TrackerRef, cursor: string | null): Promise<PollResult<SyncExternalComment>>;
+}
+
 // ─── Runtime Key Format ───
 
 /**