pi-agent-browser-native 0.3.0 → 0.5.0

package/dist/extensions/agent-browser/lib/results/artifact-manifest.js

@@ -1,3 +1,4 @@
+import { getAgentBrowserSessionIdentityKey } from "../argv-grammar.js";
 import { isRecord } from "../parsing.js";
 export function isPendingRecordingCommand(command, subcommand, kind) {
     return command === "record" && (subcommand === "start" || subcommand === "restart") && kind === "video";
@@ -32,6 +33,16 @@ function isManifestEntry(value) {
         return false;
     if (typeof value.kind !== "string" || value.kind.trim().length === 0)
         return false;
+    for (const key of ["absolutePath", "command", "cwd", "extension", "mediaType", "namespace", "requestedPath", "session", "subcommand"]) {
+        if (value[key] !== undefined && typeof value[key] !== "string")
+            return false;
+    }
+    if (value.evictedAtMs !== undefined && (typeof value.evictedAtMs !== "number" || !Number.isFinite(value.evictedAtMs)))
+        return false;
+    if (value.exists !== undefined && typeof value.exists !== "boolean")
+        return false;
+    if (value.sizeBytes !== undefined && (typeof value.sizeBytes !== "number" || !Number.isFinite(value.sizeBytes) || value.sizeBytes < 0))
+        return false;
     return true;
 }
 export function isSessionArtifactManifest(value) {
@@ -73,7 +84,34 @@ export function formatSessionArtifactRetentionSummary(manifest) {
     return `Session artifacts: ${parts.join(", ")} (${manifest.entries.length}/${manifest.maxEntries} recent).`;
 }
 export function getSessionArtifactManifestEntryKey(entry) {
-    return entry.storageScope === "explicit-path" && entry.absolutePath ? `${entry.storageScope}:${entry.absolutePath}` : `${entry.storageScope}:${entry.path}`;
+    const pathKey = entry.storageScope === "explicit-path" && entry.absolutePath ? `${entry.storageScope}:${entry.absolutePath}` : `${entry.storageScope}:${entry.path}`;
+    const recordingSessionKey = entry.command === "record" && entry.kind === "video" && entry.session
+        ? getAgentBrowserSessionIdentityKey(entry.session, entry.namespace)
+        : undefined;
+    return recordingSessionKey ? `${pathKey}\0${recordingSessionKey}` : pathKey;
+}
+export function retirePendingRecordingManifestEntries(manifest, sessionName, namespace, nowMs = Date.now()) {
+    let changed = false;
+    const sessionKey = sessionName ? getAgentBrowserSessionIdentityKey(sessionName, namespace) : undefined;
+    const entries = manifest.entries.map((entry) => {
+        if (!sessionKey
+            || !entry.session
+            || getAgentBrowserSessionIdentityKey(entry.session, entry.namespace) !== sessionKey
+            || entry.kind !== "video"
+            || !isPendingRecordingCommand(entry.command, entry.subcommand, entry.kind))
+            return entry;
+        changed = true;
+        return { ...entry, retentionState: "missing", subcommand: "close-abandoned" };
+    });
+    if (!changed)
+        return manifest;
+    return {
+        ...manifest,
+        entries,
+        evictedCount: entries.filter((entry) => entry.retentionState === "evicted").length,
+        liveCount: entries.filter((entry) => entry.retentionState === "live").length,
+        updatedAtMs: nowMs,
+    };
 }
 export function mergeSessionArtifactManifest(options) {
     const nowMs = options.nowMs ?? Date.now();
@@ -82,13 +120,31 @@ export function mergeSessionArtifactManifest(options) {
     for (const entry of options.base?.entries ?? []) {
         byPath.set(getSessionArtifactManifestEntryKey(entry), entry);
     }
-    for (const entry of options.entries ?? []) {
+    const orderedEntries = (options.entries ?? [])
+        .map((entry, index) => ({ entry, index }))
+        .sort((left, right) => left.entry.createdAtMs - right.entry.createdAtMs || left.index - right.index)
+        .map(({ entry }) => entry);
+    for (const entry of orderedEntries) {
         const key = getSessionArtifactManifestEntryKey(entry);
+        if (entry.command === "record" && entry.kind === "video") {
+            const entrySessionKey = entry.session ? getAgentBrowserSessionIdentityKey(entry.session, entry.namespace) : undefined;
+            for (const [candidateKey, candidate] of byPath) {
+                const sameRecordingSession = entrySessionKey === undefined
+                    ? candidate.session === undefined
+                    : candidate.session !== undefined && getAgentBrowserSessionIdentityKey(candidate.session, candidate.namespace) === entrySessionKey;
+                if (candidateKey !== key
+                    && sameRecordingSession
+                    && candidate.kind === "video"
+                    && isPendingRecordingCommand(candidate.command, candidate.subcommand, candidate.kind)) {
+                    byPath.delete(candidateKey);
+                }
+            }
+        }
         const existing = byPath.get(key);
         byPath.set(key, {
             ...existing,
             ...entry,
-            createdAtMs: existing?.createdAtMs ?? entry.createdAtMs,
+            createdAtMs: entry.command === "record" && entry.kind === "video" ? entry.createdAtMs : existing?.createdAtMs ?? entry.createdAtMs,
             evictedAtMs: entry.retentionState === "evicted" ? (entry.evictedAtMs ?? nowMs) : entry.evictedAtMs,
         });
     }
@@ -98,7 +154,9 @@ export function mergeSessionArtifactManifest(options) {
         .sort((left, right) => {
         const leftTime = left.evictedAtMs ?? left.createdAtMs;
         const rightTime = right.evictedAtMs ?? right.createdAtMs;
-        return rightTime - leftTime || left.path.localeCompare(right.path);
+        return rightTime - leftTime
+            || Number(isPendingRecordingCommand(right.command, right.subcommand, right.kind)) - Number(isPendingRecordingCommand(left.command, left.subcommand, left.kind))
+            || left.path.localeCompare(right.path);
     })
         .slice(0, maxEntries);
     return {

package/dist/extensions/agent-browser/lib/results/categories.js

@@ -5,6 +5,8 @@ function hasUnverifiedFileArtifact(artifacts) {
 export function classifyAgentBrowserSuccessCategory(options) {
     if (options.inspection)
         return "inspection";
+    if ((options.artifacts ?? []).some(isPendingRecordingArtifact))
+        return "artifact-pending";
     if ((options.artifacts ?? []).length > 0)
         return hasUnverifiedFileArtifact(options.artifacts) ? "artifact-unverified" : "artifact-saved";
     if (options.savedFile)
@@ -19,6 +21,9 @@ export function classifyAgentBrowserFailureCategory(options) {
     // missed control named "Confirmation required" still gets selector recovery.
     if (options.confirmationRequired)
         return "confirmation-required";
+    // Canonical upstream prefix first: lastUrl can contain aborted / policy-blocked / about:blank.
+    if (/\btab_gone:/i.test(text))
+        return "tab-gone";
     // Upstream 0.32.4+ locator misses keep detail and may echo getByRole/getByText or Names seen lists.
     // Evaluate before text-derived timeout/confirmation so accessible-name substrings cannot suppress recovery.
     const isUpstreamLocatorMiss = /\bNo element found:\s*(?:getBy[A-Za-z]+|role=|text=|label=|placeholder=|alt=|title=|testid=)/i.test(text) ||
@@ -48,7 +53,7 @@ export function classifyAgentBrowserFailureCategory(options) {
         return "policy-blocked";
     if (/cleanup failed|cleanup.*partial|partial cleanup|remaining resources/i.test(text))
         return "cleanup-failed";
-    if (options.validationError)
+    if (options.validationError || /Agent-browser Unix socket path would be|Agent-browser socket storage .* is unusable/i.test(text))
         return "validation-error";
     if (options.tabDrift || /could not re-select the intended tab|about:blank|selected tab looks wrong|tab drift|tab.*wrong/i.test(text))
         return "tab-drift";

package/dist/extensions/agent-browser/lib/results/next-actions.js

@@ -1,15 +1,15 @@
 export function withOptionalNamespaceArgs(namespace, args) {
-    return namespace && args[0] !== "--namespace" ? ["--namespace", namespace, ...args] : args;
+    return namespace !== undefined && args[0] !== "--namespace" ? ["--namespace", namespace, ...args] : args;
 }
 export function withOptionalSessionArgs(sessionName, args) {
-    if (!sessionName || args[0] === "--session")
+    if (!sessionName || args[0] === "--session" || (args[0] === "--namespace" && args[2] === "--session"))
         return args;
-    if (args[0] === "--namespace" && args[1] && args[2] !== "--session")
+    if (args[0] === "--namespace" && args.length >= 2)
         return [args[0], args[1], "--session", sessionName, ...args.slice(2)];
     return ["--session", sessionName, ...args];
 }
 export function applyNamespaceToNextActions(actions, namespace) {
-    if (!namespace || !actions)
+    if (namespace === undefined || !actions)
         return actions;
     return actions.map((action) => {
         const args = action.params?.args;
@@ -19,6 +19,18 @@ export function applyNamespaceToNextActions(actions, namespace) {
         return networkSourceLookup ? { ...action, params: { ...action.params, networkSourceLookup: { ...networkSourceLookup, namespace } } } : action;
     });
 }
+export function applySessionToNextActions(actions, sessionName) {
+    if (!sessionName || !actions)
+        return actions;
+    return actions.map((action) => {
+        // Fresh-session actions deliberately target a new session; the planner ignores sessionMode when an
+        // explicit --session is present, so prefixing one here would silently downgrade them to reuse.
+        if (action.params?.sessionMode === "fresh")
+            return action;
+        const args = action.params?.args;
+        return args ? { ...action, params: { ...action.params, args: withOptionalSessionArgs(sessionName, args) } } : action;
+    });
+}
 export function buildNextToolAction(options) {
     return {
         id: options.id,
@@ -48,7 +60,9 @@ export function isStandaloneSnapshotNextAction(action) {
     const args = action.params?.args;
     if (!args || action.params?.stdin)
         return false;
-    const commandIndex = args[0] === "--session" ? 2 : 0;
+    let commandIndex = args[0] === "--namespace" ? 2 : 0;
+    if (args[commandIndex] === "--session")
+        commandIndex += 2;
     return args[commandIndex] === "snapshot";
 }
 export function alignPageChangeSummaryNextActionIds(summary, nextActions) {

package/dist/extensions/agent-browser/lib/results/presentation/artifacts.js

@@ -1,7 +1,8 @@
 import { readFile, stat } from "node:fs/promises";
 import { extname, resolve } from "node:path";
+import { getAgentBrowserSessionIdentityKey } from "../../argv-grammar.js";
 import { isRecord, parsePositiveInteger } from "../../parsing.js";
-import { formatSessionArtifactRetentionSummary, isPendingRecordingArtifact, isPendingRecordingCommand, mergeSessionArtifactManifest, } from "../artifact-manifest.js";
+import { formatSessionArtifactRetentionSummary, getSessionArtifactManifestEntryKey, isPendingRecordingArtifact, isPendingRecordingCommand, mergeSessionArtifactManifest, } from "../artifact-manifest.js";
 import { classifyAgentBrowserSuccessCategory } from "../categories.js";
 const IMAGE_EXTENSION_TO_MIME_TYPE = {
     ".gif": "image/gif",
@@ -12,6 +13,7 @@ const IMAGE_EXTENSION_TO_MIME_TYPE = {
 };
 const INLINE_IMAGE_MAX_BYTES_ENV = "PI_AGENT_BROWSER_INLINE_IMAGE_MAX_BYTES";
 const DEFAULT_INLINE_IMAGE_MAX_BYTES = 5 * 1_024 * 1_024;
+const ARTIFACT_MTIME_TOLERANCE_MS = 2_000;
 function getImageMimeType(filePath) {
     const extension = extname(filePath).toLowerCase();
     return IMAGE_EXTENSION_TO_MIME_TYPE[extension];
@@ -36,14 +38,11 @@ function appendPresentationNotice(presentation, message) {
 function shouldAppendArtifactRetentionNotice(entries) {
     return entries.some((entry) => entry.retentionState === "evicted" || entry.storageScope !== "explicit-path");
 }
-function getManifestEntryKey(entry) {
-    return entry.storageScope === "explicit-path" && entry.absolutePath ? `${entry.storageScope}:${entry.absolutePath}` : `${entry.storageScope}:${entry.path}`;
-}
 export function manifestHasNewNoticeWorthyEntries(base, current) {
     if (!current)
         return false;
-    const baseKeys = new Set((base?.entries ?? []).map(getManifestEntryKey));
-    return current.entries.some((entry) => !baseKeys.has(getManifestEntryKey(entry)) && (entry.retentionState === "evicted" || entry.storageScope !== "explicit-path"));
+    const baseKeys = new Set((base?.entries ?? []).map(getSessionArtifactManifestEntryKey));
+    return current.entries.some((entry) => !baseKeys.has(getSessionArtifactManifestEntryKey(entry)) && (entry.retentionState === "evicted" || entry.storageScope !== "explicit-path"));
 }
 export function applyArtifactManifest(presentation, baseManifest, entries) {
     if (entries.length === 0)
@@ -86,6 +85,9 @@ const ARTIFACT_EXTENSION_TO_MEDIA_TYPE = {
     ".zip": "application/zip",
     ...IMAGE_EXTENSION_TO_MIME_TYPE,
 };
+function isDownloadWaitSubcommand(subcommand) {
+    return subcommand === "--download" || subcommand === "-d";
+}
 function getArtifactKind(commandInfo) {
     if (commandInfo.command === "screenshot")
         return "image";
@@ -95,7 +97,7 @@ function getArtifactKind(commandInfo) {
         return "pdf";
     if (commandInfo.command === "download")
         return "download";
-    if (commandInfo.command === "wait" && commandInfo.subcommand === "--download")
+    if (commandInfo.command === "wait" && isDownloadWaitSubcommand(commandInfo.subcommand))
         return "download";
     if (commandInfo.command === "state" && commandInfo.subcommand === "save")
         return "file";
@@ -135,6 +137,11 @@ function extractPathStrings(data) {
     }
     return [...new Set(paths)];
 }
+function artifactMtimeIsOutsideCommandWindow(updatedAtMs, minUpdatedAtMs, maxUpdatedAtMs) {
+    return minUpdatedAtMs !== undefined
+        && (updatedAtMs < minUpdatedAtMs - ARTIFACT_MTIME_TOLERANCE_MS
+            || (maxUpdatedAtMs !== undefined && updatedAtMs > maxUpdatedAtMs + ARTIFACT_MTIME_TOLERANCE_MS));
+}
 async function buildFileArtifactMetadata(options) {
     const kind = getArtifactKind(options.commandInfo);
     if (!kind) {
@@ -146,11 +153,16 @@ async function buildFileArtifactMetadata(options) {
     const pendingRecording = isPendingRecordingCommand(options.commandInfo.command, options.commandInfo.subcommand, kind);
     let exists;
     let sizeBytes;
+    let stale = false;
+    let updatedAtMs;
     if (!pendingRecording) {
         try {
             const fileStats = await stat(absolutePath);
             exists = true;
             sizeBytes = fileStats.size;
+            updatedAtMs = fileStats.mtimeMs;
+            const commandCreatesArtifact = !(options.commandInfo.command === "wait" && isDownloadWaitSubcommand(options.commandInfo.subcommand));
+            stale = commandCreatesArtifact && artifactMtimeIsOutsideCommandWindow(updatedAtMs, options.artifactMinUpdatedAtMs, options.artifactMaxUpdatedAtMs);
         }
         catch {
             exists = false;
@@ -165,31 +177,33 @@ async function buildFileArtifactMetadata(options) {
         extension,
         kind,
         mediaType: extension ? ARTIFACT_EXTENSION_TO_MEDIA_TYPE[extension] : undefined,
+        namespace: options.namespace,
         path: displayPath,
         recordingState: pendingRecording ? "openRecording" : undefined,
         requestedPath: options.artifactRequest?.path,
         session: options.sessionName,
         sizeBytes,
-        status: options.artifactRequest?.status ?? (pendingRecording ? "pending" : exists === false ? "missing" : "saved"),
+        status: pendingRecording ? "pending" : exists === false ? "missing" : stale ? "stale" : options.artifactRequest?.status ?? "saved",
         subcommand: options.commandInfo.subcommand,
         tempPath: options.artifactRequest?.tempPath,
+        updatedAtMs,
         willExistOnStop: pendingRecording ? true : undefined,
     };
 }
 async function buildPreviousRestartRecordingArtifact(options) {
     if (options.commandInfo.command !== "record" || options.commandInfo.subcommand !== "restart")
         return undefined;
+    const sessionKey = options.sessionName ? getAgentBrowserSessionIdentityKey(options.sessionName, options.namespace) : undefined;
     const previousRecording = options.artifactManifest?.entries.find((entry) => (entry.command === "record" &&
         (entry.subcommand === "start" || entry.subcommand === "restart") &&
         entry.kind === "video" &&
-        (!options.sessionName || !entry.session || entry.session === options.sessionName) &&
-        !options.currentPaths.has(entry.path) &&
-        (!entry.absolutePath || !options.currentPaths.has(entry.absolutePath))));
+        (!sessionKey || (entry.session && getAgentBrowserSessionIdentityKey(entry.session, entry.namespace) === sessionKey))));
     if (!previousRecording)
         return undefined;
     const absolutePath = previousRecording.absolutePath ?? resolve(options.cwd, previousRecording.path);
     try {
         const fileStats = await stat(absolutePath);
+        const stale = artifactMtimeIsOutsideCommandWindow(fileStats.mtimeMs, options.artifactMinUpdatedAtMs, options.artifactMaxUpdatedAtMs);
         return {
             absolutePath,
             artifactType: "video",
@@ -199,23 +213,39 @@ async function buildPreviousRestartRecordingArtifact(options) {
             extension: previousRecording.extension ?? (extname(absolutePath).toLowerCase() || undefined),
             kind: "video",
             mediaType: previousRecording.mediaType,
+            namespace: previousRecording.namespace ?? options.namespace,
             path: previousRecording.path,
             requestedPath: previousRecording.requestedPath,
             session: previousRecording.session ?? options.sessionName,
             sizeBytes: fileStats.size,
-            status: "saved",
+            status: stale ? "stale" : "saved",
             subcommand: "restart-previous",
+            updatedAtMs: fileStats.mtimeMs,
         };
     }
     catch {
-        return undefined;
+        return {
+            absolutePath,
+            artifactType: "video",
+            command: "record",
+            cwd: previousRecording.cwd ?? options.cwd,
+            exists: false,
+            extension: previousRecording.extension ?? (extname(absolutePath).toLowerCase() || undefined),
+            kind: "video",
+            mediaType: previousRecording.mediaType,
+            namespace: previousRecording.namespace ?? options.namespace,
+            path: previousRecording.path,
+            requestedPath: previousRecording.requestedPath,
+            session: previousRecording.session ?? options.sessionName,
+            status: "missing",
+            subcommand: "restart-previous",
+        };
     }
 }
 export async function extractFileArtifacts(options) {
     const candidates = extractPathStrings(options.data);
     const currentArtifacts = (await Promise.all(candidates.map((path) => buildFileArtifactMetadata({ ...options, path })))).filter((artifact) => artifact !== undefined);
-    const currentPaths = new Set(currentArtifacts.flatMap((artifact) => [artifact.path, artifact.absolutePath]));
-    const previousRestartRecordingArtifact = await buildPreviousRestartRecordingArtifact({ artifactManifest: options.artifactManifest, commandInfo: options.commandInfo, currentPaths, cwd: options.cwd, sessionName: options.sessionName });
+    const previousRestartRecordingArtifact = await buildPreviousRestartRecordingArtifact({ artifactManifest: options.artifactManifest, artifactMaxUpdatedAtMs: options.artifactMaxUpdatedAtMs, artifactMinUpdatedAtMs: options.artifactMinUpdatedAtMs, commandInfo: options.commandInfo, cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName });
     return previousRestartRecordingArtifact ? [previousRestartRecordingArtifact, ...currentArtifacts] : currentArtifacts;
 }
 export function buildManifestEntriesForFileArtifacts(artifacts, nowMs = Date.now()) {
@@ -228,9 +258,10 @@ export function buildManifestEntriesForFileArtifacts(artifacts, nowMs = Date.now
         extension: artifact.extension,
         kind: artifact.kind,
         mediaType: artifact.mediaType,
+        namespace: artifact.namespace,
         path: artifact.path,
         requestedPath: artifact.requestedPath,
-        retentionState: artifact.exists === false ? "missing" : "live",
+        retentionState: artifact.exists === false || artifact.status === "stale" ? "missing" : "live",
         session: artifact.session,
         sizeBytes: artifact.sizeBytes,
         storageScope: "explicit-path",
@@ -238,6 +269,9 @@ export function buildManifestEntriesForFileArtifacts(artifacts, nowMs = Date.now
     }));
 }
 export function isManifestFileArtifact(artifact) {
+    if (artifact.status === "stale") {
+        return artifact.kind === "video" && artifact.command === "record" && artifact.subcommand === "restart-previous";
+    }
     return artifact.kind === "video" && artifact.command === "record" ? true : !isPendingRecordingArtifact(artifact);
 }
 function getArtifactVerificationEntry(artifact) {
@@ -259,20 +293,24 @@ function getArtifactVerificationEntry(artifact) {
             willExistOnStop: artifact.willExistOnStop ?? true,
         };
     }
-    const state = artifact.exists === true
-        ? "verified"
-        : artifact.exists === false
-            ? "missing"
-            : "unverified";
+    const state = artifact.status === "stale"
+        ? "unverified"
+        : artifact.exists === true
+            ? "verified"
+            : artifact.exists === false
+                ? "missing"
+                : "unverified";
     return {
         absolutePath: artifact.absolutePath,
         exists: artifact.exists,
         kind: artifact.kind,
-        limitation: state === "missing"
-            ? "The wrapper did not find the reported artifact at absolutePath. Treat the path as unverified until recovered or regenerated."
-            : state === "unverified"
-                ? "The wrapper could not prove local filesystem existence for this artifact."
-                : undefined,
+        limitation: artifact.status === "stale"
+            ? "The reported path's modification time fell outside this command's bounded artifact window. Treat the artifact as stale until regenerated."
+            : state === "missing"
+                ? "The wrapper did not find the reported artifact at absolutePath. Treat the path as unverified until recovered or regenerated."
+                : state === "unverified"
+                    ? "The wrapper could not prove local filesystem existence for this artifact."
+                    : undefined,
         mediaType: artifact.mediaType,
         path: artifact.path,
         requestedPath: artifact.requestedPath,
@@ -281,6 +319,7 @@ function getArtifactVerificationEntry(artifact) {
         state,
         status: artifact.status,
         storageScope: "explicit-path",
+        updatedAtMs: artifact.updatedAtMs,
     };
 }
 function getManifestVerificationEntry(entry) {
@@ -335,17 +374,19 @@ export function buildArtifactVerificationSummary(artifacts, manifest, manifestPa
     };
 }
 export function hasMissingFileArtifact(artifacts) {
-    return (artifacts ?? []).some((artifact) => !isPendingRecordingArtifact(artifact) && artifact.exists === false);
+    return (artifacts ?? []).some((artifact) => !isPendingRecordingArtifact(artifact) && (artifact.exists === false || artifact.status === "stale"));
 }
 export function formatMissingArtifactFailureText(artifacts) {
-    const missingArtifacts = (artifacts ?? []).filter((artifact) => !isPendingRecordingArtifact(artifact) && artifact.exists === false);
-    if (missingArtifacts.length === 0)
+    const failedArtifacts = (artifacts ?? []).filter((artifact) => !isPendingRecordingArtifact(artifact) && (artifact.exists === false || artifact.status === "stale"));
+    if (failedArtifacts.length === 0)
         return undefined;
-    if (missingArtifacts.length === 1) {
-        const artifact = missingArtifacts[0];
-        return `Artifact verification failed: requested ${artifact.kind} was not found at ${artifact.absolutePath}.`;
+    if (failedArtifacts.length === 1) {
+        const artifact = failedArtifacts[0];
+        return artifact.status === "stale"
+            ? `Artifact verification failed: requested ${artifact.kind} path ${artifact.absolutePath} has a modification time outside the current command window.`
+            : `Artifact verification failed: requested ${artifact.kind} was not found at ${artifact.absolutePath}.`;
     }
-    return `Artifact verification failed: ${missingArtifacts.length} requested artifacts were not found on disk.`;
+    return `Artifact verification failed: ${failedArtifacts.length} requested artifacts were missing or stale.`;
 }
 export function classifyPresentationSuccessCategory(options) {
     if ((options.artifactVerification?.missingCount ?? 0) > 0 || (options.artifactVerification?.unverifiedCount ?? 0) > 0) {
@@ -357,9 +398,9 @@ function formatArtifactLabel(artifact) {
     switch (artifact.kind) {
         case "download":
             if (artifact.exists !== true) {
-                return artifact.command === "wait" && artifact.subcommand === "--download" ? "Download event reported; file not verified" : "Download reported; file not verified";
+                return artifact.command === "wait" && isDownloadWaitSubcommand(artifact.subcommand) ? "Download event reported; file not verified" : "Download reported; file not verified";
             }
-            return artifact.command === "wait" && artifact.subcommand === "--download" ? "Download saved and verified" : "Downloaded file verified";
+            return artifact.command === "wait" && isDownloadWaitSubcommand(artifact.subcommand) ? "Download saved and verified" : "Downloaded file verified";
         case "file":
             return artifact.command === "state" ? "State file" : "Saved file";
         case "har":
@@ -375,11 +416,16 @@ function formatArtifactLabel(artifact) {
         case "trace":
             return "Saved trace";
         case "video":
-            if (artifact.command === "record" && artifact.subcommand === "restart-previous")
+            if (artifact.command === "record" && artifact.subcommand === "restart-previous") {
+                if (artifact.status === "stale")
+                    return "Previous recording stale";
+                if (artifact.exists === false)
+                    return "Previous recording missing";
                 return "Previous recording saved";
+            }
             if (!isPendingRecordingArtifact(artifact))
                 return "Saved recording";
-            return artifact.subcommand === "restart" ? "Recording restarted; output will be written on stop" : "Recording started; output will be written on stop";
+            return artifact.subcommand === "restart" ? "Recording restarted; output will be written on stop" : "Recording started in a fresh active page; output will be written on stop";
     }
 }
 export function formatArtifactSummary(artifacts) {
@@ -409,6 +455,7 @@ export function formatArtifactMetadataLines(artifacts) {
                 `Status: ${artifact.status ?? "pending"}`,
                 `Recording state: ${artifact.recordingState ?? "openRecording"}`,
                 `Will exist on stop: ${artifact.willExistOnStop !== false}`,
+                artifact.subcommand === "start" ? "Page state: record start uses a fresh active page for video capture; prior in-page DOM and JavaScript state does not carry over. Take a fresh snapshot before continuing." : undefined,
                 artifact.session ? `Session: ${artifact.session}` : undefined,
                 artifact.cwd ? `CWD: ${artifact.cwd}` : undefined,
                 `Machine data: details.artifacts[${index}]`,
@@ -433,7 +480,7 @@ export function formatArtifactMetadataLines(artifacts) {
     });
 }
 function isDownloadWaitCommand(commandInfo) {
-    return commandInfo.command === "wait" && commandInfo.subcommand === "--download";
+    return commandInfo.command === "wait" && isDownloadWaitSubcommand(commandInfo.subcommand);
 }
 function extractSavedFilePath(data) {
     return typeof data.path === "string" && data.path.trim().length > 0 ? data.path : undefined;