@holon-run/agentinbox 0.3.0 → 0.4.0

package/README.md

@@ -136,12 +136,40 @@ Create a local source and publish an event:
 agentinbox source add local_event local-demo
 agentinbox subscription add <source_id>
 agentinbox subscription add <source_id> --agent-id <agent_id>
+agentinbox source schema <source_id>
+agentinbox subscription add <source_id> --shortcut pr --shortcut-args-json '{"number":373}'
 agentinbox subscription add <source_id> --tracked-resource-ref pr:373 --cleanup-policy-json '{"mode":"manual"}'
 agentinbox subscription add <source_id> --filter-file ./filter.json
 cat filter.json | agentinbox subscription add <source_id> --filter-stdin
 agentinbox source event <source_id> --native-id demo-1 --event local.demo
 agentinbox inbox read
 agentinbox inbox read --agent-id <agent_id>
+agentinbox inbox ack --agent-id <agent_id> --through <last_item_id>
+```
+
+When acking a reviewed batch, prefer `--through <last_item_id>` over `--all`.
+That preserves the boundary of the items you actually inspected. Use
+`ack --all` only when you have intentionally verified that every current
+unacked item should be cleared.
+
+Send a direct text message into an agent inbox:
+
+```bash
+agentinbox inbox send --agent-id <agent_id> --message "Please review PR #87"
+agentinbox inbox send --agent-id <agent_id> --message "CI failed on main" --sender operator
+```
+
+Schedule reminder messages with timers:
+
+```bash
+agentinbox timer add --agent-id <agent_id> --at <RFC3339_TIMESTAMP> --message "Check the morning build"
+agentinbox timer add --agent-id <agent_id> --every 24h --message "Review today's open PRs"
+agentinbox timer add --agent-id <agent_id> --cron "0 8 * * *" --timezone Asia/Shanghai --message "Daily triage"
+agentinbox timer list
+agentinbox timer list --agent-id <agent_id>
+agentinbox timer pause <schedule_id>
+agentinbox timer resume <schedule_id>
+agentinbox timer remove <schedule_id>
 ```
 
 Update an existing source in place:
@@ -164,6 +192,16 @@ Remove a task-specific subscription without deleting the whole agent:
 agentinbox subscription remove <subscription_id>
 ```
 
+For implementation-backed sources, inspect resolved subscription capabilities
+before adding task-scoped subscriptions:
+
+```bash
+agentinbox source schema <source_id>
+```
+
+If the source advertises subscription shortcuts, prefer them over manually
+repeating the equivalent filter, tracked resource ref, and cleanup policy.
+
 ## Docs
 
 Public docs live in the mdorigin site under [`docs/site`](./docs/site).

package/dist/src/cli.js

@@ -213,6 +213,14 @@ async function main() {
         await printRemote(client, `/agents/${encodeURIComponent(agentId)}`, undefined, "DELETE");
         return;
     }
+    if (command === "agent" && normalized[1] === "resume") {
+        const agentId = normalized[2];
+        if (!agentId) {
+            throw new Error("usage: agentinbox agent resume <agentId>");
+        }
+        await printRemote(client, `/agents/${encodeURIComponent(agentId)}/resume`, {});
+        return;
+    }
     if (command === "agent" && normalized[1] === "target" && normalized[2] === "add" && normalized[3] === "webhook") {
         const agentId = normalized[4];
         const url = takeFlagValue(normalized, "--url");
@@ -243,6 +251,14 @@ async function main() {
         await printRemote(client, `/agents/${encodeURIComponent(agentId)}/targets/${encodeURIComponent(targetId)}`, undefined, "DELETE");
         return;
     }
+    if (command === "agent" && normalized[1] === "target" && normalized[2] === "resume") {
+        const [agentId, targetId] = normalized.slice(3, 5);
+        if (!agentId || !targetId) {
+            throw new Error("usage: agentinbox agent target resume <agentId> <targetId>");
+        }
+        await printRemote(client, `/agents/${encodeURIComponent(agentId)}/targets/${encodeURIComponent(targetId)}/resume`, {});
+        return;
+    }
     if (command === "subscription" && normalized[1] === "add") {
         const args = normalized.slice(2);
         const positionals = positionalArgs(args, [
@@ -905,9 +921,11 @@ Usage:
   agentinbox agent current
   agentinbox agent show <agentId>
   agentinbox agent remove <agentId>
+  agentinbox agent resume <agentId>
   agentinbox agent target add webhook <agentId> --url URL [--activation-mode MODE] [--notify-lease-ms N]
   agentinbox agent target list <agentId>
   agentinbox agent target remove <agentId> <targetId>
+  agentinbox agent target resume <agentId> <targetId>
 `,
         timer: `agentinbox timer
 

package/dist/src/daemon.js

@@ -15,6 +15,7 @@ const node_child_process_1 = require("node:child_process");
 const client_1 = require("./client");
 const paths_1 = require("./paths");
 const START_TIMEOUT_MS = 15_000;
+const PACKAGE_VERSION = readOwnPackageVersion();
 async function ensureDaemonForClient(options = {}) {
     const transport = resolveDaemonClientTransport(options);
     if (options.noAutoStart || transport.kind !== "socket") {
@@ -95,14 +96,23 @@ async function daemonStatus(options = {}) {
         return {
             running: false,
             pid: null,
+            version: null,
+            startedAt: null,
+            command: null,
+            nodeVersion: null,
             pidPath,
             logPath,
             transport,
         };
     }
+    const processInfo = pid == null ? null : readProcessMetadata(pid);
     return {
         running: await canReachHealthz(transport),
         pid,
+        version: pid == null ? null : PACKAGE_VERSION,
+        startedAt: processInfo?.startedAt ?? null,
+        command: processInfo?.command ?? null,
+        nodeVersion: processInfo?.nodeVersion ?? null,
         pidPath,
         logPath,
         transport,
@@ -179,6 +189,24 @@ async function canReachHealthz(transport) {
         return false;
     }
 }
+function readOwnPackageVersion() {
+    const candidatePaths = [
+        node_path_1.default.join(__dirname, "..", "package.json"),
+        node_path_1.default.join(__dirname, "..", "..", "package.json"),
+    ];
+    for (const candidate of candidatePaths) {
+        try {
+            const parsed = JSON.parse(node_fs_1.default.readFileSync(candidate, "utf8"));
+            if (typeof parsed.version === "string" && parsed.version.length > 0) {
+                return parsed.version;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
 async function waitForHealthz(transport, timeoutMs) {
     const startedAt = Date.now();
     while (Date.now() - startedAt < timeoutMs) {
@@ -222,6 +250,47 @@ function readPidFile(pidPath) {
         return null;
     }
 }
+function readProcessMetadata(pid) {
+    try {
+        const output = (0, node_child_process_1.execFileSync)("ps", ["-o", "lstart=", "-o", "command=", "-p", String(pid)], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trimEnd();
+        if (!output) {
+            return null;
+        }
+        const firstNonSpace = output.search(/\S/);
+        if (firstNonSpace < 0) {
+            return null;
+        }
+        const trimmed = output.slice(firstNonSpace);
+        const match = trimmed.match(/^([A-Z][a-z]{2}\s+[A-Z][a-z]{2}\s+\d{1,2}\s+\d\d:\d\d:\d\d\s+\d{4})\s+(.*)$/);
+        if (!match) {
+            return {
+                startedAt: null,
+                command: trimmed,
+                nodeVersion: inferNodeVersionFromCommand(trimmed),
+            };
+        }
+        const [, startedAtRaw, command] = match;
+        const startedAtMs = Date.parse(startedAtRaw);
+        return {
+            startedAt: Number.isNaN(startedAtMs) ? null : new Date(startedAtMs).toISOString(),
+            command: command || null,
+            nodeVersion: inferNodeVersionFromCommand(command),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function inferNodeVersionFromCommand(command) {
+    if (!command) {
+        return null;
+    }
+    const match = command.match(/node\/(v\d+\.\d+\.\d+)\//);
+    return match ? match[1] : null;
+}
 function isProcessAlive(pid) {
     try {
         process.kill(pid, 0);

package/dist/src/http.js

@@ -487,6 +487,24 @@ function buildFastifyServer(service) {
         const params = request.params;
         return service.removeAgent(decodeURIComponent(params.agentId));
     });
+    app.post("/agents/:agentId/resume", {
+        schema: {
+            tags: ["agents"],
+            params: {
+                type: "object",
+                required: ["agentId"],
+                properties: {
+                    agentId: { type: "string", minLength: 1 },
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        return service.resumeAgent(decodeURIComponent(params.agentId));
+    });
     app.get("/agents/:agentId/targets", {
         schema: {
             tags: ["agents"],
@@ -565,6 +583,25 @@ function buildFastifyServer(service) {
         const params = request.params;
         return service.removeActivationTarget(decodeURIComponent(params.agentId), decodeURIComponent(params.targetId));
     });
+    app.post("/agents/:agentId/targets/:targetId/resume", {
+        schema: {
+            tags: ["agents"],
+            params: {
+                type: "object",
+                required: ["agentId", "targetId"],
+                properties: {
+                    agentId: { type: "string", minLength: 1 },
+                    targetId: { type: "string", minLength: 1 },
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        return service.resumeActivationTarget(decodeURIComponent(params.agentId), decodeURIComponent(params.targetId));
+    });
     app.get("/timers", {
         schema: {
             tags: ["timers"],

package/dist/src/runtime_gate.js

@@ -3,7 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ClaudeCodeTerminalStateProbe = exports.ClaudeCodeRuntimePresenceProbe = exports.TmuxTerminalStateProbe = exports.Iterm2TerminalStateProbe = exports.CodexRuntimePresenceProbe = exports.DefaultActivationGate = void 0;
+exports.ClaudeCodeTerminalStateProbe = exports.ClaudeCodeRuntimePresenceProbe = exports.TmuxTerminalStateProbe = exports.Iterm2TerminalStateProbe = exports.CodexTerminalStateProbe = exports.CodexRuntimePresenceProbe = exports.DefaultActivationGate = void 0;
+exports.readFirstLine = readFirstLine;
 const node_child_process_1 = require("node:child_process");
 const node_util_1 = require("node:util");
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -28,6 +29,7 @@ class DefaultActivationGate {
         new CodexRuntimePresenceProbe(),
         new ClaudeCodeRuntimePresenceProbe(),
     ], terminalProbes = [
+        new CodexTerminalStateProbe(),
         new Iterm2TerminalStateProbe(),
         new ClaudeCodeTerminalStateProbe(),
         new TmuxTerminalStateProbe(),
@@ -38,27 +40,32 @@ class DefaultActivationGate {
     async evaluate(target) {
         const runtimeProbe = this.runtimeProbes.find((probe) => probe.supports(target));
         const runtimePresence = runtimeProbe ? await runtimeProbe.check(target) : "unknown";
+        if (runtimePresence === "gone") {
+            return { outcome: "offline", reason: "runtime_gone" };
+        }
         const terminalProbe = this.terminalProbes.find((probe) => probe.supports(target));
         const terminalState = terminalProbe
             ? await terminalProbe.check(target)
             : { presence: "unknown", busy: "unknown" };
-        if (runtimePresence === "gone") {
-            return { outcome: "offline", reason: "runtime_gone" };
-        }
         if (terminalState.presence === "gone") {
             return { outcome: "offline", reason: "terminal_gone" };
         }
         if (terminalState.busy === "busy") {
             return { outcome: "defer", reason: "terminal_busy" };
         }
+        if (target.runtimeKind === "codex" && terminalState.busy === "idle") {
+            return { outcome: "defer", reason: "terminal_recently_active" };
+        }
         return { outcome: "inject", reason: "gate_unknown_or_idle" };
     }
 }
 exports.DefaultActivationGate = DefaultActivationGate;
 class CodexRuntimePresenceProbe {
     killFn;
-    constructor(killFn = (pid, signal) => process.kill(pid, signal)) {
+    sessionFileReader;
+    constructor(killFn = (pid, signal) => process.kill(pid, signal), sessionFileReader) {
         this.killFn = killFn;
+        this.sessionFileReader = sessionFileReader;
     }
     supports(target) {
         return target.runtimeKind === "codex" && Number.isInteger(target.runtimePid);
@@ -69,6 +76,16 @@ class CodexRuntimePresenceProbe {
         }
         try {
             this.killFn(target.runtimePid, 0);
+            if (!target.runtimeSessionId) {
+                return "unknown";
+            }
+            const sessionInfo = await (this.sessionFileReader ?? defaultCodexSessionFileReader)(target.runtimeSessionId);
+            if (sessionInfo === "unknown") {
+                return "unknown";
+            }
+            if (!sessionInfo || sessionInfo.sessionId !== target.runtimeSessionId) {
+                return "gone";
+            }
             return "alive";
         }
         catch (error) {
@@ -81,6 +98,58 @@ class CodexRuntimePresenceProbe {
     }
 }
 exports.CodexRuntimePresenceProbe = CodexRuntimePresenceProbe;
+class CodexTerminalStateProbe {
+    iTermProbe;
+    tmuxProbe;
+    sessionFileReader;
+    statReader;
+    nowFn;
+    constructor(iTermProbe = new Iterm2TerminalStateProbe(), tmuxProbe = new TmuxTerminalStateProbe(), sessionFileReader, statReader, nowFn = () => Date.now()) {
+        this.iTermProbe = iTermProbe;
+        this.tmuxProbe = tmuxProbe;
+        this.sessionFileReader = sessionFileReader;
+        this.statReader = statReader;
+        this.nowFn = nowFn;
+    }
+    supports(target) {
+        return target.runtimeKind === "codex";
+    }
+    async check(target) {
+        const terminalState = await this.readTerminalState(target);
+        if (!target.runtimeSessionId) {
+            return terminalState;
+        }
+        const sessionInfo = await (this.sessionFileReader ?? defaultCodexSessionFileReader)(target.runtimeSessionId);
+        if (sessionInfo === "unknown" || !sessionInfo || sessionInfo.sessionId !== target.runtimeSessionId) {
+            return terminalState;
+        }
+        const stat = await (this.statReader ?? defaultFileStatReader)(sessionInfo.filePath);
+        if (!stat) {
+            return terminalState;
+        }
+        if (terminalState.busy === "busy" || terminalState.presence === "gone") {
+            return terminalState;
+        }
+        const ageMs = this.nowFn() - stat.mtimeMs;
+        if (ageMs < 5000) {
+            return { presence: terminalState.presence, busy: "busy" };
+        }
+        if (ageMs < 30000) {
+            return { presence: terminalState.presence, busy: "idle" };
+        }
+        return terminalState;
+    }
+    async readTerminalState(target) {
+        if (this.iTermProbe.supports(target)) {
+            return this.iTermProbe.check(target);
+        }
+        if (this.tmuxProbe.supports(target)) {
+            return this.tmuxProbe.check(target);
+        }
+        return { presence: "unknown", busy: "unknown" };
+    }
+}
+exports.CodexTerminalStateProbe = CodexTerminalStateProbe;
 class Iterm2TerminalStateProbe {
     execAsync;
     options;
@@ -128,16 +197,16 @@ class Iterm2TerminalStateProbe {
         if (containsActiveBufferMarker(second)) {
             return { presence: "available", busy: "busy" };
         }
+        if (hasVisibleTypingPrompt(second)) {
+            return { presence: "available", busy: "busy" };
+        }
         return { presence: "available", busy: "unknown" };
     }
     async checkSessionPresence(it2api, sessionId) {
         try {
             const result = await this.execAsync(it2api, ["list-sessions"]);
-            const sessions = result.stdout
-                .split(/\r?\n/)
-                .map((line) => line.trim())
-                .filter((line) => line.length > 0);
-            return sessions.includes(sessionId) ? "available" : "gone";
+            const sessionIds = parseIterm2SessionIds(result.stdout);
+            return sessionIds.includes(sessionId) ? "available" : "gone";
         }
         catch {
             return "unknown";
@@ -284,6 +353,114 @@ function resolveIterm2ApiPath(override) {
 async function sleep(ms) {
     await new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function defaultFileStatReader(filePath) {
+    try {
+        const stats = await node_fs_1.default.promises.stat(filePath);
+        return { mtimeMs: stats.mtimeMs };
+    }
+    catch {
+        return null;
+    }
+}
+async function defaultCodexSessionFileReader(sessionId) {
+    const sessionsRoot = node_path_1.default.join(node_os_1.default.homedir(), ".codex", "sessions");
+    const filePath = await findCodexSessionFile(sessionsRoot, sessionId).catch(() => "unknown");
+    if (filePath === "unknown") {
+        return "unknown";
+    }
+    if (!filePath) {
+        return null;
+    }
+    try {
+        const firstLine = await readFirstLine(filePath);
+        if (!firstLine) {
+            return "unknown";
+        }
+        const record = JSON.parse(firstLine);
+        const parsedSessionId = typeof record.payload?.id === "string" ? record.payload.id : null;
+        if (record.type !== "session_meta" || parsedSessionId !== sessionId) {
+            return "unknown";
+        }
+        return {
+            sessionId: parsedSessionId,
+            filePath,
+            cwd: typeof record.payload?.cwd === "string" ? record.payload.cwd : null,
+        };
+    }
+    catch {
+        return "unknown";
+    }
+}
+async function findCodexSessionFile(root, sessionId) {
+    let years;
+    try {
+        years = await node_fs_1.default.promises.readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    for (const year of years) {
+        if (!year.isDirectory()) {
+            continue;
+        }
+        const yearPath = node_path_1.default.join(root, year.name);
+        const match = await walkCodexSessionLevel(yearPath, sessionId, 2);
+        if (match) {
+            return match;
+        }
+    }
+    return null;
+}
+async function walkCodexSessionLevel(dir, sessionId, depth) {
+    let entries;
+    try {
+        entries = await node_fs_1.default.promises.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    for (const entry of entries) {
+        const entryPath = node_path_1.default.join(dir, entry.name);
+        if (entry.isFile() && entry.name.endsWith(`${sessionId}.jsonl`)) {
+            return entryPath;
+        }
+        if (entry.isDirectory() && depth > 0) {
+            const match = await walkCodexSessionLevel(entryPath, sessionId, depth - 1);
+            if (match) {
+                return match;
+            }
+        }
+    }
+    return null;
+}
+async function readFirstLine(filePath) {
+    const handle = await node_fs_1.default.promises.open(filePath, "r");
+    try {
+        const chunkSize = 4096;
+        const chunks = [];
+        let position = 0;
+        while (true) {
+            const buffer = Buffer.alloc(chunkSize);
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+            if (bytesRead <= 0) {
+                break;
+            }
+            const chunk = buffer.toString("utf8", 0, bytesRead);
+            const newline = chunk.indexOf("\n");
+            if (newline >= 0) {
+                chunks.push(chunk.slice(0, newline));
+                break;
+            }
+            chunks.push(chunk);
+            position += bytesRead;
+        }
+        const firstLine = chunks.join("").trim();
+        return firstLine.length > 0 ? firstLine : null;
+    }
+    finally {
+        await handle.close();
+    }
+}
 function isTmuxMissingPaneError(error) {
     if (!(error instanceof Error)) {
         return false;
@@ -446,14 +623,7 @@ class ClaudeCodeTerminalStateProbe {
         try {
             const it2api = resolveIterm2ApiPath();
             const result = await execFileAsync(it2api, ["list-sessions"]);
-            const lines = result.stdout.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
-            // Parse session IDs from iTerm2 output format: "Session \"...\" id=<UUID> ..."
-            const sessionIds = lines
-                .map((line) => {
-                const match = line.match(/id=([A-F0-9-]+)/);
-                return match ? match[1] : null;
-            })
-                .filter((id) => id !== null);
+            const sessionIds = parseIterm2SessionIds(result.stdout);
             return sessionIds.includes(itermSessionId) ? "available" : "gone";
         }
         catch {
@@ -462,3 +632,14 @@ class ClaudeCodeTerminalStateProbe {
     }
 }
 exports.ClaudeCodeTerminalStateProbe = ClaudeCodeTerminalStateProbe;
+function parseIterm2SessionIds(stdout) {
+    return stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => {
+        const match = line.match(/\bid=([A-F0-9-]+)/i);
+        return match ? match[1] : null;
+    })
+        .filter((id) => id !== null);
+}

package/dist/src/service.js

@@ -531,6 +531,57 @@ class AgentInboxService {
         this.reconcileAgentStatus(agentId);
         return { removed: true };
     }
+    async resumeAgent(agentId) {
+        this.getAgent(agentId);
+        const targets = this.store.listActivationTargetsForAgent(agentId);
+        const results = [];
+        for (const target of targets) {
+            results.push(await this.resumeActivationTarget(agentId, target.targetId));
+        }
+        this.reconcileAgentStatus(agentId);
+        return {
+            resumed: results.some((result) => result.resumed),
+            agent: this.getAgent(agentId),
+            targets: results,
+        };
+    }
+    async resumeActivationTarget(agentId, targetId) {
+        const target = this.getActivationTarget(targetId);
+        if (target.agentId !== agentId) {
+            throw new Error(`activation target ${targetId} does not belong to agent ${agentId}`);
+        }
+        if (target.status === "active") {
+            return {
+                targetId: target.targetId,
+                resumed: false,
+                status: target.status,
+                reason: "already_active",
+            };
+        }
+        let result;
+        if (target.kind === "terminal") {
+            result = await this.resumeTerminalActivationTarget(target);
+        }
+        else {
+            const now = (0, util_1.nowIso)();
+            this.store.updateActivationTargetRuntime(target.targetId, {
+                status: "active",
+                offlineSince: null,
+                consecutiveFailures: 0,
+                lastError: null,
+                updatedAt: now,
+                lastSeenAt: now,
+            });
+            result = {
+                targetId: target.targetId,
+                resumed: true,
+                status: "active",
+                reason: "webhook_resumed",
+            };
+        }
+        this.reconcileAgentStatus(agentId);
+        return result;
+    }
     async registerSubscription(input) {
         if (input.shortcut) {
             const source = this.store.getSource(input.sourceId);
@@ -1355,10 +1406,12 @@ class AgentInboxService {
         try {
             const state = this.store.getActivationDispatchState(buffer.agentId, buffer.targetId);
             if (!state) {
+                const inbox = this.ensureInboxForAgent(buffer.agentId);
                 const dispatched = await this.dispatchActivationTarget({
                     agentId: buffer.agentId,
                     targetId: buffer.targetId,
                     newItemCount: entries.length,
+                    totalUnackedCount: this.store.countInboxItems(inbox.inboxId, false),
                     summary: entries[0]?.summary ?? null,
                     subscriptionIds: uniqueSortedNullable(entries.map((entry) => entry.subscriptionId)),
                     sourceIds: uniqueSorted(entries.map((entry) => entry.sourceId)),
@@ -1428,6 +1481,7 @@ class AgentInboxService {
             agentId,
             targetId,
             newItemCount: state.pendingNewItemCount > 0 ? state.pendingNewItemCount : unacked,
+            totalUnackedCount: unacked,
             summary: state.pendingSummary,
             subscriptionIds: state.pendingSubscriptionIds,
             sourceIds: state.pendingSourceIds,
@@ -1463,6 +1517,7 @@ class AgentInboxService {
         }
         const inbox = this.ensureInboxForAgent(input.agentId);
         const summary = summarizeActivation(inbox.inboxId, input.newItemCount, input.summary);
+        const totalUnackedCount = input.totalUnackedCount ?? this.store.countInboxItems(inbox.inboxId, false);
         try {
             if (target.kind === "terminal") {
                 const gate = await this.activationGate.evaluate(target);
@@ -1487,7 +1542,7 @@ class AgentInboxService {
                 }
                 const prompt = (0, terminal_1.renderAgentPrompt)({
                     inboxId: inbox.inboxId,
-                    newItemCount: input.newItemCount,
+                    totalUnackedCount,
                     summary: input.summary,
                 });
                 await this.terminalDispatcher.dispatch(target, prompt);
@@ -1644,6 +1699,46 @@ class AgentInboxService {
             lastSeenAt: agent.lastSeenAt,
         });
     }
+    async resumeTerminalActivationTarget(target) {
+        const probeStatus = await this.terminalDispatcher.probeStatus(target);
+        const now = (0, util_1.nowIso)();
+        if (probeStatus === "available") {
+            this.store.updateActivationTargetRuntime(target.targetId, {
+                status: "active",
+                offlineSince: null,
+                consecutiveFailures: 0,
+                lastError: null,
+                updatedAt: now,
+                lastSeenAt: now,
+            });
+            return {
+                targetId: target.targetId,
+                resumed: true,
+                status: "active",
+                reason: "terminal_available",
+            };
+        }
+        if (probeStatus === "gone") {
+            this.store.updateActivationTargetRuntime(target.targetId, {
+                status: "offline",
+                offlineSince: target.offlineSince ?? now,
+                updatedAt: now,
+                lastError: target.lastError ?? "terminal gone",
+            });
+            return {
+                targetId: target.targetId,
+                resumed: false,
+                status: "offline",
+                reason: "terminal_gone",
+            };
+        }
+        return {
+            targetId: target.targetId,
+            resumed: false,
+            status: "offline",
+            reason: "probe_unknown",
+        };
+    }
     runLifecycleCleanupPass(nowMs) {
         this.lastLifecycleCleanupAt = nowMs;
         const removed = new Set();

package/dist/src/terminal.js

@@ -46,7 +46,9 @@ function detectTerminalContext(env = process.env) {
     throw new Error("unable to detect a supported terminal context");
 }
 function renderAgentPrompt(input) {
-    const base = `AgentInbox: ${input.newItemCount} new items arrived in inbox ${input.inboxId}.`;
+    const totalUnackedCount = input.totalUnackedCount ?? input.newItemCount ?? 0;
+    const itemWord = totalUnackedCount === 1 ? "item" : "items";
+    const base = `AgentInbox: ${totalUnackedCount} unacked ${itemWord} in inbox ${input.inboxId}.`;
     if (input.summary) {
         return `${base} Summary: ${input.summary}. Please read the inbox, process them, and ack when finished.`;
     }
@@ -90,31 +92,44 @@ class TerminalDispatcher {
         throw new Error(`unsupported terminal backend: ${String(target.backend)}`);
     }
     async probe(target) {
+        return (await this.probeStatus(target)) === "available";
+    }
+    async probeStatus(target) {
         try {
             if (target.backend === "tmux") {
                 if (!target.tmuxPaneId) {
-                    return false;
+                    return "unknown";
                 }
                 const result = await this.execAsync("tmux", ["display-message", "-p", "-t", target.tmuxPaneId, "#{pane_id}"]);
-                return result.stdout.trim() === target.tmuxPaneId;
+                return result.stdout.trim() === target.tmuxPaneId ? "available" : "gone";
             }
             if (target.backend === "iterm2") {
                 const sessionId = normalizeOptionalString(target.itermSessionId);
                 if (!sessionId) {
-                    return false;
+                    return "unknown";
                 }
                 const it2api = resolveIterm2ApiPath(this.options.iterm2ApiPath);
                 const result = await this.execAsync(it2api, ["list-sessions"]);
-                return result.stdout.includes(sessionId);
+                return result.stdout.includes(sessionId) ? "available" : "gone";
             }
         }
-        catch {
-            return false;
+        catch (error) {
+            if (target.backend === "tmux" && isTmuxMissingPaneError(error)) {
+                return "gone";
+            }
+            return "unknown";
         }
-        return false;
+        return "unknown";
     }
 }
 exports.TerminalDispatcher = TerminalDispatcher;
+function isTmuxMissingPaneError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const candidate = `${error.message} ${"stderr" in error ? String(error.stderr ?? "") : ""}`;
+    return candidate.includes("can't find pane");
+}
 function detectTty(env) {
     const direct = tryReadCurrentTty();
     if (direct) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holon-run/agentinbox",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Local event subscription and delivery service for agents.",
   "license": "Apache-2.0",
   "repository": {