opencode-missions 0.1.0 → 0.1.1

package/README.md

@@ -1,32 +1,62 @@
 # opencode-missions
 
-OpenCode plugin for project-local mission planning, delegated feature execution, structured worker handoffs, and milestone validation. It re-implements the mission lifecycle locally and does not require Droid CLI, Factory runtime files, or any external mission service.
+OpenCode plugin for mission planning, delegated feature execution, structured worker handoffs, and milestone validation. It re-implements the mission lifecycle locally and does not require Droid CLI, Factory runtime files, or any external mission service.
+
+## What it provides
+
+- OpenCode mission tools for creating, planning, running, pausing, resuming, and completing missions
+- One-worker-at-a-time feature delegation through OpenCode child sessions
+- Structured worker handoffs with verification evidence, test coverage notes, and discovered issues
+- Automatic scrutiny and user-testing validator features after each completed milestone
+- Completion gates that block unresolved handoff items, failed validation assertions, and missing milestone validators
+- Optional `/mission` command, orchestrator agent, worker agent, validator agents, and mission orchestration skill
+- Global mission state under Factory-compatible storage when Droid is installed, or OpenCode storage otherwise
 
 ## Install
 
-Add the npm plugin to `opencode.json`:
+For the fastest setup in the current project:
+
+```sh
+npm install -g opencode-missions
+opencode-missions install
+```
+
+Then add the npm plugin to `opencode.json`:
 
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-missions"]
+  "plugin": ["opencode-missions@latest"]
 }
 ```
 
-OpenCode installs npm plugins automatically with Bun at startup.
+For a different project directory:
 
-Optional agent, command, and skill assets are included under `opencode/`. To install them into the current project:
-
-```bash
-bunx opencode-missions install
+```sh
+opencode-missions install /path/to/project
 ```
 
-That copies:
+The install command is idempotent. It copies optional OpenCode assets into the project:
 
 - `opencode/agents/*` to `.opencode/agents/`
 - `opencode/commands/*` to `.opencode/commands/`
 - `opencode/skills/*` to `.opencode/skills/`
 
+OpenCode installs npm plugins automatically with Bun at startup after the package is listed in config.
+
+## Manual config
+
+If you do not want the optional assets, only add the plugin entry:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-missions@latest"]
+}
+```
+
+If you want the included `/mission` command and agent presets without using the installer, copy the package `opencode/agents`, `opencode/commands`, and `opencode/skills` directories into your project's `.opencode/` directory.
+
 ## Usage
 
 After enabling the plugin, use the mission tools directly or install the included `/mission` command and mission agents:
@@ -40,10 +70,39 @@ The orchestrator creates a mission workspace, writes mission artifacts and featu
 Mission state is stored under:
 
 ```text
-.opencode/droid-missions/missions/
+~/.factory/missions/
 ```
 
-The storage path intentionally remains stable for compatibility with the recovered mission lifecycle.
+when a `droid` executable is available on `PATH`. If Droid is not installed, the plugin falls back to:
+
+```text
+~/.opencode/missions/
+```
+
+`FACTORY_HOME_OVERRIDE` is respected for isolated development and tests.
+When Factory environment variables indicate a non-production environment and `droid` is installed, the Factory-compatible root is `~/.factory-dev/missions/`.
+
+Missions created by earlier versions under project-local `.opencode/droid-missions/missions/` are not moved automatically. Move or recreate those missions explicitly if you need them in global storage.
+
+## Local development install
+
+From this repo:
+
+```sh
+bun install
+bun run build
+npm pack
+```
+
+Then point OpenCode at the packed tarball through the plugin array:
+
+```jsonc
+{
+  "plugin": ["opencode-missions@file:/absolute/path/opencode-missions-0.1.0.tgz"]
+}
+```
+
+Direct local source installs are useful for debugging, but npm/tarball installs better match how OpenCode resolves plugin dependencies.
 
 ## Tools
 
@@ -76,3 +135,11 @@ npm version patch
 git push --follow-tags
 npm publish --access public
 ```
+
+## Troubleshooting
+
+- **Mission tools are not visible:** confirm `opencode.json` contains `"plugin": ["opencode-missions@latest"]`, then restart OpenCode.
+- **`/mission` is not visible:** run `opencode-missions install` in the project root or copy the optional assets manually.
+- **A mission will not complete:** run `droid_mission_status` and resolve pending features, validation features, handoff issues, or validation-state assertions.
+- **Direct edits to mission state fail:** use the mission tools instead of editing global mission system files such as `state.json`, `features.json`, or `progress_log.jsonl`.
+- **Local tarball install cannot find dependencies:** use `npm pack` and reference the packed `.tgz`, or install from npm with `opencode-missions@latest`.

package/dist/droid-missions/paths.d.ts

@@ -1,6 +1,12 @@
-export declare const STORAGE_DIR: string;
+export declare const OPENCODE_STORAGE_DIR = ".opencode";
+export declare const FACTORY_STORAGE_DIR = ".factory";
+export declare const FACTORY_DEV_STORAGE_DIR = ".factory-dev";
 export declare const MISSIONS_DIR = "missions";
-export declare function missionStorageRoot(projectRoot: string): string;
+export declare function hasDroidOnPath(): boolean;
+export declare function factoryMissionStorageRoot(): string;
+export declare function opencodeMissionStorageRoot(): string;
+export declare function missionStorageKind(): "factory" | "opencode";
+export declare function missionStorageRoot(_projectRoot: string): string;
 export declare function missionsRoot(projectRoot: string): string;
 export declare function sanitizeMissionId(input: string): string;
 export declare function createMissionId(title: string, now: string): string;

package/dist/droid-missions/store.d.ts

@@ -1,4 +1,7 @@
 import type { FeatureHandoff, MissionCreateArgs, MissionFeature, MissionSnapshot, MissionState, ProgressEntry, StoredHandoff } from "./types";
+export declare class MissionNotFoundError extends Error {
+    constructor(missionId: string, missionsRootPath: string);
+}
 export declare class MissionStore {
     readonly projectRoot: string;
     constructor(projectRoot: string);

package/dist/droid-missions/types.d.ts

@@ -7,6 +7,7 @@ export type MissionState = {
     title: string;
     goal: string;
     status: MissionStatus;
+    state?: MissionStatus;
     workingDirectory: string;
     createdAt: string;
     updatedAt: string;
@@ -15,6 +16,7 @@ export type MissionState = {
     activeWorkerSessionId?: string;
     pauseReason?: string;
     lastMessage?: string;
+    artifactLayoutVersion?: number;
 };
 export type FeaturePlanInput = {
     id: string;
@@ -22,7 +24,7 @@ export type FeaturePlanInput = {
     skillName: string;
     milestone: string;
     preconditions?: string[];
-    expectedBehavior: string;
+    expectedBehavior: string | string[];
     verificationSteps?: string[];
     fulfills?: string[];
 };
@@ -32,6 +34,7 @@ export type MissionFeature = FeaturePlanInput & {
     fulfills: string[];
     status: FeatureStatus;
     workerSessionId?: string;
+    workerSessionIds?: string[];
     startedAt?: string;
     completedAt?: string;
     isValidation?: boolean;
@@ -102,10 +105,13 @@ export type StoredHandoff = FeatureHandoff & {
     createdAt: string;
     dismissedAt?: string;
     dismissalReason?: string;
+    timestamp?: string;
+    handoff?: FeatureHandoff;
 };
 export type ProgressEntry = {
     type: "mission_accepted" | "mission_paused" | "mission_resumed" | "mission_run_started" | "worker_started" | "worker_selected_feature" | "worker_completed" | "worker_failed" | "worker_paused" | "handoff_items_dismissed" | "milestone_validation_triggered" | "mission_completed" | "features_written" | "artifact_written";
     at: string;
+    timestamp?: string;
     missionId: string;
     featureId?: string;
     workerSessionId?: string;
@@ -118,6 +124,11 @@ export type MissionSnapshot = {
     features: MissionFeature[];
     handoffs: StoredHandoff[];
     progress: ProgressEntry[];
+    metadata?: {
+        storageKind: "factory" | "opencode";
+        featureCounts: Record<FeatureStatus, number>;
+        resumable: boolean;
+    };
 };
 export type MissionCreateArgs = {
     missionId?: string;

package/dist/index.js

@@ -1,11 +1,108 @@
 // @bun
 // src/index.ts
 import { tool } from "@opencode-ai/plugin";
+import { realpathSync } from "fs";
 import path3 from "path";
 
+// src/droid-missions/paths.ts
+import { accessSync, constants } from "fs";
+import { homedir } from "os";
+import path from "path";
+var OPENCODE_STORAGE_DIR = ".opencode";
+var FACTORY_STORAGE_DIR = ".factory";
+var FACTORY_DEV_STORAGE_DIR = ".factory-dev";
+var MISSIONS_DIR = "missions";
+function factoryHome() {
+  return process.env.FACTORY_HOME_OVERRIDE || homedir();
+}
+function factoryDirName() {
+  const env = process.env.FACTORY_ENV ?? process.env.NEXT_PUBLIC_ENV;
+  if (env && env.toLowerCase().trim() !== "production") {
+    return FACTORY_DEV_STORAGE_DIR;
+  }
+  return FACTORY_STORAGE_DIR;
+}
+function executableNames(command) {
+  if (process.platform !== "win32")
+    return [command];
+  const extensions = (process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean);
+  return [command, ...extensions.map((extension) => `${command}${extension}`)];
+}
+function hasDroidOnPath() {
+  const pathEnv = process.env.PATH;
+  if (!pathEnv)
+    return false;
+  for (const entry of pathEnv.split(path.delimiter)) {
+    if (!entry)
+      continue;
+    for (const executable of executableNames("droid")) {
+      try {
+        accessSync(path.join(entry, executable), constants.X_OK);
+        return true;
+      } catch {}
+    }
+  }
+  return false;
+}
+function factoryMissionStorageRoot() {
+  return path.join(factoryHome(), factoryDirName());
+}
+function opencodeMissionStorageRoot() {
+  return path.join(factoryHome(), OPENCODE_STORAGE_DIR);
+}
+function missionStorageKind() {
+  return hasDroidOnPath() ? "factory" : "opencode";
+}
+function missionStorageRoot(_projectRoot) {
+  return missionStorageKind() === "factory" ? factoryMissionStorageRoot() : opencodeMissionStorageRoot();
+}
+function missionsRoot(projectRoot) {
+  return path.join(missionStorageRoot(projectRoot), MISSIONS_DIR);
+}
+function sanitizeMissionId(input) {
+  const value = input.trim();
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value)) {
+    throw new Error("Invalid mission id. Use 1-128 letters, numbers, dots, underscores, or hyphens.");
+  }
+  return value;
+}
+function createMissionId(title, now) {
+  const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48) || "mission";
+  const stamp = new Date(now).getTime().toString(36);
+  return sanitizeMissionId(`${slug}-${stamp}`);
+}
+function missionDir(projectRoot, missionId) {
+  return path.join(missionsRoot(projectRoot), sanitizeMissionId(missionId));
+}
+function toMissionRelativePath(relativePath) {
+  const normalized = relativePath.replaceAll("\\", "/").replace(/^\/+/, "");
+  if (normalized === "" || normalized.startsWith("../") || normalized.includes("/../") || normalized === "..") {
+    throw new Error(`Invalid mission artifact path: ${relativePath}`);
+  }
+  return path.posix.normalize(normalized);
+}
+function assertInside(parent, child) {
+  const resolvedParent = path.resolve(parent);
+  const resolvedChild = path.resolve(child);
+  if (resolvedChild !== resolvedParent && !resolvedChild.startsWith(resolvedParent + path.sep)) {
+    throw new Error(`Path escapes mission directory: ${child}`);
+  }
+}
+function isMissionSystemFile(relativePath) {
+  const systemFiles = new Set([
+    "state.json",
+    "features.json",
+    "progress_log.jsonl",
+    "handoffs.jsonl",
+    "worker-transcripts.jsonl",
+    "working_directory.txt"
+  ]);
+  return systemFiles.has(toMissionRelativePath(relativePath));
+}
+
 // src/droid-missions/prompts.ts
 function buildWorkerPrompt(input) {
-  const { state, feature, missionDir, message } = input;
+  const { state, feature, missionDir: missionDir2, message } = input;
   const extraMessage = message ? `
 ## Orchestrator Message
 
@@ -18,7 +115,7 @@ ${message}
 - Mission ID: ${state.missionId}
 - Title: ${state.title}
 - Goal: ${state.goal}
-- Mission directory: ${missionDir}
+- Mission directory: ${missionDir2}
 - Working directory: ${state.workingDirectory}
 
 ## Assigned Feature
@@ -94,6 +191,19 @@ function allFeaturesCompleted(features) {
 function progressType(successState) {
   return successState === "success" ? "worker_completed" : "worker_failed";
 }
+function clearWorkerSession(feature) {
+  feature.workerSessionId = undefined;
+  feature.workerSessionIds = [];
+}
+function setWorkerSession(feature, workerSessionId) {
+  feature.workerSessionId = workerSessionId;
+  if (!workerSessionId)
+    return;
+  feature.workerSessionIds = [
+    ...feature.workerSessionIds ?? [],
+    workerSessionId
+  ].filter((value, index, array) => array.indexOf(value) === index);
+}
 function validationFeature(milestone, kind) {
   const id = kind === "scrutiny" ? `scrutiny-validator-${milestone}` : `user-testing-validator-${milestone}`;
   return {
@@ -185,7 +295,7 @@ class MissionRunner {
         const firstPendingIndex = features.findIndex((feature2) => feature2.status === "pending");
         if (pausedFeature && firstPendingIndex !== -1 && pausedIndex !== -1 && firstPendingIndex < pausedIndex) {
           pausedFeature.status = "pending";
-          pausedFeature.workerSessionId = undefined;
+          clearWorkerSession(pausedFeature);
           pausedFeature.startedAt = undefined;
           state.status = "running";
           state.pauseReason = undefined;
@@ -198,7 +308,7 @@ class MissionRunner {
         }
         if (pausedFeature && args.restartFeature) {
           pausedFeature.status = "pending";
-          pausedFeature.workerSessionId = undefined;
+          clearWorkerSession(pausedFeature);
           pausedFeature.startedAt = undefined;
           state.status = "running";
           state.pauseReason = undefined;
@@ -331,7 +441,7 @@ class MissionRunner {
         firstStarted.workerSessionId = workerSessionId;
       }
       feature.status = "in_progress";
-      feature.workerSessionId = workerSessionId;
+      setWorkerSession(feature, workerSessionId);
       feature.startedAt = at;
       state.status = "running";
       state.updatedAt = at;
@@ -382,7 +492,7 @@ class MissionRunner {
         });
       } catch (error) {
         feature.status = "pending";
-        feature.workerSessionId = undefined;
+        clearWorkerSession(feature);
         feature.startedAt = undefined;
         state.status = "orchestrator_turn";
         state.activeFeatureId = undefined;
@@ -430,7 +540,7 @@ class MissionRunner {
       throw new Error("commitId and repoPath are required when codeChanged is true");
     }
     assertHandoffContract(args);
-    feature.workerSessionId = args.workerSessionId ?? feature.workerSessionId;
+    setWorkerSession(feature, args.workerSessionId ?? feature.workerSessionId);
     feature.completedAt = at;
     feature.status = args.successState === "success" ? "completed" : "pending";
     const hasHandoffIssues = args.handoff.discoveredIssues.length > 0 || hasUnfinishedWork(args.handoff.whatWasLeftUndone);
@@ -676,61 +786,11 @@ import {
 } from "fs/promises";
 import path2 from "path";
 
-// src/droid-missions/paths.ts
-import path from "path";
-var STORAGE_DIR = path.join(".opencode", "droid-missions");
-var MISSIONS_DIR = "missions";
-function missionStorageRoot(projectRoot) {
-  return path.join(projectRoot, STORAGE_DIR);
-}
-function missionsRoot(projectRoot) {
-  return path.join(missionStorageRoot(projectRoot), MISSIONS_DIR);
-}
-function sanitizeMissionId(input) {
-  const value = input.trim();
-  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value)) {
-    throw new Error("Invalid mission id. Use 1-128 letters, numbers, dots, underscores, or hyphens.");
-  }
-  return value;
-}
-function createMissionId(title, now) {
-  const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48) || "mission";
-  const stamp = new Date(now).getTime().toString(36);
-  return sanitizeMissionId(`${slug}-${stamp}`);
-}
-function missionDir(projectRoot, missionId) {
-  return path.join(missionsRoot(projectRoot), sanitizeMissionId(missionId));
-}
-function toMissionRelativePath(relativePath) {
-  const normalized = relativePath.replaceAll("\\", "/").replace(/^\/+/, "");
-  if (normalized === "" || normalized.startsWith("../") || normalized.includes("/../") || normalized === "..") {
-    throw new Error(`Invalid mission artifact path: ${relativePath}`);
-  }
-  return path.posix.normalize(normalized);
-}
-function assertInside(parent, child) {
-  const resolvedParent = path.resolve(parent);
-  const resolvedChild = path.resolve(child);
-  if (resolvedChild !== resolvedParent && !resolvedChild.startsWith(resolvedParent + path.sep)) {
-    throw new Error(`Path escapes mission directory: ${child}`);
-  }
-}
-function isMissionSystemFile(relativePath) {
-  const systemFiles = new Set([
-    "state.json",
-    "features.json",
-    "progress_log.jsonl",
-    "handoffs.jsonl",
-    "worker-transcripts.jsonl",
-    "working_directory.txt"
-  ]);
-  return systemFiles.has(toMissionRelativePath(relativePath));
-}
-
 // src/droid-missions/validation.ts
 var systemManagedFeatureFields = new Set([
   "status",
   "workerSessionId",
+  "workerSessionIds",
   "startedAt",
   "completedAt",
   "isValidation",
@@ -768,6 +828,15 @@ function readStringArray(record, key) {
   }
   return value.map((item) => item.trim()).filter(Boolean);
 }
+function readStringOrStringArray(record, key) {
+  const value = record[key];
+  if (typeof value === "string" && value.trim() !== "")
+    return value.trim();
+  if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+    return value.map((item) => item.trim()).filter(Boolean);
+  }
+  throw new Error(`Feature field "${key}" must be a non-empty string or array of strings`);
+}
 function validateFeaturePlans(inputs, skillNames) {
   const ids = new Set;
   return inputs.map((input, index) => {
@@ -795,7 +864,7 @@ function validateFeaturePlans(inputs, skillNames) {
       skillName,
       milestone: readString(input, "milestone"),
       preconditions: readStringArray(input, "preconditions"),
-      expectedBehavior: readString(input, "expectedBehavior"),
+      expectedBehavior: readStringOrStringArray(input, "expectedBehavior"),
       verificationSteps: readStringArray(input, "verificationSteps"),
       fulfills: readStringArray(input, "fulfills")
     };
@@ -915,6 +984,153 @@ Plan artifacts, write feature slices, run one worker per feature, then complete
 function handoffId(featureId, at) {
   return `${featureId}-${at.replace(/[^a-z0-9]/gi, "").slice(0, 20)}`;
 }
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function normalizeStringArray(value) {
+  if (Array.isArray(value)) {
+    return value.filter((item) => typeof item === "string");
+  }
+  if (typeof value === "string" && value.trim())
+    return [value.trim()];
+  return [];
+}
+function normalizeState(raw, missionId) {
+  const record = asRecord(raw);
+  const status = record.status ?? record.state;
+  return {
+    ...record,
+    missionId: typeof record.missionId === "string" ? record.missionId : missionId,
+    title: typeof record.title === "string" ? record.title : missionId,
+    goal: typeof record.goal === "string" ? record.goal : "",
+    status: typeof status === "string" ? status : "awaiting_input",
+    state: typeof status === "string" ? status : "awaiting_input",
+    workingDirectory: typeof record.workingDirectory === "string" ? record.workingDirectory : process.cwd(),
+    createdAt: typeof record.createdAt === "string" ? record.createdAt : new Date(0).toISOString(),
+    updatedAt: typeof record.updatedAt === "string" ? record.updatedAt : new Date(0).toISOString()
+  };
+}
+function stateForDisk(state) {
+  return {
+    ...state,
+    state: state.status
+  };
+}
+function normalizeFeature(raw) {
+  const record = asRecord(raw);
+  const workerSessionIds = normalizeStringArray(record.workerSessionIds);
+  if (typeof record.workerSessionId === "string" && !workerSessionIds.includes(record.workerSessionId)) {
+    workerSessionIds.push(record.workerSessionId);
+  }
+  const workerSessionId = typeof record.workerSessionId === "string" ? record.workerSessionId : workerSessionIds.at(-1);
+  return {
+    ...record,
+    id: String(record.id ?? ""),
+    description: String(record.description ?? ""),
+    skillName: String(record.skillName ?? "implementation"),
+    milestone: String(record.milestone ?? "default"),
+    preconditions: normalizeStringArray(record.preconditions),
+    expectedBehavior: typeof record.expectedBehavior === "string" || Array.isArray(record.expectedBehavior) ? record.expectedBehavior : "",
+    verificationSteps: normalizeStringArray(record.verificationSteps),
+    fulfills: normalizeStringArray(record.fulfills),
+    status: record.status === "in_progress" || record.status === "completed" || record.status === "cancelled" ? record.status : "pending",
+    workerSessionId,
+    workerSessionIds
+  };
+}
+function featureForDisk(feature) {
+  const workerSessionIds = [
+    ...feature.workerSessionIds ?? [],
+    ...feature.workerSessionId ? [feature.workerSessionId] : []
+  ].filter((value, index, array) => array.indexOf(value) === index);
+  const { workerSessionId: _workerSessionId, ...rest } = feature;
+  return {
+    ...rest,
+    workerSessionIds
+  };
+}
+function normalizeProgressEntry(raw) {
+  const record = asRecord(raw);
+  const at = record.at ?? record.timestamp;
+  return {
+    ...record,
+    type: String(record.type ?? "artifact_written"),
+    at: typeof at === "string" ? at : new Date(0).toISOString(),
+    timestamp: typeof at === "string" ? at : new Date(0).toISOString(),
+    missionId: String(record.missionId ?? "")
+  };
+}
+function progressForDisk(entry) {
+  return {
+    ...entry,
+    timestamp: entry.timestamp ?? entry.at
+  };
+}
+function normalizeStoredHandoff(raw) {
+  const record = asRecord(raw);
+  const handoff = asRecord(record.handoff);
+  const flattened = Object.keys(handoff).length > 0 ? handoff : record;
+  const createdAt = record.createdAt ?? record.timestamp;
+  const featureId = String(record.featureId ?? "unknown-feature");
+  const timestamp = typeof createdAt === "string" ? createdAt : new Date(0).toISOString();
+  return {
+    ...flattened,
+    id: typeof record.id === "string" ? record.id : handoffId(featureId, timestamp),
+    missionId: String(record.missionId ?? ""),
+    featureId,
+    workerSessionId: typeof record.workerSessionId === "string" ? record.workerSessionId : undefined,
+    successState: record.successState === "partial" || record.successState === "failure" ? record.successState : "success",
+    returnToOrchestrator: record.returnToOrchestrator === true,
+    validatorsPassed: typeof record.validatorsPassed === "boolean" ? record.validatorsPassed : undefined,
+    commitId: typeof record.commitId === "string" ? record.commitId : undefined,
+    repoPath: typeof record.repoPath === "string" ? record.repoPath : undefined,
+    handoffFile: typeof record.handoffFile === "string" ? record.handoffFile : "",
+    createdAt: timestamp,
+    dismissedAt: typeof record.dismissedAt === "string" ? record.dismissedAt : undefined,
+    dismissalReason: typeof record.dismissalReason === "string" ? record.dismissalReason : undefined,
+    timestamp,
+    handoff: flattened
+  };
+}
+function handoffForDisk(handoff) {
+  const nested = handoff.handoff ?? {
+    salientSummary: handoff.salientSummary,
+    whatWasImplemented: handoff.whatWasImplemented,
+    whatWasLeftUndone: handoff.whatWasLeftUndone,
+    verification: handoff.verification,
+    tests: handoff.tests,
+    discoveredIssues: handoff.discoveredIssues,
+    skillFeedback: handoff.skillFeedback
+  };
+  return {
+    id: handoff.id,
+    missionId: handoff.missionId,
+    timestamp: handoff.timestamp ?? handoff.createdAt,
+    createdAt: handoff.createdAt,
+    workerSessionId: handoff.workerSessionId,
+    featureId: handoff.featureId,
+    successState: handoff.successState,
+    returnToOrchestrator: handoff.returnToOrchestrator,
+    validatorsPassed: handoff.validatorsPassed,
+    commitId: handoff.commitId,
+    repoPath: handoff.repoPath,
+    handoffFile: handoff.handoffFile,
+    dismissedAt: handoff.dismissedAt,
+    dismissalReason: handoff.dismissalReason,
+    handoff: nested
+  };
+}
+function isEnoent(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+
+class MissionNotFoundError extends Error {
+  constructor(missionId, missionsRootPath) {
+    const storage = missionStorageKind() === "factory" ? "Factory global mission storage because droid is installed on PATH" : "OpenCode global mission storage because droid is not installed on PATH";
+    super(`Mission not found: ${missionId}. Checked ${storage} at ${missionsRootPath}. Run droid_mission_list to see available mission IDs, or create a mission with droid_mission_create.`);
+    this.name = "MissionNotFoundError";
+  }
+}
 
 class MissionStore {
   projectRoot;
@@ -947,14 +1163,17 @@ class MissionStore {
     await mkdir(path2.join(dir, "library"), { recursive: true });
     await mkdir(path2.join(dir, "scripts"), { recursive: true });
     await mkdir(path2.join(dir, "handoffs"), { recursive: true });
+    await mkdir(path2.join(dir, "validation"), { recursive: true });
     const state = {
       missionId,
       title: args.title,
       goal: args.goal,
       status: "awaiting_input",
+      state: "awaiting_input",
       workingDirectory: args.workingDirectory ?? this.projectRoot,
       createdAt,
-      updatedAt: createdAt
+      updatedAt: createdAt,
+      artifactLayoutVersion: 2
     };
     await writeFile(path2.join(dir, "mission.md"), missionMarkdown(args, missionId, createdAt));
     await writeFile(path2.join(dir, "working_directory.txt"), `${state.workingDirectory}
@@ -963,8 +1182,8 @@ class MissionStore {
     await writeFile(path2.join(dir, "skills", "implementation", "SKILL.md"), DEFAULT_IMPLEMENTATION_SKILL);
     await writeFile(path2.join(dir, "skills", "scrutiny-validator", "SKILL.md"), DEFAULT_SCRUTINY_SKILL);
     await writeFile(path2.join(dir, "skills", "user-testing-validator", "SKILL.md"), DEFAULT_USER_TESTING_SKILL);
-    await writeJson(path2.join(dir, "state.json"), state);
-    await writeJson(path2.join(dir, "features.json"), []);
+    await writeJson(path2.join(dir, "state.json"), stateForDisk(state));
+    await writeJson(path2.join(dir, "features.json"), { features: [] });
     await writeFile(path2.join(dir, "progress_log.jsonl"), "");
     await writeFile(path2.join(dir, "handoffs.jsonl"), "");
     await writeFile(path2.join(dir, "worker-transcripts.jsonl"), "");
@@ -972,6 +1191,12 @@ class MissionStore {
       missionId,
       milestones: {}
     });
+    await writeJson(path2.join(dir, "canonical-artifact-layout.json"), {
+      version: 2,
+      markedCanonicalAt: createdAt,
+      importedPaths: [],
+      ambiguousSkillNames: []
+    });
     await this.appendProgress(missionId, {
       type: "mission_accepted",
       at: createdAt,
@@ -998,16 +1223,35 @@ class MissionStore {
     return states.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
   }
   async readState(missionId) {
-    return readJson(path2.join(this.missionDir(missionId), "state.json"));
+    try {
+      return normalizeState(await readJson(path2.join(this.missionDir(missionId), "state.json")), missionId);
+    } catch (error) {
+      if (isEnoent(error)) {
+        throw new MissionNotFoundError(missionId, this.missionsRoot());
+      }
+      throw error;
+    }
   }
   async writeState(state) {
-    await writeJson(path2.join(this.missionDir(state.missionId), "state.json"), state);
+    await writeJson(path2.join(this.missionDir(state.missionId), "state.json"), stateForDisk(state));
   }
   async readFeatures(missionId) {
-    return readJson(path2.join(this.missionDir(missionId), "features.json"));
+    let raw;
+    try {
+      raw = await readJson(path2.join(this.missionDir(missionId), "features.json"));
+    } catch (error) {
+      if (isEnoent(error)) {
+        throw new MissionNotFoundError(missionId, this.missionsRoot());
+      }
+      throw error;
+    }
+    const features = Array.isArray(raw) ? raw : asRecord(raw).features;
+    return Array.isArray(features) ? features.map(normalizeFeature) : [];
   }
   async writeFeatureRecords(missionId, features) {
-    await writeJson(path2.join(this.missionDir(missionId), "features.json"), features);
+    await writeJson(path2.join(this.missionDir(missionId), "features.json"), {
+      features: features.map(featureForDisk)
+    });
   }
   async writeFeatures(missionId, inputs) {
     const skillNames = await this.listMissionSkills(missionId);
@@ -1055,23 +1299,27 @@ class MissionStore {
     return target;
   }
   async readProgress(missionId) {
-    return readJsonl(path2.join(this.missionDir(missionId), "progress_log.jsonl"));
+    return (await readJsonl(path2.join(this.missionDir(missionId), "progress_log.jsonl"))).map(normalizeProgressEntry);
   }
   async appendProgress(missionId, entry) {
-    await appendJsonl(path2.join(this.missionDir(missionId), "progress_log.jsonl"), entry);
+    await appendJsonl(path2.join(this.missionDir(missionId), "progress_log.jsonl"), progressForDisk(entry));
   }
   async readHandoffs(missionId) {
-    return readJsonl(path2.join(this.missionDir(missionId), "handoffs.jsonl"));
+    return (await readJsonl(path2.join(this.missionDir(missionId), "handoffs.jsonl"))).map((entry) => {
+      const normalized = normalizeStoredHandoff(entry);
+      return { ...normalized, missionId };
+    });
   }
   async writeHandoffs(missionId, handoffs) {
-    await writeFile(path2.join(this.missionDir(missionId), "handoffs.jsonl"), handoffs.map((handoff) => JSON.stringify(handoff)).join(`
+    await writeFile(path2.join(this.missionDir(missionId), "handoffs.jsonl"), handoffs.map((handoff) => JSON.stringify(handoffForDisk(handoff))).join(`
 `) + (handoffs.length ? `
 ` : ""), "utf8");
   }
   async appendHandoff(missionId, args) {
     const createdAt = nowIso2(args.now);
     const id = handoffId(args.featureId, createdAt);
-    const handoffFile = path2.join(this.missionDir(missionId), "handoffs", `${id}.json`);
+    const workerId = args.workerSessionId ?? "unknown-worker";
+    const handoffFile = path2.join(this.missionDir(missionId), "handoffs", `${createdAt.replace(/[:.]/g, "-")}__${args.featureId}__${workerId}.json`);
     const stored = {
       id,
       missionId,
@@ -1084,9 +1332,11 @@ class MissionStore {
       repoPath: args.repoPath,
       handoffFile,
       createdAt,
+      timestamp: createdAt,
+      handoff: args.handoff,
       ...args.handoff
     };
-    await writeJson(handoffFile, stored);
+    await writeJson(handoffFile, handoffForDisk(stored));
     await this.appendTranscriptSkeleton(missionId, {
       workerSessionId: args.workerSessionId,
       featureId: args.featureId,
@@ -1100,7 +1350,7 @@ ${args.handoff.verification.commandsRun.map((command) => `- ${command.command} (
 `)}`,
       createdAt
     });
-    await appendJsonl(path2.join(this.missionDir(missionId), "handoffs.jsonl"), stored);
+    await appendJsonl(path2.join(this.missionDir(missionId), "handoffs.jsonl"), handoffForDisk(stored));
     return stored;
   }
   async appendTranscriptSkeleton(missionId, args) {
@@ -1118,6 +1368,7 @@ ${args.handoff.verification.commandsRun.map((command) => `- ${command.command} (
   async dismissHandoffItems(missionId, dismissals, now) {
     const at = nowIso2(now);
     const reasons = new Map(dismissals.map((item) => [item.id, item.reason]));
+    const originalHandoffs = await this.readHandoffs(missionId);
     const handoffs = (await this.readHandoffs(missionId)).map((handoff) => {
       const reason = reasons.get(handoff.id);
       if (!reason)
@@ -1133,17 +1384,37 @@ ${args.handoff.verification.commandsRun.map((command) => `- ${command.command} (
       type: "handoff_items_dismissed",
       at,
       missionId,
-      summary: `${dismissals.length} handoff items dismissed`
+      summary: `${dismissals.length} handoff items dismissed`,
+      details: {
+        dismissals: dismissals.map((dismissal) => {
+          const handoff = originalHandoffs.find((item) => item.id === dismissal.id);
+          return {
+            type: "handoff",
+            sourceFeatureId: handoff?.featureId ?? dismissal.id,
+            summary: handoff?.salientSummary ?? dismissal.id,
+            justification: dismissal.reason
+          };
+        })
+      }
     });
     return handoffs;
   }
   async snapshot(missionId) {
+    const features = await this.readFeatures(missionId);
     return {
       dir: this.missionDir(missionId),
       state: await this.readState(missionId),
-      features: await this.readFeatures(missionId),
+      features,
       handoffs: await this.readHandoffs(missionId),
-      progress: await this.readProgress(missionId)
+      progress: await this.readProgress(missionId),
+      metadata: {
+        storageKind: missionStorageKind(),
+        featureCounts: features.reduce((counts, feature) => {
+          counts[feature.status] += 1;
+          return counts;
+        }, { pending: 0, in_progress: 0, completed: 0, cancelled: 0 }),
+        resumable: missionStorageKind() !== "factory"
+      }
     };
   }
 }
@@ -1156,8 +1427,8 @@ function projectRootFrom(input) {
   return input.worktree || input.directory;
 }
 function isProtectedMissionPath(projectRoot, filePath) {
-  const resolved = path3.resolve(filePath);
-  const missionRoot = path3.join(path3.resolve(projectRoot), ".opencode", "droid-missions", "missions");
+  const resolved = resolveExistingOrParent(filePath);
+  const missionRoot = resolveExistingOrParent(missionsRoot(projectRoot));
   if (!resolved.startsWith(missionRoot + path3.sep))
     return false;
   return [
@@ -1169,6 +1440,19 @@ function isProtectedMissionPath(projectRoot, filePath) {
     "working_directory.txt"
   ].includes(path3.basename(resolved));
 }
+function resolveExistingOrParent(filePath) {
+  try {
+    return realpathSync(filePath);
+  } catch {
+    const parent = path3.dirname(filePath);
+    const base = path3.basename(filePath);
+    try {
+      return path3.join(realpathSync(parent), base);
+    } catch {
+      return path3.resolve(filePath);
+    }
+  }
+}
 function normalizeToolPath(args) {
   const candidate = args.filePath ?? args.path ?? args.file ?? args.target;
   return typeof candidate === "string" ? candidate : undefined;
@@ -1373,7 +1657,7 @@ var DroidMissionsPlugin = async (ctx) => {
         }
       }),
       droid_mission_list: tool({
-        description: "List all project-local OpenCode missions.",
+        description: "List all missions in the selected global mission storage root.",
         args: {},
         async execute() {
           return jsonResult({ missions: await store.listMissions() });
@@ -1388,14 +1672,15 @@ var DroidMissionsPlugin = async (ctx) => {
       if (filePath && isProtectedMissionPath(projectRoot, filePath)) {
         throw new Error("Use droid_mission tools instead of direct edits to mission system files.");
       }
+      const missionRoot = path3.resolve(missionsRoot(projectRoot));
       const serializedArgs = JSON.stringify(output.args);
-      if (serializedArgs.includes(".opencode/droid-missions/missions/") && /state\.json|features\.json|progress_log\.jsonl|handoffs\.jsonl/.test(serializedArgs)) {
+      if (serializedArgs.includes(missionRoot) && /state\.json|features\.json|progress_log\.jsonl|handoffs\.jsonl/.test(serializedArgs)) {
         throw new Error("Use droid_mission tools instead of patching mission system files.");
       }
     },
     async "shell.env"(input, output) {
       const root = input.cwd.startsWith(projectRoot) ? projectRoot : input.cwd;
-      output.env.OPENCODE_DROID_MISSIONS_ROOT = path3.join(root, ".opencode", "droid-missions");
+      output.env.OPENCODE_DROID_MISSIONS_ROOT = missionsRoot(root);
     },
     async "experimental.session.compacting"(_input, output) {
       const missions = await store.listMissions();

package/opencode/AGENTS.md

@@ -15,7 +15,7 @@ skills/    OpenCode-compatible mission orchestration skill
 ## Safe-Change Rules
 
 - Keep tool permissions aligned with the plugin tool names.
-- Do not instruct agents to edit `.opencode/droid-missions/missions/*` system files directly.
+- Do not instruct agents to edit global mission system files directly.
 - Validation agents must return control to the orchestrator through `droid_mission_end_feature`.
 - Do not mention Droid CLI installation or Factory runtime setup in these assets.
 

package/opencode/agents/droid-mission-orchestrator.md

@@ -1,5 +1,5 @@
 ---
-description: Plans and controls Droid-style missions through project-local OpenCode mission tools.
+description: Plans and controls Droid-style missions through global OpenCode mission tools.
 mode: primary
 permission:
   read: allow

package/opencode/commands/mission.md

@@ -1,5 +1,5 @@
 ---
-description: Create or continue a project-local OpenCode mission.
+description: Create or continue a global OpenCode mission.
 agent: droid-mission-orchestrator
 ---
 

package/opencode/skills/droid-mission-orchestrator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: droid-mission-orchestrator
-description: Create and run project-local Droid-style missions in OpenCode without any external mission runtime.
+description: Create and run global Droid-style missions in OpenCode without any external mission runtime.
 compatibility: opencode
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-missions",
-  "version": "0.1.0",
-  "description": "OpenCode plugin for project-local mission planning, worker delegation, handoffs, and validation.",
+  "version": "0.1.1",
+  "description": "OpenCode plugin for global mission planning, worker delegation, handoffs, and validation.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",