th-cc50cd: wire the OpenCode lifecycle plugin into th harness

enable opencode links ~/.config/opencode/plugins/smooth-agent.js into the
smooth-agent plugin checkout (never-clobber: only symlinks are replaced,
a real file is refused); status reports it; disable removes it under the
same resolves-into-smooth-owned-sources rule as skills. Docs + changeset.

Gates: cargo fmt/clippy clean, cargo test --features admin 686 passed
(10 harness tests incl. the new link/refuse/disable case), pnpm
test:hooks 21 passed + node plugin lifecycle test.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: brentrager

.changeset/oc-lifecycle-plugin.md

@@ -0,0 +1,5 @@
+---
+'@smooai/smooth': minor
+---
+
+th-cc50cd: smooth-agent OpenCode lifecycle plugin — every OpenCode session now registers on the th-mail bus (placeholder handle `oc-<dir>-<sid4>`, pid-reaped), publishes working presence from tool activity (throttled), goes idle on session.idle and offline on session.deleted, degrading to a silent no-op without `th`. `th harness enable opencode` links it into `~/.config/opencode/plugins/` from the smooth-agent plugin checkout (same never-clobber/ownership rules as skills; `disable` removes it), `status` reports it, and the node smoke test is wired into `pnpm test:hooks`.

crates/smooth-cli/src/harness.rs

@@ -105,10 +105,17 @@ fn enable(h: Harness, home: &Path) {
             statusline_step(home);
         }
         Harness::Codex => codex_plugin_step(home),
-        Harness::OpenCode => match link_skills(home) {
-            Ok((added, kept)) => println!("   skills: {added} linked, {kept} already current → {}", opencode_skills_dir(home).display()),
-            Err(e) => println!("   skills: {} {e:#}", "FAILED".bright_red()),
-        },
+        Harness::OpenCode => {
+            match link_skills(home) {
+                Ok((added, kept)) => println!("   skills: {added} linked, {kept} already current → {}", opencode_skills_dir(home).display()),
+                Err(e) => println!("   skills: {} {e:#}", "FAILED".bright_red()),
+            }
+            match link_opencode_plugin(home) {
+                Ok(true) => println!("   plugin: lifecycle plugin linked → {}", opencode_plugin_link(home).display()),
+                Ok(false) => println!("   plugin: already current"),
+                Err(e) => println!("   plugin: {} {e:#}", "FAILED".bright_red()),
+            }
+        }
     }
 }
 
@@ -210,6 +217,11 @@ fn status(h: Harness, home: &Path) {
             } else {
                 println!("   skills: {n} linked");
             }
+            if smooth_owned_link(&opencode_plugin_link(home), home) {
+                println!("   plugin: lifecycle plugin linked");
+            } else {
+                println!("   plugin: not linked — `th harness enable opencode`");
+            }
         }
     }
 }
@@ -224,6 +236,11 @@ fn disable(h: Harness, home: &Path) -> Result<()> {
             std::fs::remove_file(l).with_context(|| format!("remove {}", l.display()))?;
         }
         println!("   skills: {} smooth-owned links removed", links.len());
+        let plugin = opencode_plugin_link(home);
+        if smooth_owned_link(&plugin, home) {
+            std::fs::remove_file(&plugin).with_context(|| format!("remove {}", plugin.display()))?;
+            println!("   plugin: lifecycle plugin link removed");
+        }
     }
     if h == Harness::ClaudeCode {
         println!("   plugin: left installed — remove with `claude plugin uninstall smooth-agent@smooth` if you mean it");
@@ -267,6 +284,50 @@ fn opencode_skills_dir(home: &Path) -> PathBuf {
     home.join(".opencode").join("skills")
 }
 
+/// Where the OpenCode lifecycle plugin (th-cc50cd) gets linked: OpenCode
+/// auto-loads plugin files from `~/.config/opencode/plugins/`.
+fn opencode_plugin_link(home: &Path) -> PathBuf {
+    home.join(".config").join("opencode").join("plugins").join("smooth-agent.js")
+}
+
+/// Is this path a symlink resolving into smooth-owned sources (the Claude
+/// plugin cache / marketplace checkout)? The ownership rule for everything
+/// `disable` may remove.
+fn smooth_owned_link(path: &Path, home: &Path) -> bool {
+    std::fs::symlink_metadata(path).is_ok_and(|m| m.file_type().is_symlink())
+        && std::fs::read_link(path).is_ok_and(|t| t.starts_with(home.join(".claude").join("plugins")))
+}
+
+/// Link the smooth-agent OpenCode lifecycle plugin (session registration +
+/// presence on the th-mail bus). Same never-clobber rules as skills: only a
+/// symlink is ever replaced. Returns true when the link was (re)written.
+fn link_opencode_plugin(home: &Path) -> Result<bool> {
+    let source = skill_source(home)
+        .and_then(|skills| skills.parent().map(|root| root.join("opencode").join("smooth-agent.js")))
+        .filter(|p| p.is_file())
+        .context("smooth-agent plugin checkout has no opencode/smooth-agent.js — update the plugin first (th harness enable claude-code)")?;
+    let link = opencode_plugin_link(home);
+    if let Some(parent) = link.parent() {
+        std::fs::create_dir_all(parent).with_context(|| format!("create {}", parent.display()))?;
+    }
+    match std::fs::symlink_metadata(&link) {
+        Ok(meta) if meta.file_type().is_symlink() => {
+            if std::fs::read_link(&link).is_ok_and(|t| t == source) {
+                return Ok(false);
+            }
+            std::fs::remove_file(&link)?;
+        }
+        Ok(_) => anyhow::bail!("{} exists and is not a symlink — left alone", link.display()),
+        Err(_) => {}
+    }
+    #[cfg(unix)]
+    std::os::unix::fs::symlink(&source, &link).with_context(|| format!("link {}", link.display()))?;
+    #[cfg(not(unix))]
+    anyhow::bail!("plugin link needs symlink support; copy {} manually", source.display());
+    #[cfg(unix)]
+    Ok(true)
+}
+
 /// Symlink every canonical skill into the OpenCode skills dir. Never clobbers
 /// a real file/dir; repairs stale or dead symlinks. Returns (added, kept).
 fn link_skills(home: &Path) -> Result<(usize, usize)> {
@@ -413,6 +474,9 @@ mod tests {
             std::fs::create_dir_all(&d).unwrap();
             std::fs::write(d.join("SKILL.md"), "x").unwrap();
         }
+        let oc = tmp.path().join(".claude/plugins/marketplaces/smooth/claude-plugins/smooth-agent/opencode");
+        std::fs::create_dir_all(&oc).unwrap();
+        std::fs::write(oc.join("smooth-agent.js"), "export const SmoothAgent = 1;").unwrap();
         tmp
     }
 
@@ -512,6 +576,29 @@ mod tests {
         assert!(claude_statusline_wired(tmp.path()));
     }
 
+    #[test]
+    #[cfg(unix)] // exercises real symlinks
+    fn opencode_lifecycle_plugin_links_and_disables_cleanly() {
+        let tmp = home();
+        assert!(link_opencode_plugin(tmp.path()).unwrap(), "first run links");
+        assert!(!link_opencode_plugin(tmp.path()).unwrap(), "second run is a no-op");
+        let link = opencode_plugin_link(tmp.path());
+        assert!(smooth_owned_link(&link, tmp.path()));
+
+        // A user's own real file of the same name is refused, not clobbered.
+        std::fs::remove_file(&link).unwrap();
+        std::fs::write(&link, "my own plugin").unwrap();
+        assert!(link_opencode_plugin(tmp.path()).is_err());
+        assert_eq!(std::fs::read_to_string(&link).unwrap(), "my own plugin");
+        assert!(!smooth_owned_link(&link, tmp.path()), "a real file is never ours to remove");
+        std::fs::remove_file(&link).unwrap();
+
+        // disable removes the link it owns.
+        link_opencode_plugin(tmp.path()).unwrap();
+        disable(Harness::OpenCode, tmp.path()).unwrap();
+        assert!(std::fs::symlink_metadata(&link).is_err(), "disable must remove the plugin link");
+    }
+
     #[test]
     fn providers_expands_all_and_rejects_junk() {
         assert_eq!(providers("all").unwrap(), Harness::ALL.to_vec());

docs/Engineering/Using-th-CLI.md

@@ -58,6 +58,9 @@ th harness enable claude-code   # smooth-agent plugin install/update (claude CLI
                                 # MCP server, statusline check
 th harness enable codex         # MCP server + plugin state detection
 th harness enable opencode      # MCP server + shared-skill symlinks (~/.opencode/skills)
+                                # + the lifecycle plugin (~/.config/opencode/plugins/smooth-agent.js):
+                                # every OpenCode session registers on the th-mail bus with
+                                # working/idle/offline presence (pearl th-cc50cd)
 th harness enable all
 th harness status               # per-harness: MCP ok/stale/missing, plugin, skills, statusline
 th harness disable <provider>   # removes ONLY what smooth wrote (MCP entry, smooth-owned links)
@@ -68,9 +71,9 @@ th harness disable <provider>   # removes ONLY what smooth wrote (MCP entry, smo
 key order survive); `disable` never touches user-owned entries. The canonical
 skill source is the installed smooth-agent plugin checkout; Claude Code and
 Codex consume skills through the plugin itself, OpenCode gets symlinks.
-Lifecycle-hook parity for OpenCode (session registration, presence, inbox
-delivery) is pearl th-cc50cd; the read-only/approval-gated MCP tool split is
-pearl th-1d5ca8.
+Inbox delivery INTO a running OpenCode session (prompt-boundary context
+injection via the SDK client) is the remaining piece of pearl th-cc50cd; the
+write kill switch for `th mcp serve` is `SMOOTH_MCP_ALLOW_WRITE=0` (th-1d5ca8).
 
 ---