@shardflux/cli 0.18.0 → 0.18.1

package/CHANGELOG.md

@@ -1,6 +1,21 @@
 # Changelog
 
-## 0.18.0 (not yet published)
+## 0.18.1 (not yet published)
+
+- `shard agents logs` takes a conversation id (`shard agents logs conv_… --json`) and follows that conversation's own
+  terminal: the PTY its computer recorded for it (a fork's inherited one included), also when you name the
+  conversation's VM by its key. `--json` adds `conversation: { id }`. Before, a conversation id read as an unknown
+  workspace key and a conversation VM's key looked for a terminal named after the VM.
+- A finished conversation whose VM was removed opens again from every app: `shard agents open <conversation>` with
+  `--in auto` (the menu bar), `--in web`, `--in claude-desktop` or `--in t3` restores it into a fresh VM from its saved
+  branch and transcript (the same conversation, its session resumed and started) instead of answering `This
+  conversation is saved. Resume it to continue.` A restore says `Restored` once. `shard conversations send` says it
+  too when the API restored the conversation to take the message.
+- Brings the Shardflux app for Ubuntu 0.1.1, which reads this CLI's `--json` answers whole: Settings → Agents shows
+  Connected, the top-bar panel lists your conversations, and Start opens the conversation it started. The optional
+  dependency on `@shardflux/desktop-linux-x64` / `-arm64` is exactly 0.1.1.
+
+## 0.18.0 (2026-10-10)
 
 - A conversation that needs you says why: `shard conversations list` adds it as a fifth column, `shard conversations
   get` prints it after the branch, and `shard agents list` shows it as the session's LAST MESSAGE (one line, cut to

package/README.md

@@ -428,7 +428,7 @@ plan only when Stripe confirms the payment, so `--wait` polls until the subscrip
 open). An organization that already has a subscription changes plans in the billing portal: the
 command prints the portal URL instead (exit 0).
 
-On the signup trial (60 days of Pro, no card), `billing status` shows when it ends and
+On the signup trial (30 days of Pro, no card), `billing status` shows when it ends and
 what follows (0.6.2+): `plan  trial, ends 2026-11-29 14:03:00Z, then free (trial, catalog ...)`, then
 `keep these limits after the trial: shard billing upgrade pro` (0.13.4+). A subscription outranks the
 trial and ends it. The trial is granted, never bought, so `billing plans` leaves it out.

package/dist/agent-commands.js

@@ -28,7 +28,7 @@ import { openInFor } from "./t3-mode.js";
 import { openClaudeDesktopSession, openDesktopWorkspace, queueT3Prewarm } from "./agent-target-commands.js";
 import { submitInitialPrompt, prepareInitialCodexProject } from "./initial-prompt.js";
 import { conversationWorkspace, conversationsUnavailable, getConversation, listConversations, resumeConversation } from "./conversations.js";
-import { conversationTerminal } from "./conversation-terminal.js";
+import { conversationTerminal, reopenConversation } from "./conversation-terminal.js";
 import { CHOICE_PENDING, choiceReport, hasChoice, launchChoice, modelChoice, runFlags } from "./agent-models.js";
 const active = (session) => session.state === 'running' || session.state === 'starting';
 /** `<slug>-<6 hex of sha256(identity)>`: the same repository gets the same key on every machine. */
@@ -299,7 +299,12 @@ export const AGENT_HANDLERS = {
         if (values.in === 'auto') {
             // The menu and other launchers use the same CLI-owned target selection. Never put provider URLs in a client.
             // A conversation id opens that conversation's own session, also when its computer hosts other threads.
-            const ws = resolvedConversation ? await conversationWorkspace(ctx, resolvedConversation) : await resolveWorkspace(ctx, agent);
+            // A conversation whose VM was removed restores into a fresh one first (0.18.1+).
+            let ws;
+            if (resolvedConversation)
+                ({ conversation: resolvedConversation, ws } = await reopenConversation(ctx, resolvedConversation, values));
+            else
+                ws = await resolveWorkspace(ctx, agent);
             const project = ws.labels.repo_remote || ws.labels.shard_project || ws.key;
             const store = new AgentStateStore(ctx.store.dir);
             const app = values.app ?? resolvedConversation?.harness ?? ws.labels.shard_app ?? ws.labels.app ?? store.app(project);

package/dist/agent-target-commands.js

@@ -5,7 +5,7 @@ import { ensureCloudClaude } from "./claude-cloud-login.js";
 import { spawn } from 'node:child_process';
 import { Readable, Duplex } from 'node:stream';
 import { ShardfluxApiError, WorkspaceTunnels } from '@shardflux/sdk';
-import { conversationWorkspace, getConversation } from "./conversations.js";
+import { getConversation } from "./conversations.js";
 import { out, resolveWorkspace } from "./commands.js";
 import { MODEL_CHOICES } from "./agent-models.js";
 import { AgentTargets, installedTargets, targetLabel } from "./agent-targets.js";
@@ -229,14 +229,21 @@ const openTarget = (target) => async (ctx, values, [ref = 'main']) => {
     if (target === 't3' && /^conv_[a-z0-9]{26}$/.test(ref))
         return openT3Conversation(ctx, ref, values);
     // A conversation id opens that conversation's own session on its computer (claude.ai, the desktop apps).
-    const conversation = /^conv_[a-z0-9]{26}$/.test(ref) ? await getConversation(ctx, ref) : undefined;
+    let conversation = /^conv_[a-z0-9]{26}$/.test(ref) ? await getConversation(ctx, ref) : undefined;
     // A pooled thread (0.18.0+) has no provider login on its session: it opens remotely in T3 Code.
     if (conversation && conversationPooled(conversation)) {
         if (!detected.targets.includes('t3'))
             throw pooledNeedsT3(ref);
         return openT3Conversation(ctx, ref, values);
     }
-    let ws = conversation ? await conversationWorkspace(ctx, conversation) : await resolveWorkspace(ctx, keyOf(ref));
+    // A conversation whose VM was removed restores into a fresh one first (0.18.1+).
+    let ws;
+    if (conversation) {
+        const { reopenConversation } = await import("./conversation-terminal.js");
+        ({ conversation, ws } = await reopenConversation(ctx, conversation, values));
+    }
+    else
+        ws = await resolveWorkspace(ctx, keyOf(ref));
     if (values.reachable !== undefined)
         ws = await ctx.cloud().workspaces.open({ key: ws.key, ...agentReachability(values), wait: false });
     // T3 lists both agents and opens without Claude (it shows Claude as signed out); the Claude apps need it.

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.18.0";
+export declare const CLI_VERSION = "0.18.1";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

package/dist/args.js

@@ -13,7 +13,7 @@ import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
 import { DEFAULT_CHOICE, MODEL_CHOICES } from "./agent-models.js";
-export const CLI_VERSION = '0.18.0';
+export const CLI_VERSION = '0.18.1';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -1288,8 +1288,8 @@ const AGENT_COMMANDS = [
         } },
     { path: ['agents', 'fork'], summary: 'Fork an agent’s memory and disk', positionals: [{ name: 'agent', required: true }, { name: 'name', required: true }], options: WAIT },
     { path: ['agents', 'park'], summary: 'Suspend an agent when idle', positionals: [{ name: 'agent', required: true }], options: { 'when-idle': { type: 'string', value: '<duration>', description: 'Idle grace before suspend (default 1s).' } } },
-    { path: ['agents', 'logs'], summary: 'Tail an agent PTY from its output offset', positionals: [{ name: 'agent', required: true }], options: {
-            app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' },
+    { path: ['agents', 'logs'], summary: 'Tail an agent’s terminal from its output offset: a conversation id (0.18.1+) or an agent workspace key', positionals: [{ name: 'agent', required: true }], options: {
+            app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice; a conversation uses its own).' },
             offset: { type: 'string', value: '<bytes>', description: 'Read from this output byte offset (default last 64 KiB).' },
             follow: { type: 'boolean', description: 'Follow output until interrupted.' },
         } },

package/dist/command-center-actions.js

@@ -11,9 +11,11 @@ import { agentName as gitAgentName } from "./agent-git.js";
 import { randomUUID } from 'node:crypto';
 import { prepareAgentMachine } from "./agent-machine.js";
 import { OperationFailedError } from '@shardflux/sdk';
+import { conversationPtyId, getConversation } from "./conversations.js";
 import { launchConversationProject, launchProjectCommand } from "./conversation-terminal.js";
 import { startThreadOn } from "./thread-on-computer.js";
 import { launchT3 } from "./t3-launch.js";
+const CONVERSATION_ID = /^conv_[a-z0-9]{26}$/;
 /** L9 can register target-specific handlers after detecting the installed applications. */
 export async function availableTargets(ctx) {
     const { HANDLERS } = await import("./handlers.js");
@@ -124,14 +126,38 @@ export const CENTER_HANDLERS = {
     },
     async 'agents logs'(ctx, values, [ref]) {
         if (!ref)
-            throw new UsageError('agents logs requires an agent workspace key');
+            throw new UsageError('agents logs requires a conversation id or an agent workspace key');
         if (values.app !== undefined && values.app !== 'claude' && values.app !== 'codex')
             throw new UsageError('--app must be claude or codex');
-        const ws = await resolveWorkspace(ctx, ref);
+        // A conversation (0.18.1+): its id, or its VM's key. Its PTY is the guest's record, never derived from the VM key.
+        let conversation;
+        let ws;
+        if (CONVERSATION_ID.test(ref)) {
+            conversation = await getConversation(ctx, ref);
+            ws = await ctx.cloud().workspaces.get(conversation.workspace_id);
+        }
+        else {
+            ws = await resolveWorkspace(ctx, ref);
+            if (ws.labels.shard_conversation && CONVERSATION_ID.test(ws.labels.shard_conversation))
+                conversation = await getConversation(ctx, ws.labels.shard_conversation);
+        }
+        if (conversation?.route === 'codex-cloud')
+            throw new UsageError(`Codex Cloud runs this conversation; follow it with shard agents open ${conversation.id}.`);
+        if (conversation?.route === 'acp')
+            throw new UsageError('This conversation runs through its ACP client, which shows its output; it has no terminal to follow.');
+        if (conversation && values.app !== undefined && values.app !== conversation.harness)
+            throw new UsageError(`This conversation runs ${conversation.harness}; omit --app.`);
         const project = ws.labels.repo_remote || ws.labels.shard_project || ws.key;
-        const app = str(values.app) ?? new AgentStateStore(ctx.store.dir).app(project, ws.labels.app === 'codex' ? 'codex' : 'claude');
-        const id = `shard-${ws.labels.agent_pty_name || agentName(ws.key, ws.labels)}-${app}`;
+        const app = conversation?.harness ?? str(values.app) ?? new AgentStateStore(ctx.store.dir).app(project, ws.labels.app === 'codex' ? 'codex' : 'claude');
         const cell = ws.cell({ agentLabel: ctx.agentLabel, ...(ctx.wake ? {} : { wake: null }), transitionTimeoutMs: ctx.wakeTimeoutMs });
+        let id;
+        try {
+            id = conversation ? await conversationPtyId(cell, conversation, ctx.signal) : `shard-${ws.labels.agent_pty_name || agentName(ws.key, ws.labels)}-${app}`;
+        }
+        catch (error) {
+            cell.close();
+            throw error;
+        }
         const offsetText = str(values.offset);
         if (offsetText !== undefined && (!/^\d+$/.test(offsetText) || !Number.isSafeInteger(Number(offsetText))))
             throw new UsageError('--offset must be a nonnegative safe integer');
@@ -175,7 +201,7 @@ export const CENTER_HANDLERS = {
             }
             const remainder = decoder.decode();
             if (ctx.json)
-                ctx.io.stdout.write(json({ pty_id: id, output: output + remainder, nextOffset: cursor.offset, session, exited }));
+                ctx.io.stdout.write(json({ pty_id: id, ...(conversation ? { conversation: { id: conversation.id } } : {}), output: output + remainder, nextOffset: cursor.offset, session, exited }));
             else
                 ctx.io.stdout.write(remainder);
             return 0;

package/dist/conversation-commands.js

@@ -22,7 +22,12 @@ export const CONVERSATION_HANDLERS = {
         return 0;
     },
     async 'conversations get'(ctx, _values, [id]) { const c = await conversationClient(ctx).conversations.get(id); const q = questionLine(c, 200); out(ctx, `${c.title}\n${c.state}\n${c.branch}\n${q ? `${q}\n` : ''}`, c); return 0; },
-    async 'conversations send'(ctx, _values, [id, text]) { const r = await conversationClient(ctx).conversations.send(id, text, { signal: ctx.signal }); out(ctx, `Message sent (${r.seq}).\n`, r); return 0; },
+    // A finished conversation whose VM was removed restores into a fresh one, then takes the message (APIs that do; 0.18.1+).
+    async 'conversations send'(ctx, _values, [id, text]) {
+        const r = await conversationClient(ctx).conversations.send(id, text, { signal: ctx.signal });
+        out(ctx, `${r.restored ? 'Restored\n' : ''}Message sent (${r.seq}).\n`, r);
+        return 0;
+    },
     async 'conversations wait'(ctx, values, [id]) {
         const seconds = values.timeout === undefined ? 900 : Number(values.timeout);
         if (!Number.isInteger(seconds) || seconds < 0 || seconds > 900)

package/dist/conversation-terminal.d.ts

@@ -4,6 +4,16 @@ import type { Values } from './args.js';
 import type { Conversation } from './conversations.js';
 /** Every terminal entry point uses the durable conversation's native harness, worktree and session. */
 export declare function conversationTerminal(ctx: Ctx, ws: Workspace, c: Conversation, project: string, values: Values): Promise<number>;
+/**
+ * A conversation and its VM, for an app to open (Claude Desktop, claude.ai, T3 Code, the menu bar). A conversation
+ * whose VM was removed after it finished restores first (0.18.1+): a fresh VM from its saved branch and transcript, the
+ * same conversation and its session resumed. A terminal conversation's session starts detached, as a new one does, so
+ * the app reaches it at once; the guest starts the others.
+ */
+export declare function reopenConversation(ctx: Ctx, c: Conversation, values: Values): Promise<{
+    conversation: Conversation;
+    ws: Workspace;
+}>;
 /**
  * `shard ./` (and `agents new --in auto`): new conversations open where `agents targets` says (open_in, 0.17.0+): T3
  * Code mode, Claude Desktop or claude.ai for Claude (the conversation's Remote Control session), else this terminal.

package/dist/conversation-terminal.js

@@ -23,6 +23,7 @@ import { launchT3 } from "./t3-launch.js";
 import { openClaudeDesktopSession, remoteControlUrl } from "./agent-target-commands.js";
 import { openUrl } from "./browser.js";
 import { out } from "./commands.js";
+import { progress } from "./progress.js";
 /** Every terminal entry point uses the durable conversation's native harness, worktree and session. */
 export async function conversationTerminal(ctx, ws, c, project, values) {
     if (c.route === 'codex-cloud')
@@ -32,6 +33,27 @@ export async function conversationTerminal(ctx, ws, c, project, values) {
     const pty = ws.labels.shard_conversation && ws.labels.shard_conversation !== c.id ? conversationName(c) : undefined;
     return terminal(ctx, ws, c.harness, conversationName(c), project, values, undefined, c.worktree_path, { id: c.id, session: c.harness_session_id, title: c.title, ...(pty ? { pty } : {}), choice: recordedChoice(c) });
 }
+/**
+ * A conversation and its VM, for an app to open (Claude Desktop, claude.ai, T3 Code, the menu bar). A conversation
+ * whose VM was removed after it finished restores first (0.18.1+): a fresh VM from its saved branch and transcript, the
+ * same conversation and its session resumed. A terminal conversation's session starts detached, as a new one does, so
+ * the app reaches it at once; the guest starts the others.
+ */
+export async function reopenConversation(ctx, c, values) {
+    if (!c.ended_at || c.route === 'codex-cloud')
+        return { conversation: c, ws: await conversationWorkspace(ctx, c) };
+    const restored = await resumeConversation(ctx, c);
+    const ws = await conversationWorkspace(ctx, restored);
+    if (restored.route !== 'terminal') {
+        progress(ctx, 'Restored');
+        return { conversation: restored, ws };
+    }
+    if (!(await savedMachine(ctx))?.template)
+        await syncAgentConfig(ctx, ws);
+    const quiet = { ...ctx, io: { ...ctx.io, stdout: { write: () => true } } };
+    await conversationTerminal(quiet, ws, restored, ws.labels.repo_remote || ws.labels.shard_project || ws.key, { ...values, detach: true });
+    return { conversation: restored, ws };
+}
 /**
  * `shard ./` (and `agents new --in auto`): new conversations open where `agents targets` says (open_in, 0.17.0+): T3
  * Code mode, Claude Desktop or claude.ai for Claude (the conversation's Remote Control session), else this terminal.

package/dist/conversations.d.ts

@@ -1,4 +1,4 @@
-import type { Workspace, WorkspaceView } from '@shardflux/sdk';
+import type { CellClient, Workspace, WorkspaceView } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
 import type { ModelChoice } from './agent-models.js';
 export type Harness = 'claude' | 'codex';
@@ -65,6 +65,13 @@ export interface LocalConversation {
  */
 export declare const conversationEnded: (c: Pick<Conversation, "state" | "ended_at" | "route" | "landed">) => boolean;
 export declare const conversationName: (c: Conversation) => string;
+/**
+ * The managed PTY a conversation's harness runs in (0.18.1+). The guest records it per conversation
+ * (sf-agent's conversation runtime record), which also keeps the PTY a fork inherited from its parent; without a
+ * record it is the one the guest names after the conversation, `shard-<name>-<harness>`. Never the VM key's name: a
+ * conversation's VM is `<project>/conv-<name>`.
+ */
+export declare function conversationPtyId(cell: Pick<CellClient, 'exec'>, c: Conversation, signal?: AbortSignal): Promise<string>;
 export declare function validateConversation(c: Conversation): Conversation;
 export declare function localConversations(ctx: Pick<Ctx, 'store' | 'apiUrl'>): Record<string, LocalConversation>;
 export declare function rememberConversation(ctx: Pick<Ctx, 'store' | 'apiUrl'>, c: Conversation, folder: string, handedOff?: boolean, baseBranch?: string): void;

package/dist/conversations.js

@@ -9,6 +9,7 @@ import { UsageError } from "./errors.js";
 import { conversationClient } from "./conversation-commands.js";
 import { recordSeedSnapshot } from "./files-mirror.js";
 import { rememberTwinSeed, sendTwinSeed, twinCheckoutArgv, twinSeed } from "./worktree-twin.js";
+import { progress } from "./progress.js";
 /**
  * Whether the conversation has ended: its VM was reclaimed, or it was archived or discarded. A finished turn is `done`
  * while its VM still takes the next turn; on Codex Cloud, `done` ends the conversation.
@@ -20,6 +21,37 @@ export const conversationName = (c) => {
         throw new Error('Conversation returned an invalid branch or name');
     return name;
 };
+/** The guest's managed PTY id: `shard-<name>-<app>` (services/guest-agent/internal/agents PtyID). */
+const MANAGED_PTY = /^shard-[a-z0-9][a-z0-9._-]{0,63}-(claude|codex)$/;
+/**
+ * The managed PTY a conversation's harness runs in (0.18.1+). The guest records it per conversation
+ * (sf-agent's conversation runtime record), which also keeps the PTY a fork inherited from its parent; without a
+ * record it is the one the guest names after the conversation, `shard-<name>-<harness>`. Never the VM key's name: a
+ * conversation's VM is `<project>/conv-<name>`.
+ */
+export async function conversationPtyId(cell, c, signal) {
+    const derived = `shard-${conversationName(c)}-${c.harness}`;
+    let stdout;
+    try {
+        const r = await cell.exec.run(['cat', `/home/user/.local/share/shardflux/conversation-runtime/${c.id}.json`], { timeoutMs: 10_000, maxOutputBytes: 4096, ...(signal ? { signal } : {}) });
+        if (r.exitCode !== 0)
+            return derived;
+        stdout = r.stdout;
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw error;
+        return derived;
+    }
+    let recorded;
+    try {
+        recorded = JSON.parse(stdout)?.pty_id;
+    }
+    catch {
+        return derived;
+    }
+    return typeof recorded === 'string' && MANAGED_PTY.test(recorded) && recorded.endsWith(`-${c.harness}`) ? recorded : derived;
+}
 export function validateConversation(c) {
     if (!c || !/^conv_[a-z0-9]{26}$/.test(c.id) || !c.project_id || !c.workspace_id || !c.worktree_path?.startsWith('/home/user/') || /[\0\r\n]/.test(c.worktree_path) || !['claude', 'codex'].includes(c.harness))
         throw new Error('Conversation response omitted its identity or binding');
@@ -120,6 +152,9 @@ export async function restoreConversationBinding(ctx, c, ws) {
     const result = await cell.exec.run(['sf-agent', 'conversation', 'restore', '--args', '{"start":false}'], { cwd: c.worktree_path, env: { SF_CONVERSATION_ID: c.id }, timeoutMs: 120_000, signal: ctx.signal });
     if (result.exitCode !== 0)
         throw new Error(`Conversation restore failed: ${result.stderr.trim()}`);
+    // A conversation whose VM was removed now runs in a fresh one, from its saved branch and transcript (0.18.1+).
+    if (c.restore.kind === 'resume')
+        progress(ctx, 'Restored');
 }
 export async function createConversationRecord(ctx, folder, harness, route, name, allocated, idempotencyKey = randomUUID(), choice = {}) {
     const project = projectIdentity(folder);

package/dist/t3-launch.js

@@ -125,7 +125,9 @@ export async function openT3Conversation(ctx, conversationId, values = {}) {
         return 0;
     }
     // Its VM as T3's SSH environment, with the checks every `agents open t3` makes: --reachable and the cloud Claude login.
-    let ws = await conversationWorkspace(ctx, conversation);
+    // A conversation whose VM was removed restores into a fresh one first (0.18.1+).
+    const { reopenConversation } = await import("./conversation-terminal.js");
+    let { ws } = await reopenConversation(ctx, conversation, values);
     if (values.reachable !== undefined)
         ws = await ctx.cloud().workspaces.open({ key: ws.key, ...agentReachability(values), wait: false });
     // A pooled thread (0.18.0+) runs on the account hub, not on the account's cloud Claude login.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "type": "module",
   "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork serverless agent workspaces.",
   "license": "Apache-2.0",
@@ -58,8 +58,8 @@
     "typescript-eslint": "8.70.1"
   },
   "optionalDependencies": {
-    "@shardflux/desktop-linux-x64": "0.1.0",
-    "@shardflux/desktop-linux-arm64": "0.1.0",
+    "@shardflux/desktop-linux-x64": "0.1.1",
+    "@shardflux/desktop-linux-arm64": "0.1.1",
     "@shardflux/menubar-darwin": "^0.6.0"
   },
   "scripts": {