@ours.network/fleet 1.2.0-nightly.54 → 1.2.0-nightly.55

package/dist/temp-lifecycle.js

@@ -1,8 +1,11 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, } from 'node:fs';
+import { parse } from 'yaml';
 import { randomUUID } from 'node:crypto';
 import { basename, join } from 'node:path';
 import { replaceFileAtomically, withFileLock, withSynchronousFileLock } from './atomic-file.js';
 import { realExec } from './exec.js';
+import { captureMemberEnvironment, catalogLiveness, memberKey, readMember, registerMember, unregisterMember, unregisterTaskMember } from './supervisor/catalog.js';
+import { ensureFleetParent } from './supervisor/fleet.js';
 import { stateRoot, tmpRoot } from './paths.js';
 export const TEMP_SUPERVISOR_FILE = '.temp-supervisor.json';
 export const TEMP_TERMINATION_FILE = 'termination.jsonl';
@@ -13,26 +16,40 @@ export const TEMP_LAUNCH_GRACE_MS = 60_000;
 const metadataPath = (dir) => join(dir, TEMP_SUPERVISOR_FILE);
 export const tempSystemdUnit = (name) => `ours-fleet-temp-${name}.service`;
 export const tempLaunchdLabel = (name) => `network.ours.fleet.temp.${name}`;
-export function prepareTempSupervisor(dir, role) {
+export function prepareTempSupervisor(dir, role, taskOwner) {
     const record = {
-        version: 1, role, launchId: randomUUID(), createdAt: new Date().toISOString(), phase: 'launching',
+        version: 1, role, launchId: randomUUID(), createdAt: new Date().toISOString(), phase: 'launching', ...(taskOwner ? { taskOwner } : {}),
     };
     replaceFileAtomically(metadataPath(dir), JSON.stringify(record, null, 2) + '\n');
     return record;
 }
 export function readTempSupervisor(dir) {
+    let value;
     try {
-        const value = JSON.parse(readFileSync(metadataPath(dir), 'utf8'));
-        if (value.version !== 1 || typeof value.role !== 'string' || typeof value.launchId !== 'string')
-            return undefined;
-        return value;
+        value = JSON.parse(readFileSync(metadataPath(dir), 'utf8'));
     }
     catch {
         return undefined;
     }
+    if (!value || typeof value !== 'object' || value.version !== 1 || typeof value.role !== 'string' || typeof value.launchId !== 'string')
+        return undefined;
+    if (value.kind !== undefined && !['fleet-managed', 'systemd-transient', 'launchd-transient', 'detached'].includes(value.kind))
+        throw Error('TEMP_SUPERVISOR_KIND_UNSUPPORTED');
+    return value;
+}
+/** Broad scans retain unsupported entries instead of blocking other members. */
+export function readTempSupervisorForScan(dir) {
+    try {
+        return readTempSupervisor(dir);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'TEMP_SUPERVISOR_KIND_UNSUPPORTED')
+            return undefined;
+        throw error;
+    }
 }
 const metadataLockPath = (dir) => join(stateRoot(), 'locks', 'temp-supervisors', encodeURIComponent(basename(dir)));
-async function updateTempSupervisor(dir, update) {
+export async function updateTempSupervisor(dir, update) {
     // The launcher and the just-started supervisor are separate processes. Lock
     // their read/merge/write updates so neither can discard the other's kind,
     // target, pid or phase. The lock lives outside the role directory so an
@@ -48,54 +65,22 @@ async function updateTempSupervisor(dir, update) {
         return next;
     });
 }
-/**
- * Launch a temp supervisor outside the caller's service-manager ownership
- * boundary. `detached: true` creates a new process group but does not escape a
- * systemd cgroup; a transient unit does, and is not enabled across reboot.
- */
+/** Register managed members under Fleet; explicit manual mode uses a detached child. */
 export function makeTempSupervisorLauncher(options = {}) {
     const exec = options.exec ?? realExec;
     const platform = options.platform ?? process.platform;
     const supervisor = options.supervisor ?? process.env.OURS_FLEET_SUPERVISOR;
     return async (binPath, args, dir) => {
-        const inherited = [
-            'HOME', 'PATH', 'XDG_RUNTIME_DIR', 'OURS_FLEET_HOME', 'OURS_FLEET_SOCKET_ROOT', 'CODEX_HOME',
-            // Preserve runtime selection across the service-manager boundary, including
-            // an explicit empty value which selects the bundle over manager defaults.
-            'CODEX_PATH',
-            // The child supervisor performs daemon identity and wake probes itself;
-            // it must resolve the same ours profile as the spawning supervisor.
-            'OURS_PORT', 'OURS_STATE_DIR', 'OURS_API_TOKEN', 'OURS_CONFIG',
-        ]
-            .flatMap(key => process.env[key] !== undefined ? [`${key}=${process.env[key]}`] : []);
         const role = args.at(-1);
         if (!role)
             throw new Error('temporary supervisor launch requires a role name');
-        const log = join(dir, 'supervisor.log');
-        if (supervisor !== 'none' && platform === 'linux') {
-            const target = tempSystemdUnit(role);
-            await updateTempSupervisor(dir, { phase: 'launching', kind: 'systemd-transient', target, binPath });
-            const result = await exec('systemd-run', [
-                '--user', '--quiet', '--collect', `--unit=${target}`,
-                '--property=Type=exec', '--property=KillMode=control-group', '--property=TimeoutStopSec=15s',
-                `--property=StandardOutput=append:${log}`, `--property=StandardError=append:${log}`,
-                ...inherited.map(value => `--setenv=${value}`),
-                process.execPath, binPath, ...args,
-            ]);
-            if (result.code !== 0)
-                throw new Error(`systemd-run ${target} failed: ${result.stderr.trim() || `exit ${result.code}`}`);
-            await updateTempSupervisor(dir, { phase: 'active' });
-            return;
-        }
-        if (supervisor !== 'none' && platform === 'darwin') {
-            const target = tempLaunchdLabel(role);
-            await updateTempSupervisor(dir, { phase: 'launching', kind: 'launchd-transient', target, binPath });
-            const result = await exec('launchctl', [
-                'submit', '-l', target, '-o', log, '-e', log, '--',
-                '/usr/bin/env', ...inherited, process.execPath, binPath, ...args,
-            ]);
-            if (result.code !== 0)
-                throw new Error(`launchctl submit ${target} failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+        const metadata = readTempSupervisor(dir);
+        if (supervisor !== 'none') {
+            const kind = metadata?.taskOwner ? 'task' : 'temporary';
+            await updateTempSupervisor(dir, { phase: 'launching', kind: 'fleet-managed', target: memberKey(role, kind), binPath });
+            await ensureFleetParent(exec, platform);
+            await registerMember({ name: role, kind, dir, environment: await captureMemberEnvironment(),
+                ...(metadata?.taskOwner ? { taskOwner: metadata.taskOwner, launchId: metadata.launchId } : {}) });
             await updateTempSupervisor(dir, { phase: 'active' });
             return;
         }
@@ -211,7 +196,7 @@ export function archiveTempState(role, reason, outcome, detail, now = new Date()
     return paths.target;
 }
 function isArchiveForLaunch(path, role, launchId) {
-    const supervisor = readTempSupervisor(path);
+    const supervisor = readTempSupervisorForScan(path);
     if (supervisor?.role !== role || supervisor.launchId !== launchId)
         return false;
     try {
@@ -256,7 +241,7 @@ export function tempArchiveForCreationAction(role, creationActionId) {
         return undefined;
     }
     const matches = entries.flatMap(path => {
-        const supervisor = readTempSupervisor(path);
+        const supervisor = readTempSupervisorForScan(path);
         if (!supervisor || supervisor.role !== role || !isArchiveForLaunch(path, role, supervisor.launchId))
             return [];
         try {
@@ -317,7 +302,15 @@ function recoverInterruptedArchives(now) {
     const recovered = [];
     for (const name of names) {
         const source = join(archiveRoot(), name);
-        const supervisor = readTempSupervisor(source);
+        let supervisor;
+        try {
+            supervisor = readTempSupervisor(source);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === 'TEMP_SUPERVISOR_KIND_UNSUPPORTED')
+                continue;
+            throw error;
+        }
         let line;
         try {
             line = readFileSync(join(source, TEMP_TERMINATION_FILE), 'utf8')
@@ -393,11 +386,13 @@ export async function tempSupervisorLiveness(dir, deps = {}) {
     // A concurrent spawn writes the target before systemd-run/launchctl has
     // registered it. A not-yet-created unit looks exactly like an inactive one,
     // so launch phase plus its bounded grace is not cleanup authority.
-    if (record.phase === 'launching'
+    if (record.phase === 'launching' && !requestedTempStopReason(dir)
         && (!Number.isFinite(age) || age < TEMP_LAUNCH_GRACE_MS))
         return 'unknown';
     // Older writers could lose `kind` in an unlocked metadata RMW while retaining
     // the supervisor pid. Exact argv ownership is stronger than the missing tag.
+    if (record.kind === 'fleet-managed')
+        return (await catalogLiveness(record.target ?? memberKey(record.role, record.taskOwner ? 'task' : 'temporary'), exec)).state;
     if (record.pid && (!record.kind || record.kind === 'detached'))
         return detachedProcessLiveness(record, deps);
     if (record.kind === 'systemd-transient' && record.target) {
@@ -461,6 +456,13 @@ export async function stopTempSupervisor(role, deps = {}) {
     replaceFileAtomically(join(dir, TEMP_STOP_REQUEST_FILE), JSON.stringify({
         version: 1, role, reason: 'operator-stop', requestedAt: new Date().toISOString(),
     }) + '\n');
+    if (record.kind === 'fleet-managed') {
+        if (record.taskOwner)
+            await unregisterTaskMember(role, { ...record.taskOwner, launchId: record.launchId }, { exec, sleep: deps.sleep });
+        else
+            await unregisterMember(record.target ?? memberKey(role, 'temporary'), { exec, sleep: deps.sleep });
+        return 'stopped';
+    }
     if (record.kind === 'systemd-transient' && record.target) {
         const result = await exec('systemctl', ['--user', 'stop', record.target]);
         if (result.code !== 0
@@ -511,6 +513,26 @@ export async function stopTempSupervisor(role, deps = {}) {
     (deps.kill ?? process.kill)(record.pid, 'SIGTERM');
     return 'stopped';
 }
+/** Legacy task snapshots remain recovery evidence even before explicit migration. */
+function hasRetainedTaskReference(dir) {
+    try {
+        if (basename(dir).startsWith('layout-')) {
+            const provenance = JSON.parse(readFileSync(join(dir, 'creation.json'), 'utf8'));
+            if (typeof provenance.creationActionId === 'string' && provenance.creationActionId.startsWith('task-'))
+                return true;
+        }
+        const startup = parse(readFileSync(join(dir, 'role.yaml'), 'utf8'))?.roomMemberStartup;
+        if (!startup?.room_id || !/^[A-Za-z0-9_-]{1,120}$/.test(startup.room_id))
+            return false;
+        const room = JSON.parse(readFileSync(join(stateRoot(), 'rooms', `${startup.room_id}.json`), 'utf8'));
+        return typeof room.task_id === 'string'
+            && room.member_seats.some((seat) => seat.role_name === basename(dir));
+    }
+    catch (error) {
+        // An unreadable role/room is uncertain ownership, never permission to reclaim.
+        return error.code !== 'ENOENT';
+    }
+}
 /**
  * Move a bounded batch of definitely-dead temp state into the evidence archive.
  * Unknown/legacy/live entries are preserved; absence of proof is never cleanup authority.
@@ -532,8 +554,18 @@ export async function reclaimStaleTempState(deps = {}) {
     const archived = [...recovered];
     for (const entry of entries) {
         const dir = join(tmpRoot(), entry.name);
-        if (!readTempSupervisor(dir))
-            continue; // legacy evidence has no safe ownership proof
+        const supervisor = readTempSupervisorForScan(dir);
+        if (!supervisor || supervisor.taskOwner || hasRetainedTaskReference(dir))
+            continue;
+        if (supervisor?.kind === 'fleet-managed' && supervisor.target) {
+            try {
+                if (readMember(supervisor.target)?.desired === 'running')
+                    continue;
+            }
+            catch {
+                continue;
+            } // uncertain catalog intent is never reclamation authority
+        }
         if (await tempSupervisorLiveness(dir, deps) !== 'stopped')
             continue;
         const target = archiveTempState(entry.name, 'stale-supervisor', 'reclaimed', 'supervisor is definitively stopped; state moved from the live roster without deletion', now);

package/dist/temp-supervisor-recovery.d.ts

@@ -1,3 +1,3 @@
 export declare const TEMP_RECYCLE_EXIT = 75;
 /** Keep the service's main process alive while replacing a PID-scoped worker. */
-export declare function runTempSupervisor(name: string, entrypoint: string, initial?: () => Promise<void>): Promise<void>;
+export declare function runTempSupervisor(name: string, entrypoint: string, initial?: () => Promise<void>, suspendOnStop?: boolean): Promise<void>;

package/dist/temp-supervisor-recovery.js

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import { runTemp, SupervisorRecycleRequiredError } from './runner.js';
 export const TEMP_RECYCLE_EXIT = 75;
 /** Keep the service's main process alive while replacing a PID-scoped worker. */
-export async function runTempSupervisor(name, entrypoint, initial = () => runTemp(name)) {
+export async function runTempSupervisor(name, entrypoint, initial = () => runTemp(name), suspendOnStop = false) {
     try {
         await initial();
         return;
@@ -12,7 +12,7 @@ export async function runTempSupervisor(name, entrypoint, initial = () => runTem
             throw error;
     }
     for (let attempt = 0; attempt < 3; attempt++) {
-        const child = spawn(process.execPath, [entrypoint, '_run-temp-worker', name], {
+        const child = spawn(process.execPath, [entrypoint, '_run-temp-worker', name, ...(suspendOnStop ? ['--suspend-on-stop'] : [])], {
             stdio: 'inherit',
             env: process.env,
         });

package/docs/fleet-migration.md

@@ -0,0 +1,54 @@
+# Upgrade to one Fleet service
+
+Permanent and task agents share one systemd user service on Linux or one
+LaunchAgent on macOS. Install the package and explicitly run `ours-fleet init`;
+package installation alone does not migrate services. New task/temporary launches
+refuse `FLEET_SERVICE_NOT_INSTALLED` until init succeeds. Native supervision uses
+the OS user's home; a custom `OURS_FLEET_HOME` is refused. Manual/isolated fleets
+can use `OURS_FLEET_SUPERVISOR=none` without boot recovery.
+
+Before init, back up Fleet configuration, private member/runtime/session state,
+task/room records and native units/plists. Preserve operator readiness commands,
+timeout/restart settings and environment in the common parent's explicit
+systemd drop-ins (`~/.config/systemd/user/ours-fleet.service.d/`). Conflicting
+per-agent settings need operator resolution. Migration does not copy scripts or
+silently discard hooks. Resolve `OPERATOR_DROPIN_REQUIRED` or `UNSUPPORTED_DROPIN`,
+reload the user manager, verify its effective settings, then retry.
+
+Init preflights configured permanent agents, retires only their proven old native
+services and registers them after exact old-process absence. `up NAME` migrates
+only NAME. Existing identity and conversation files remain in place. On Linux,
+enabled legacy roles transfer running boot intent, including enabled inactive
+roles; disabled inactive roles remain untouched. macOS stopped roles stay stopped.
+Interrupted transfers retain receipts; retry with the original state instead of
+deleting proof or starting old and new supervisors together.
+
+The parent starts existing agent runners. Adding a member does not restart it.
+Restarting the parent affects every managed agent. Permanent agents resume their
+conversation with their existing readiness/continuity prompts and may receive a
+new private runtime instance after orderly release. Task agents retain their
+original identity, runtime owner and conversation. Managed stop persists across
+parent restart/reboot. Non-resumable temporary agents retire on parent shutdown.
+
+## Existing tasks
+
+Running pre-upgrade transient task members remain untouched and report
+`migration_pending`; init does not make them durable. Clean legacy shutdown or
+explicit temporary stop releases/archives them. After abrupt process loss,
+`ours-fleet task recover-members TASK_ID` can adopt a stopped single-room member
+only with its original owner, identity, launch, workspace, conversation and room
+admission intact and exact process absence proven. Missing/mismatched evidence
+and unmarked legacy layouts require reconciliation. There is no automatic live
+handover: let old work retire normally, or preserve and inspect its original
+state before a controlled transition. Do not create replacement identities,
+redeem invitations again or fabricate ownership records to force recovery.
+
+## Rollback
+
+Stop the common parent and prove all managed process groups absent. Preserve an
+offline backup of catalog, receipts, private state and operator drop-ins. Restore
+the prior Fleet release and reviewed legacy units/plists, enabling only intended
+running agents. Keep the common parent disabled while legacy supervision runs.
+Re-entering central mode requires retained-proof reconciliation and old-process
+absence. Physical reboot/boot ordering, real macOS launchd and live host migration
+have not been qualified by the isolated process and injected native tests.

package/docs/task-workspaces.md

@@ -159,3 +159,29 @@ claiming complete erasure. An identity with no recoverable authenticated binding
 requires restoring its actual ownership evidence; a name-only force removal is
 not supported. Room deletion removes the linked Task's dead room/member links and preserves its workspace; use explicit
 Task deletion when the request includes the associated Task and its artifacts.
+
+
+## Retained task agents
+
+Task agents use the common Fleet service and existing runners while remaining
+outside the standalone agent roster. Recovery retains their original identity,
+private runtime owner, launch, working directory, admitted room and supported
+backend conversation. `ours-fleet task recover-members TASK_ID` resumes proven
+stopped members or resets their held restart circuit; it never creates identities
+or invitations. See [upgrade and rollback](fleet-migration.md) for legacy tasks.
+
+Recovery delivers an undispatched assignment once, continues interrupted work,
+and sends no readiness/work prompt to a completed idle conversation. An uncertain
+dispatch gets a continuation instead of replaying the assignment. First-session
+retry requires proof that no readiness/work was submitted; established session
+loss requires restoration of the original context. Task agents require a resumable
+harness. Missing ownership, workspace or room evidence keeps recovery held.
+
+Parent shutdown suspends task agents. Explicit member stop terminally releases
+the exact saved owner and archives its launch; it does not complete the task.
+Finish/cancel/review retain their existing semantics. Task deletion stops and
+unregisters only owned members, verifies identity absence and retries cleanup
+before erasing task/room/workspace resources. Permanent siblings remain intact.
+Standalone CLI/web removal refuses `TASK_MEMBER_IS_TASK_OWNED`; use the owning
+task lifecycle. Lost/corrupt task or launch records require restoring original
+backup evidence or explicit ownership reconciliation before deletion can finish.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/fleet",
-  "version": "1.2.0-nightly.54",
+  "version": "1.2.0-nightly.55",
   "description": "Harness-agnostic fleet of persistent, identity-bound AI agents. Declarative fleet.yaml, managed native/ACP sessions, supervision, and ours.network messaging.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",
@@ -22,6 +22,7 @@
     "docs/live-voice.md",
     "docs/room-layouts.md",
     "docs/validation/managed-cli-permissions.md",
+    "docs/fleet-migration.md",
     "LICENSE",
     "docs/acp-files.md"
   ],
@@ -38,6 +39,8 @@
     "test:pack": "vitest run --config vitest.integration.config.ts",
     "prepack": "npm run build",
     "prepublishOnly": "npm run build && npm test",
+    "test:task-recovery": "node test/task-runtime-recovery.integration.mjs",
+    "test:fleet-recovery": "node test/fleet-manager-recovery.integration.mjs",
     "test:v1-recovery": "node test/fleet-v1-recovery.integration.mjs retry && node test/fleet-v1-recovery.integration.mjs terminal-after-failure && node test/fleet-v1-recovery.integration.mjs terminal-release-failure"
   },
   "dependencies": {