backeer-opencode 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to `backeer-opencode` are documented here.
 
+## 0.2.0 - 2026-09-01
+
+- Notify when an OpenCode assistant run completes successfully.
+- Notify terminal session errors with redacted diagnostic summaries.
+- Warn once when a session reaches its third retry attempt.
+- Notify once per version when an OpenCode update is available.
+- Add granular lifecycle configuration and lifecycle state to `/backeer status`.
+- Use stable lifecycle event IDs and the completion sound for successful runs.
+
 ## 0.1.5 - 2026-09-01
 
 - Check the NPM registry for a newer Backeer plugin version once per day.

package/README.md

@@ -1,10 +1,11 @@
 # Backeer for OpenCode
 
 `backeer-opencode` connects OpenCode to Backeer. It sends mobile notifications
-for permission requests, questions, and completed todo lists. While a permission
-is pending, it also consumes an authenticated Backeer command stream so an
-authorized user can answer **Allow once**, **Always allow**, or **Reject** from
-the Backeer iOS application.
+for permission requests, questions, completed todo lists, completed assistant
+runs, session failures, prolonged retries, and OpenCode updates. While a
+permission is pending, it also consumes an authenticated Backeer command stream
+so an authorized user can answer **Allow once**, **Always allow**, or **Reject**
+from the Backeer iOS application.
 
 The plugin uses outbound HTTPS only. It does not start a server or require an
 inbound firewall rule.
@@ -109,6 +110,13 @@ environment variables are supported:
 | `BACKEER_NOTIFY_PERMISSIONS` | Set to `false` to disable permission notifications and remote replies |
 | `BACKEER_NOTIFY_QUESTIONS` | Set to `false` to disable question notifications |
 | `BACKEER_NOTIFY_TODOS` | Set to `false` to disable todo-completion notifications |
+| `BACKEER_NOTIFY_LIFECYCLE` | Set to `false` to disable every lifecycle notification |
+| `BACKEER_NOTIFY_SESSION_COMPLETED` | Set to `false` to disable successful-run notifications |
+| `BACKEER_NOTIFY_SESSION_ERRORS` | Set to `false` to disable session-error notifications |
+| `BACKEER_NOTIFY_SESSION_RETRIES` | Set to `false` to disable retry warnings |
+| `BACKEER_NOTIFY_OPENCODE_UPDATES` | Set to `false` to disable OpenCode update notifications |
+| `BACKEER_SESSION_COMPLETION_MIN_SECONDS` | Minimum run duration; defaults to `0` (every completion) |
+| `BACKEER_RETRY_ATTEMPT_THRESHOLD` | First retry attempt that triggers a warning; defaults to `3` |
 | `BACKEER_LOG_LEVEL` | `info` (default), `error`, `debug`, or `silent` |
 
 For npm installations, non-secret options can also be supplied through the
@@ -122,7 +130,16 @@ OpenCode plugin tuple syntax:
       {
         "permissions": true,
         "questions": true,
-        "todos": true
+        "todos": true,
+        "lifecycle": {
+          "enabled": true,
+          "completed": true,
+          "errors": true,
+          "retries": true,
+          "updates": true,
+          "completionMinSeconds": 0,
+          "retryAttemptThreshold": 3
+        }
       }
     ]
   ]
@@ -130,7 +147,8 @@ OpenCode plugin tuple syntax:
 ```
 
 Supported options are `origin`, `tokenFile`, `permissions`, `questions`,
-`todos`, and `logLevel`. The token itself is deliberately not a plugin option.
+`todos`, `lifecycle`, and `logLevel`. Use `"lifecycle": false` to disable the
+entire lifecycle group. The token itself is deliberately not a plugin option.
 
 ## Console feedback
 
@@ -140,6 +158,9 @@ The plugin writes compact, single-line status messages instead of raw HTTP logs:
 ◆ Backeer  Permission request sent
 ◆ Backeer  Question sent
 ◆ Backeer  Todo completion sent
+◆ Backeer  Task completion sent
+◆ Backeer  Retry warning sent
+◆ Backeer  Task failure sent
 ✓ Backeer  Decision applied: Always allow
 ! Backeer  Connection interrupted — retrying
 ```
@@ -163,9 +184,9 @@ The plugin registers a `/backeer` command inside OpenCode:
 ```
 
 The status report shows the plugin version, gateway reachability, token source,
-notification switches, command-stream state, pending permissions, and log level.
-It never displays the token. Gateway reachability does not validate the source
-credential.
+notification switches and lifecycle thresholds, command-stream state, pending
+permissions, and log level. It never displays the token. Gateway reachability
+does not validate the source credential.
 
 `/backeer token` displays safe rotation instructions. Never paste a raw token
 into slash-command arguments because OpenCode may retain command text in session
@@ -198,6 +219,21 @@ The plugin publishes:
 | `question.asked` | Notification-only question card |
 | `question.v2.asked` | Notification-only question card, including plan-mode questions |
 | `todo.updated` | One notification when a non-empty list transitions to fully completed |
+| `message.updated` + `session.status`/`session.idle` | One notification for each successfully completed assistant run |
+| `session.error` | Critical failure notification with a redacted error summary |
+| `session.status` (`retry`) | One warning when the configured retry threshold is reached |
+| `installation.update-available` | One notification per available OpenCode version |
+
+Completion requires a completed, error-free assistant message in the current
+busy cycle. An idle event caused by a pending permission or question is not
+reported as successful. Repeated idle callbacks, retry callbacks, error events,
+and update events use stable correlation IDs so they do not create duplicate
+push notifications.
+
+Lifecycle payloads intentionally omit command arguments, model output, file
+paths and diffs, stack traces, HTTP response bodies, and response headers. Error
+messages are length-limited and redact common credentials, URL queries, and
+filesystem paths before leaving the OpenCode host.
 
 Permission commands are delivered at least once. The plugin caches terminal
 acknowledgements and resends the same acknowledgement on redelivery without

package/dist/backeer-permission.js

@@ -77,6 +77,43 @@ function createConsoleReporter(levelValue) {
 
 // src/config.js
 var DEFAULT_ORIGIN = "https://external-gateway.backeer.com";
+function integer(value, fallback, { minimum = 0, maximum = 86400 } = {}) {
+  if (value === void 0 || value === null || value === "") return fallback;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < minimum || parsed > maximum) {
+    throw new Error(`Expected an integer between ${minimum} and ${maximum}`);
+  }
+  return parsed;
+}
+function loadLifecycleConfig(option) {
+  const values = option && typeof option === "object" ? option : {};
+  const masterValue = typeof option === "boolean" ? option : values.enabled ?? process.env.BACKEER_NOTIFY_LIFECYCLE;
+  const masterEnabled = enabled(masterValue);
+  return {
+    enabled: masterEnabled,
+    completed: masterEnabled && enabled(
+      values.completed ?? process.env.BACKEER_NOTIFY_SESSION_COMPLETED
+    ),
+    errors: masterEnabled && enabled(
+      values.errors ?? process.env.BACKEER_NOTIFY_SESSION_ERRORS
+    ),
+    retries: masterEnabled && enabled(
+      values.retries ?? process.env.BACKEER_NOTIFY_SESSION_RETRIES
+    ),
+    updates: masterEnabled && enabled(
+      values.updates ?? process.env.BACKEER_NOTIFY_OPENCODE_UPDATES
+    ),
+    completionMinSeconds: integer(
+      values.completionMinSeconds ?? process.env.BACKEER_SESSION_COMPLETION_MIN_SECONDS,
+      0
+    ),
+    retryAttemptThreshold: integer(
+      values.retryAttemptThreshold ?? process.env.BACKEER_RETRY_ATTEMPT_THRESHOLD,
+      3,
+      { minimum: 1, maximum: 100 }
+    )
+  };
+}
 function defaultConfigDirectory() {
   const base = process.env.XDG_CONFIG_HOME?.trim();
   return base ? join(base, "opencode") : join(homedir(), ".config", "opencode");
@@ -114,6 +151,7 @@ function loadConfig(options = {}) {
       options.questions ?? process.env.BACKEER_NOTIFY_QUESTIONS
     ),
     todos: enabled(options.todos ?? process.env.BACKEER_NOTIFY_TODOS),
+    lifecycle: loadLifecycleConfig(options.lifecycle),
     logLevel: normalizeLogLevel(
       options.logLevel ?? process.env.BACKEER_LOG_LEVEL
     )
@@ -359,7 +397,7 @@ import {
 import { dirname, resolve } from "node:path";
 
 // src/updates.js
-var PLUGIN_VERSION = "0.1.5";
+var PLUGIN_VERSION = "0.2.0";
 var PACKAGE_NAME = "backeer-opencode";
 var NPM_REGISTRY_URL = "https://registry.npmjs.org";
 var CHECK_TIMEOUT_MS = 3e3;
@@ -564,6 +602,11 @@ async function buildStatus(config, permissionController, updateChecker) {
     `- Permission notifications: ${config.permissions ? "enabled" : "disabled"}`,
     `- Question notifications: ${config.questions ? "enabled" : "disabled"}`,
     `- Todo notifications: ${config.todos ? "enabled" : "disabled"}`,
+    `- Lifecycle notifications: ${config.lifecycle.enabled ? "enabled" : "disabled"}`,
+    `  - Completed sessions: ${config.lifecycle.completed ? "enabled" : "disabled"} (minimum ${config.lifecycle.completionMinSeconds}s)`,
+    `  - Session errors: ${config.lifecycle.errors ? "enabled" : "disabled"}`,
+    `  - Retry warnings: ${config.lifecycle.retries ? "enabled" : "disabled"} (attempt ${config.lifecycle.retryAttemptThreshold}+)`,
+    `  - OpenCode updates: ${config.lifecycle.updates ? "enabled" : "disabled"}`,
     `- Command stream: ${permissionStatus.stream}`,
     `- Pending permissions: ${permissionStatus.pending}`,
     `- Log level: ${config.logLevel}`,
@@ -684,6 +727,342 @@ Backeer is already current at version ${update.currentVersion}.` : "## Backeer u
   };
 }
 
+// src/lifecycle-publishers.js
+var CONTROL_CHARACTERS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g;
+var SECRET_ASSIGNMENT = /\b(token|secret|password|api[-_ ]?key)\s*[:=]\s*[^\s,;]+/gi;
+var BEARER_TOKEN = /\bBearer\s+[^\s,;]+/gi;
+var URL_WITH_QUERY = /\bhttps?:\/\/[^\s?#]+(?:\?[^\s#]*)?(?:#[^\s]*)?/gi;
+var WINDOWS_PATH = /\b[A-Za-z]:\\(?:[^\\\s]+\\)+[^\s]*/g;
+var POSIX_PATH = /(^|\s)\/(?:[^/\s]+\/)+[^\s]*/g;
+function sanitizeErrorMessage(value) {
+  return limit(value, 2e3).replace(CONTROL_CHARACTERS, " ").replace(BEARER_TOKEN, "Bearer [redacted]").replace(SECRET_ASSIGNMENT, "$1=[redacted]").replace(URL_WITH_QUERY, (value2) => {
+    try {
+      const url = new URL(value2);
+      return `${url.origin}${url.pathname}`;
+    } catch {
+      return "[url redacted]";
+    }
+  }).replace(WINDOWS_PATH, "[path redacted]").replace(POSIX_PATH, "$1[path redacted]").replace(/\s+/g, " ").trim().slice(0, 500);
+}
+function safeErrorDetails(error) {
+  const name = limit(error?.name || "OpenCodeError", 100);
+  const message = sanitizeErrorMessage(error?.data?.message ?? error?.message);
+  const statusCode = Number.isInteger(error?.data?.statusCode) ? String(error.data.statusCode) : "";
+  return { name, message, statusCode };
+}
+async function resolveSessionTitle2(client, directory, sessionID, reporter) {
+  if (!sessionID || typeof client?.session?.get !== "function") return "";
+  try {
+    const result = await client.session.get({
+      path: { id: sessionID },
+      query: { directory },
+      throwOnError: true
+    });
+    return limit((result?.data ?? result)?.title);
+  } catch (error) {
+    reporter.debug("Session title unavailable", error);
+    return "";
+  }
+}
+async function publish(config, reporter, event, feedback) {
+  const result = await postJsonWithRetry(config, config.eventsEndpoint, {
+    type: "application",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    notify: true,
+    direction: "in",
+    ...event
+  });
+  reporter.success(feedback, `HTTP ${result.status}`);
+}
+function secondsLabel(durationMs) {
+  const seconds = Math.max(0, Math.round(durationMs / 1e3));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  return remainder ? `${minutes}m ${remainder}s` : `${minutes}m`;
+}
+async function publishSessionCompleted({
+  config,
+  reporter,
+  client,
+  directory,
+  sessionID,
+  messageID,
+  durationMs
+}) {
+  const sessionTitle = await resolveSessionTitle2(
+    client,
+    directory,
+    sessionID,
+    reporter
+  );
+  const duration = secondsLabel(durationMs);
+  const location = sessionTitle ? ` \u201C${sessionTitle}\u201D` : "";
+  await publish(config, reporter, {
+    severity: "info",
+    title: "OpenCode task completed",
+    body: `OpenCode finished${location} in ${duration}.`,
+    payload: [
+      { key: "OpenCode session", value: sessionTitle },
+      { key: "Outcome", value: "Completed" },
+      { key: "Duration", value: duration }
+    ].filter((item) => item.value),
+    externalId: `opencode:lifecycle:completed:${sessionID}:${messageID}`
+  }, "Task completion sent");
+}
+async function publishSessionRetry({
+  config,
+  reporter,
+  client,
+  directory,
+  sessionID,
+  correlation,
+  attempt,
+  next
+}) {
+  const sessionTitle = await resolveSessionTitle2(
+    client,
+    directory,
+    sessionID,
+    reporter
+  );
+  const retryAt = Number.isFinite(next) ? new Date(next).toISOString() : "";
+  await publish(config, reporter, {
+    severity: "warning",
+    title: "OpenCode is retrying",
+    body: `OpenCode reached retry attempt ${attempt}. The operation is still running.`,
+    payload: [
+      { key: "OpenCode session", value: sessionTitle },
+      { key: "Retry attempt", value: String(attempt) },
+      { key: "Next retry", value: retryAt }
+    ].filter((item) => item.value),
+    externalId: `opencode:lifecycle:retry:${sessionID}:${correlation}`
+  }, "Retry warning sent");
+}
+async function publishSessionError({
+  config,
+  reporter,
+  client,
+  directory,
+  sessionID,
+  correlation,
+  error
+}) {
+  const sessionTitle = await resolveSessionTitle2(
+    client,
+    directory,
+    sessionID,
+    reporter
+  );
+  const details = safeErrorDetails(error);
+  const location = sessionTitle ? ` in \u201C${sessionTitle}\u201D` : "";
+  const body = details.message ? `OpenCode failed${location}: ${details.message}` : `OpenCode failed${location}.`;
+  await publish(config, reporter, {
+    // Backeer/iOS currently support info, warning and critical severities.
+    severity: "critical",
+    title: "OpenCode task failed",
+    body: limit(body, 1e3),
+    payload: [
+      { key: "OpenCode session", value: sessionTitle },
+      { key: "Outcome", value: "Failed" },
+      { key: "Error type", value: details.name },
+      { key: "HTTP status", value: details.statusCode },
+      { key: "Error", value: details.message }
+    ].filter((item) => item.value),
+    externalId: `opencode:lifecycle:error:${sessionID || "global"}:${correlation}`
+  }, "Task failure sent");
+}
+async function publishOpenCodeUpdate({ config, reporter, version }) {
+  const safeVersion = limit(version, 100);
+  await publish(config, reporter, {
+    severity: "info",
+    title: "OpenCode update available",
+    body: `OpenCode ${safeVersion} is available.`,
+    payload: [{ key: "Available version", value: safeVersion }],
+    externalId: `opencode:lifecycle:update:${safeVersion}`
+  }, "OpenCode update sent");
+}
+function errorCorrelation(event, sessionState) {
+  if (typeof event?.id === "string" && event.id) return limit(event.id, 200);
+  if (sessionState?.lastAssistant?.id) return limit(sessionState.lastAssistant.id, 200);
+  const details = safeErrorDetails(event?.properties?.error);
+  return stableHash(`${details.name}:${details.statusCode}:${details.message}`);
+}
+
+// src/lifecycle-controller.js
+var QUESTION_EVENTS = /* @__PURE__ */ new Set(["question.asked", "question.v2.asked"]);
+var QUESTION_REPLY_EVENTS = /* @__PURE__ */ new Set([
+  "question.replied",
+  "question.v2.replied",
+  "question.answered",
+  "question.v2.answered"
+]);
+function createLifecycleController({
+  config,
+  reporter,
+  client,
+  directory,
+  now = () => Date.now(),
+  publishers = {}
+}) {
+  const sendCompleted = publishers.completed ?? publishSessionCompleted;
+  const sendError = publishers.error ?? publishSessionError;
+  const sendRetry = publishers.retry ?? publishSessionRetry;
+  const sendUpdate = publishers.update ?? publishOpenCodeUpdate;
+  const sessions = /* @__PURE__ */ new Map();
+  const publishedUpdates = /* @__PURE__ */ new Map();
+  function sessionState(sessionID) {
+    let state = sessions.get(sessionID);
+    if (!state) {
+      state = {
+        busy: false,
+        busySince: 0,
+        failed: false,
+        retryNotified: false,
+        waiting: false,
+        lastAssistant: void 0,
+        completedMessageID: ""
+      };
+      rememberBounded(sessions, sessionID, state);
+    }
+    return state;
+  }
+  function dispatch(label, operation) {
+    void Promise.resolve(operation).catch((error) => reporter.error(label, error));
+  }
+  function beginCycle(state) {
+    if (state.busy) return;
+    state.busy = true;
+    state.busySince = now();
+    state.failed = false;
+    state.retryNotified = false;
+    state.waiting = false;
+    state.lastAssistant = void 0;
+  }
+  function finishCycle(sessionID, state) {
+    if (!state.busy) return;
+    state.busy = false;
+    const assistant = state.lastAssistant;
+    const durationMs = Math.max(0, now() - state.busySince);
+    const qualifies = assistant?.id && assistant.completed && !assistant.error && !state.failed && !state.waiting && durationMs >= config.lifecycle.completionMinSeconds * 1e3 && state.completedMessageID !== assistant.id;
+    if (!qualifies || !config.lifecycle.completed) return;
+    state.completedMessageID = assistant.id;
+    dispatch(
+      "Task completion could not be sent",
+      sendCompleted({
+        config,
+        reporter,
+        client,
+        directory,
+        sessionID,
+        messageID: limit(assistant.id, 200),
+        durationMs
+      })
+    );
+  }
+  function handleMessage(event) {
+    const info = event.properties?.info;
+    if (info?.role !== "assistant" || typeof info.sessionID !== "string") return;
+    const state = sessionState(info.sessionID);
+    state.lastAssistant = {
+      id: typeof info.id === "string" ? info.id : "",
+      completed: Number.isFinite(info.time?.completed),
+      error: Boolean(info.error)
+    };
+    if (info.error) state.failed = true;
+  }
+  function handleStatus(event) {
+    const sessionID = event.properties?.sessionID;
+    const status = event.properties?.status;
+    if (typeof sessionID !== "string" || typeof status?.type !== "string") return;
+    const state = sessionState(sessionID);
+    if (status.type === "busy") {
+      beginCycle(state);
+      return;
+    }
+    if (status.type === "idle") {
+      finishCycle(sessionID, state);
+      return;
+    }
+    if (status.type !== "retry") return;
+    beginCycle(state);
+    if (!config.lifecycle.retries || state.retryNotified) return;
+    if (!Number.isInteger(status.attempt) || status.attempt < config.lifecycle.retryAttemptThreshold) return;
+    state.retryNotified = true;
+    const correlation = state.lastAssistant?.id || stableHash(
+      `${status.attempt}:${Number.isFinite(status.next) ? status.next : "unknown"}`
+    );
+    dispatch(
+      "Retry warning could not be sent",
+      sendRetry({
+        config,
+        reporter,
+        client,
+        directory,
+        sessionID,
+        correlation: limit(correlation, 200),
+        attempt: status.attempt,
+        next: status.next
+      })
+    );
+  }
+  function handleError(event) {
+    const sessionID = typeof event.properties?.sessionID === "string" ? event.properties.sessionID : "";
+    const state = sessionID ? sessionState(sessionID) : void 0;
+    if (state) state.failed = true;
+    if (!config.lifecycle.errors) return;
+    dispatch(
+      "Task failure could not be sent",
+      sendError({
+        config,
+        reporter,
+        client,
+        directory,
+        sessionID,
+        correlation: errorCorrelation(event, state),
+        error: event.properties?.error
+      })
+    );
+  }
+  function handleWaiting(event, waiting) {
+    const sessionID = event.properties?.sessionID;
+    if (typeof sessionID !== "string") return;
+    sessionState(sessionID).waiting = waiting;
+  }
+  return {
+    handle(event) {
+      if (!config.lifecycle.enabled || !event?.type) return;
+      if (event.type === "message.updated") {
+        handleMessage(event);
+      } else if (event.type === "session.status") {
+        handleStatus(event);
+      } else if (event.type === "session.idle") {
+        const sessionID = event.properties?.sessionID;
+        if (typeof sessionID === "string") finishCycle(sessionID, sessionState(sessionID));
+      } else if (event.type === "session.error") {
+        handleError(event);
+      } else if (event.type === "permission.asked" || QUESTION_EVENTS.has(event.type)) {
+        handleWaiting(event, true);
+      } else if (event.type === "permission.replied" || QUESTION_REPLY_EVENTS.has(event.type)) {
+        handleWaiting(event, false);
+      } else if (event.type === "installation.update-available" && config.lifecycle.updates) {
+        const version = event.properties?.version;
+        if (typeof version !== "string" || !version.trim()) return;
+        if (publishedUpdates.has(version)) return;
+        rememberBounded(publishedUpdates, version, true);
+        dispatch(
+          "OpenCode update could not be sent",
+          sendUpdate({ config, reporter, version: version.trim() })
+        );
+      }
+    },
+    dispose() {
+      sessions.clear();
+      publishedUpdates.clear();
+    }
+  };
+}
+
 // src/sse.js
 function parseSseFrame(frame) {
   const data = [];
@@ -988,6 +1367,12 @@ async function BackeerPlugin({ client, directory }, options = {}) {
     client,
     directory
   });
+  const lifecycleController = createLifecycleController({
+    config,
+    reporter,
+    client,
+    directory
+  });
   const todoCompletionBySessionID = /* @__PURE__ */ new Map();
   const publishedQuestions = /* @__PURE__ */ new Map();
   const updateChecker = createUpdateChecker();
@@ -1064,6 +1449,7 @@ async function BackeerPlugin({ client, directory }, options = {}) {
     "chat.message": handleUpdateNotice,
     event: async ({ event }) => {
       if (!config.token) return;
+      lifecycleController.handle(event);
       if (config.permissions && event.type === "permission.asked") {
         await handlePermissionAsked(event);
         return;
@@ -1084,6 +1470,7 @@ async function BackeerPlugin({ client, directory }, options = {}) {
     },
     dispose: async () => {
       await permissionController.dispose();
+      lifecycleController.dispose();
       todoCompletionBySessionID.clear();
       publishedQuestions.clear();
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "backeer-opencode",
-  "version": "0.1.5",
-  "description": "Backeer notifications and remote permission decisions for OpenCode",
+  "version": "0.2.0",
+  "description": "Backeer lifecycle notifications and remote permission decisions for OpenCode",
   "type": "module",
   "main": "./src/index.js",
   "exports": {

package/src/config.js

@@ -7,6 +7,50 @@ import { enabled } from "./utilities.js"
 
 const DEFAULT_ORIGIN = "https://external-gateway.backeer.com"
 
+function integer(value, fallback, { minimum = 0, maximum = 86_400 } = {}) {
+  if (value === undefined || value === null || value === "") return fallback
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed < minimum || parsed > maximum) {
+    throw new Error(`Expected an integer between ${minimum} and ${maximum}`)
+  }
+  return parsed
+}
+
+function loadLifecycleConfig(option) {
+  const values = option && typeof option === "object" ? option : {}
+  const masterValue = typeof option === "boolean"
+    ? option
+    : values.enabled ?? process.env.BACKEER_NOTIFY_LIFECYCLE
+  const masterEnabled = enabled(masterValue)
+
+  return {
+    enabled: masterEnabled,
+    completed: masterEnabled && enabled(
+      values.completed ?? process.env.BACKEER_NOTIFY_SESSION_COMPLETED,
+    ),
+    errors: masterEnabled && enabled(
+      values.errors ?? process.env.BACKEER_NOTIFY_SESSION_ERRORS,
+    ),
+    retries: masterEnabled && enabled(
+      values.retries ?? process.env.BACKEER_NOTIFY_SESSION_RETRIES,
+    ),
+    updates: masterEnabled && enabled(
+      values.updates ?? process.env.BACKEER_NOTIFY_OPENCODE_UPDATES,
+    ),
+    completionMinSeconds: integer(
+      values.completionMinSeconds ??
+        process.env.BACKEER_SESSION_COMPLETION_MIN_SECONDS,
+      0,
+    ),
+    retryAttemptThreshold: integer(
+      values.retryAttemptThreshold ??
+        process.env.BACKEER_RETRY_ATTEMPT_THRESHOLD,
+      3,
+      { minimum: 1, maximum: 100 },
+    ),
+  }
+}
+
 function defaultConfigDirectory() {
   const base = process.env.XDG_CONFIG_HOME?.trim()
   return base ? join(base, "opencode") : join(homedir(), ".config", "opencode")
@@ -52,6 +96,7 @@ export function loadConfig(options = {}) {
       options.questions ?? process.env.BACKEER_NOTIFY_QUESTIONS,
     ),
     todos: enabled(options.todos ?? process.env.BACKEER_NOTIFY_TODOS),
+    lifecycle: loadLifecycleConfig(options.lifecycle),
     logLevel: normalizeLogLevel(
       options.logLevel ?? process.env.BACKEER_LOG_LEVEL,
     ),

package/src/lifecycle-controller.js

@@ -0,0 +1,205 @@
+import {
+  errorCorrelation,
+  publishOpenCodeUpdate,
+  publishSessionCompleted,
+  publishSessionError,
+  publishSessionRetry,
+} from "./lifecycle-publishers.js"
+import { limit, rememberBounded, stableHash } from "./utilities.js"
+
+const QUESTION_EVENTS = new Set(["question.asked", "question.v2.asked"])
+const QUESTION_REPLY_EVENTS = new Set([
+  "question.replied",
+  "question.v2.replied",
+  "question.answered",
+  "question.v2.answered",
+])
+
+export function createLifecycleController({
+  config,
+  reporter,
+  client,
+  directory,
+  now = () => Date.now(),
+  publishers = {},
+}) {
+  const sendCompleted = publishers.completed ?? publishSessionCompleted
+  const sendError = publishers.error ?? publishSessionError
+  const sendRetry = publishers.retry ?? publishSessionRetry
+  const sendUpdate = publishers.update ?? publishOpenCodeUpdate
+  const sessions = new Map()
+  const publishedUpdates = new Map()
+
+  function sessionState(sessionID) {
+    let state = sessions.get(sessionID)
+    if (!state) {
+      state = {
+        busy: false,
+        busySince: 0,
+        failed: false,
+        retryNotified: false,
+        waiting: false,
+        lastAssistant: undefined,
+        completedMessageID: "",
+      }
+      rememberBounded(sessions, sessionID, state)
+    }
+    return state
+  }
+
+  function dispatch(label, operation) {
+    void Promise.resolve(operation).catch((error) => reporter.error(label, error))
+  }
+
+  function beginCycle(state) {
+    if (state.busy) return
+    state.busy = true
+    state.busySince = now()
+    state.failed = false
+    state.retryNotified = false
+    state.waiting = false
+    state.lastAssistant = undefined
+  }
+
+  function finishCycle(sessionID, state) {
+    if (!state.busy) return
+    state.busy = false
+    const assistant = state.lastAssistant
+    const durationMs = Math.max(0, now() - state.busySince)
+    const qualifies = assistant?.id && assistant.completed && !assistant.error &&
+      !state.failed && !state.waiting &&
+      durationMs >= config.lifecycle.completionMinSeconds * 1000 &&
+      state.completedMessageID !== assistant.id
+    if (!qualifies || !config.lifecycle.completed) return
+
+    state.completedMessageID = assistant.id
+    dispatch(
+      "Task completion could not be sent",
+      sendCompleted({
+        config,
+        reporter,
+        client,
+        directory,
+        sessionID,
+        messageID: limit(assistant.id, 200),
+        durationMs,
+      }),
+    )
+  }
+
+  function handleMessage(event) {
+    const info = event.properties?.info
+    if (info?.role !== "assistant" || typeof info.sessionID !== "string") return
+    const state = sessionState(info.sessionID)
+    state.lastAssistant = {
+      id: typeof info.id === "string" ? info.id : "",
+      completed: Number.isFinite(info.time?.completed),
+      error: Boolean(info.error),
+    }
+    if (info.error) state.failed = true
+  }
+
+  function handleStatus(event) {
+    const sessionID = event.properties?.sessionID
+    const status = event.properties?.status
+    if (typeof sessionID !== "string" || typeof status?.type !== "string") return
+    const state = sessionState(sessionID)
+
+    if (status.type === "busy") {
+      beginCycle(state)
+      return
+    }
+    if (status.type === "idle") {
+      finishCycle(sessionID, state)
+      return
+    }
+    if (status.type !== "retry") return
+
+    beginCycle(state)
+    if (!config.lifecycle.retries || state.retryNotified) return
+    if (!Number.isInteger(status.attempt) ||
+        status.attempt < config.lifecycle.retryAttemptThreshold) return
+
+    state.retryNotified = true
+    const correlation = state.lastAssistant?.id || stableHash(
+      `${status.attempt}:${Number.isFinite(status.next) ? status.next : "unknown"}`,
+    )
+    dispatch(
+      "Retry warning could not be sent",
+      sendRetry({
+        config,
+        reporter,
+        client,
+        directory,
+        sessionID,
+        correlation: limit(correlation, 200),
+        attempt: status.attempt,
+        next: status.next,
+      }),
+    )
+  }
+
+  function handleError(event) {
+    const sessionID = typeof event.properties?.sessionID === "string"
+      ? event.properties.sessionID
+      : ""
+    const state = sessionID ? sessionState(sessionID) : undefined
+    if (state) state.failed = true
+    if (!config.lifecycle.errors) return
+
+    dispatch(
+      "Task failure could not be sent",
+      sendError({
+        config,
+        reporter,
+        client,
+        directory,
+        sessionID,
+        correlation: errorCorrelation(event, state),
+        error: event.properties?.error,
+      }),
+    )
+  }
+
+  function handleWaiting(event, waiting) {
+    const sessionID = event.properties?.sessionID
+    if (typeof sessionID !== "string") return
+    sessionState(sessionID).waiting = waiting
+  }
+
+  return {
+    handle(event) {
+      if (!config.lifecycle.enabled || !event?.type) return
+
+      if (event.type === "message.updated") {
+        handleMessage(event)
+      } else if (event.type === "session.status") {
+        handleStatus(event)
+      } else if (event.type === "session.idle") {
+        const sessionID = event.properties?.sessionID
+        if (typeof sessionID === "string") finishCycle(sessionID, sessionState(sessionID))
+      } else if (event.type === "session.error") {
+        handleError(event)
+      } else if (event.type === "permission.asked" || QUESTION_EVENTS.has(event.type)) {
+        handleWaiting(event, true)
+      } else if (event.type === "permission.replied" || QUESTION_REPLY_EVENTS.has(event.type)) {
+        handleWaiting(event, false)
+      } else if (event.type === "installation.update-available" &&
+          config.lifecycle.updates) {
+        const version = event.properties?.version
+        if (typeof version !== "string" || !version.trim()) return
+        if (publishedUpdates.has(version)) return
+        rememberBounded(publishedUpdates, version, true)
+        dispatch(
+          "OpenCode update could not be sent",
+          sendUpdate({ config, reporter, version: version.trim() }),
+        )
+      }
+    },
+
+    dispose() {
+      sessions.clear()
+      publishedUpdates.clear()
+    },
+  }
+}

package/src/lifecycle-publishers.js

@@ -0,0 +1,187 @@
+import { postJsonWithRetry } from "./http.js"
+import { limit, stableHash } from "./utilities.js"
+
+const CONTROL_CHARACTERS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g
+const SECRET_ASSIGNMENT = /\b(token|secret|password|api[-_ ]?key)\s*[:=]\s*[^\s,;]+/gi
+const BEARER_TOKEN = /\bBearer\s+[^\s,;]+/gi
+const URL_WITH_QUERY = /\bhttps?:\/\/[^\s?#]+(?:\?[^\s#]*)?(?:#[^\s]*)?/gi
+const WINDOWS_PATH = /\b[A-Za-z]:\\(?:[^\\\s]+\\)+[^\s]*/g
+const POSIX_PATH = /(^|\s)\/(?:[^/\s]+\/)+[^\s]*/g
+
+export function sanitizeErrorMessage(value) {
+  return limit(value, 2000)
+    .replace(CONTROL_CHARACTERS, " ")
+    .replace(BEARER_TOKEN, "Bearer [redacted]")
+    .replace(SECRET_ASSIGNMENT, "$1=[redacted]")
+    .replace(URL_WITH_QUERY, (value) => {
+      try {
+        const url = new URL(value)
+        return `${url.origin}${url.pathname}`
+      } catch {
+        return "[url redacted]"
+      }
+    })
+    .replace(WINDOWS_PATH, "[path redacted]")
+    .replace(POSIX_PATH, "$1[path redacted]")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 500)
+}
+
+export function safeErrorDetails(error) {
+  const name = limit(error?.name || "OpenCodeError", 100)
+  const message = sanitizeErrorMessage(error?.data?.message ?? error?.message)
+  const statusCode = Number.isInteger(error?.data?.statusCode)
+    ? String(error.data.statusCode)
+    : ""
+  return { name, message, statusCode }
+}
+
+async function resolveSessionTitle(client, directory, sessionID, reporter) {
+  if (!sessionID || typeof client?.session?.get !== "function") return ""
+
+  try {
+    const result = await client.session.get({
+      path: { id: sessionID },
+      query: { directory },
+      throwOnError: true,
+    })
+    return limit((result?.data ?? result)?.title)
+  } catch (error) {
+    reporter.debug("Session title unavailable", error)
+    return ""
+  }
+}
+
+async function publish(config, reporter, event, feedback) {
+  const result = await postJsonWithRetry(config, config.eventsEndpoint, {
+    type: "application",
+    timestamp: new Date().toISOString(),
+    notify: true,
+    direction: "in",
+    ...event,
+  })
+  reporter.success(feedback, `HTTP ${result.status}`)
+}
+
+function secondsLabel(durationMs) {
+  const seconds = Math.max(0, Math.round(durationMs / 1000))
+  if (seconds < 60) return `${seconds}s`
+  const minutes = Math.floor(seconds / 60)
+  const remainder = seconds % 60
+  return remainder ? `${minutes}m ${remainder}s` : `${minutes}m`
+}
+
+export async function publishSessionCompleted({
+  config,
+  reporter,
+  client,
+  directory,
+  sessionID,
+  messageID,
+  durationMs,
+}) {
+  const sessionTitle = await resolveSessionTitle(
+    client,
+    directory,
+    sessionID,
+    reporter,
+  )
+  const duration = secondsLabel(durationMs)
+  const location = sessionTitle ? ` “${sessionTitle}”` : ""
+  await publish(config, reporter, {
+    severity: "info",
+    title: "OpenCode task completed",
+    body: `OpenCode finished${location} in ${duration}.`,
+    payload: [
+      { key: "OpenCode session", value: sessionTitle },
+      { key: "Outcome", value: "Completed" },
+      { key: "Duration", value: duration },
+    ].filter((item) => item.value),
+    externalId: `opencode:lifecycle:completed:${sessionID}:${messageID}`,
+  }, "Task completion sent")
+}
+
+export async function publishSessionRetry({
+  config,
+  reporter,
+  client,
+  directory,
+  sessionID,
+  correlation,
+  attempt,
+  next,
+}) {
+  const sessionTitle = await resolveSessionTitle(
+    client,
+    directory,
+    sessionID,
+    reporter,
+  )
+  const retryAt = Number.isFinite(next) ? new Date(next).toISOString() : ""
+  await publish(config, reporter, {
+    severity: "warning",
+    title: "OpenCode is retrying",
+    body: `OpenCode reached retry attempt ${attempt}. The operation is still running.`,
+    payload: [
+      { key: "OpenCode session", value: sessionTitle },
+      { key: "Retry attempt", value: String(attempt) },
+      { key: "Next retry", value: retryAt },
+    ].filter((item) => item.value),
+    externalId: `opencode:lifecycle:retry:${sessionID}:${correlation}`,
+  }, "Retry warning sent")
+}
+
+export async function publishSessionError({
+  config,
+  reporter,
+  client,
+  directory,
+  sessionID,
+  correlation,
+  error,
+}) {
+  const sessionTitle = await resolveSessionTitle(
+    client,
+    directory,
+    sessionID,
+    reporter,
+  )
+  const details = safeErrorDetails(error)
+  const location = sessionTitle ? ` in “${sessionTitle}”` : ""
+  const body = details.message
+    ? `OpenCode failed${location}: ${details.message}`
+    : `OpenCode failed${location}.`
+  await publish(config, reporter, {
+    // Backeer/iOS currently support info, warning and critical severities.
+    severity: "critical",
+    title: "OpenCode task failed",
+    body: limit(body, 1000),
+    payload: [
+      { key: "OpenCode session", value: sessionTitle },
+      { key: "Outcome", value: "Failed" },
+      { key: "Error type", value: details.name },
+      { key: "HTTP status", value: details.statusCode },
+      { key: "Error", value: details.message },
+    ].filter((item) => item.value),
+    externalId: `opencode:lifecycle:error:${sessionID || "global"}:${correlation}`,
+  }, "Task failure sent")
+}
+
+export async function publishOpenCodeUpdate({ config, reporter, version }) {
+  const safeVersion = limit(version, 100)
+  await publish(config, reporter, {
+    severity: "info",
+    title: "OpenCode update available",
+    body: `OpenCode ${safeVersion} is available.`,
+    payload: [{ key: "Available version", value: safeVersion }],
+    externalId: `opencode:lifecycle:update:${safeVersion}`,
+  }, "OpenCode update sent")
+}
+
+export function errorCorrelation(event, sessionState) {
+  if (typeof event?.id === "string" && event.id) return limit(event.id, 200)
+  if (sessionState?.lastAssistant?.id) return limit(sessionState.lastAssistant.id, 200)
+  const details = safeErrorDetails(event?.properties?.error)
+  return stableHash(`${details.name}:${details.statusCode}:${details.message}`)
+}

package/src/management.js

@@ -111,6 +111,11 @@ async function buildStatus(config, permissionController, updateChecker) {
     `- Permission notifications: ${config.permissions ? "enabled" : "disabled"}`,
     `- Question notifications: ${config.questions ? "enabled" : "disabled"}`,
     `- Todo notifications: ${config.todos ? "enabled" : "disabled"}`,
+    `- Lifecycle notifications: ${config.lifecycle.enabled ? "enabled" : "disabled"}`,
+    `  - Completed sessions: ${config.lifecycle.completed ? "enabled" : "disabled"} (minimum ${config.lifecycle.completionMinSeconds}s)`,
+    `  - Session errors: ${config.lifecycle.errors ? "enabled" : "disabled"}`,
+    `  - Retry warnings: ${config.lifecycle.retries ? "enabled" : "disabled"} (attempt ${config.lifecycle.retryAttemptThreshold}+)`,
+    `  - OpenCode updates: ${config.lifecycle.updates ? "enabled" : "disabled"}`,
     `- Command stream: ${permissionStatus.stream}`,
     `- Pending permissions: ${permissionStatus.pending}`,
     `- Log level: ${config.logLevel}`,

package/src/plugin.js

@@ -10,6 +10,7 @@ import {
   createBackeerCommandHandler,
   registerBackeerCommand,
 } from "./management.js"
+import { createLifecycleController } from "./lifecycle-controller.js"
 import { createPermissionController } from "./permission-controller.js"
 import { createConsoleReporter } from "./reporter.js"
 import {
@@ -21,7 +22,8 @@ import { rememberBounded } from "./utilities.js"
 /**
  * OpenCode server plugin entrypoint.
  *
- * Supported options: origin, tokenFile, permissions, questions, todos, logLevel.
+ * Supported options: origin, tokenFile, permissions, questions, todos,
+ * lifecycle, logLevel.
  * The ingest token is intentionally accepted only through the environment or a
  * protected file so it cannot accidentally be committed in opencode.json.
  */
@@ -45,6 +47,12 @@ export default async function BackeerPlugin({ client, directory }, options = {})
     client,
     directory,
   })
+  const lifecycleController = createLifecycleController({
+    config,
+    reporter,
+    client,
+    directory,
+  })
   const todoCompletionBySessionID = new Map()
   const publishedQuestions = new Map()
   const updateChecker = createUpdateChecker()
@@ -135,6 +143,8 @@ export default async function BackeerPlugin({ client, directory }, options = {})
     event: async ({ event }) => {
       if (!config.token) return
 
+      lifecycleController.handle(event)
+
       if (config.permissions && event.type === "permission.asked") {
         await handlePermissionAsked(event)
         return
@@ -162,6 +172,7 @@ export default async function BackeerPlugin({ client, directory }, options = {})
 
     dispose: async () => {
       await permissionController.dispose()
+      lifecycleController.dispose()
       todoCompletionBySessionID.clear()
       publishedQuestions.clear()
     },

package/src/updates.js

@@ -1,4 +1,4 @@
-export const PLUGIN_VERSION = "0.1.5"
+export const PLUGIN_VERSION = "0.2.0"
 
 const PACKAGE_NAME = "backeer-opencode"
 const NPM_REGISTRY_URL = "https://registry.npmjs.org"