approved-plan-continuity-hard-gate/scripts/subagent_delivery_watchdog.mjs

#!/usr/bin/env node

import fs from 'node:fs';
import path from 'node:path';
import process from 'node:process';

const ROOT_DIR = path.resolve(import.meta.dirname, '..');
const STATE_DIR = path.join(ROOT_DIR, 'state', 'subagent-delivery-watchdog');

function parseArgs(argv) {
  const args = {
    compact: false,
    input: null,
    help: false,
  };

  for (let i = 0; i < argv.length; i += 1) {
    const token = argv[i];

    if (token === '--compact') {
      args.compact = true;
      continue;
    }

    if (token === '--help' || token === '-h') {
      args.help = true;
      continue;
    }

    if (token === '--input') {
      args.input = argv[i + 1] ?? null;
      i += 1;
      continue;
    }

    if (token.startsWith('--input=')) {
      args.input = token.slice('--input='.length) || null;
      continue;
    }
  }

  return args;
}

function printHelp() {
  const lines = [
    'Usage: node scripts/subagent_delivery_watchdog.mjs [--compact] [--input <path>]',
    '',
    'Minimal CLI skeleton for the subagent delivery watchdog.',
  ];
  process.stdout.write(`${lines.join('\n')}\n`);
}

function tryReadInput(inputPath) {
  if (!inputPath) {
    return {
      path: null,
      exists: false,
      bytes: 0,
      preview: '',
    };
  }

  try {
    const content = fs.readFileSync(inputPath, 'utf8');
    return {
      path: inputPath,
      exists: true,
      bytes: Buffer.byteLength(content, 'utf8'),
      preview: content.slice(0, 200),
      content,
    };
  } catch (error) {
    return {
      path: inputPath,
      exists: false,
      bytes: 0,
      preview: '',
      error: error instanceof Error ? error.message : String(error),
    };
  }
}

function tryParseJson(content) {
  if (typeof content !== 'string' || content.length === 0) {
    return null;
  }

  try {
    return JSON.parse(content);
  } catch {
    return null;
  }
}

function writeDispatchReceiptState(payload) {
  if (!payload || typeof payload !== 'object') {
    return null;
  }

  const { runId, childSessionKey, dispatchAt, expectedBy } = payload;

  if (![runId, childSessionKey, dispatchAt, expectedBy].every((value) => typeof value === 'string' && value.length > 0)) {
    return null;
  }

  fs.mkdirSync(STATE_DIR, { recursive: true });

  const statePath = path.join(STATE_DIR, `${runId}.json`);
  const dispatchRecord = {
    runId,
    childSessionKey,
    dispatchAt,
    expectedBy,
  };

  fs.writeFileSync(statePath, `${JSON.stringify(dispatchRecord, null, 2)}\n`, 'utf8');

  return {
    statePath,
    record: dispatchRecord,
  };
}

function writeCompletionReceiptState(payload) {
  if (!payload || typeof payload !== 'object') {
    return null;
  }

  const { runId } = payload;
  const completionReceivedAt = payload.completionReceivedAt ?? payload.completionReceiptAt ?? null;
  const forwardedToMain = payload.forwardedToMain;
  const resultSource = payload.resultSource;

  if (typeof runId !== 'string' || runId.length === 0) {
    return null;
  }

  const completionUpdates = {};

  if (typeof completionReceivedAt === 'string' && completionReceivedAt.length > 0) {
    completionUpdates.completionReceivedAt = completionReceivedAt;
  }

  if (typeof forwardedToMain === 'boolean') {
    completionUpdates.forwardedToMain = forwardedToMain;
  }

  if (typeof resultSource === 'string' && resultSource.length > 0) {
    completionUpdates.resultSource = resultSource;
  }

  if (Object.keys(completionUpdates).length === 0) {
    return null;
  }

  fs.mkdirSync(STATE_DIR, { recursive: true });

  const statePath = path.join(STATE_DIR, `${runId}.json`);
  let currentRecord = {};

  if (fs.existsSync(statePath)) {
    try {
      currentRecord = JSON.parse(fs.readFileSync(statePath, 'utf8'));
    } catch {
      currentRecord = {};
    }
  }

  const nextRecord = {
    ...currentRecord,
    runId,
    ...completionUpdates,
  };

  fs.writeFileSync(statePath, `${JSON.stringify(nextRecord, null, 2)}\n`, 'utf8');

  return {
    statePath,
    record: nextRecord,
    updatedFields: Object.keys(completionUpdates),
  };
}

function parseTime(value) {
  if (typeof value !== 'string' || value.length === 0) {
    return null;
  }

  const timestamp = Date.parse(value);
  return Number.isNaN(timestamp) ? null : timestamp;
}

function recomputeStatus(payload) {
  if (!payload || typeof payload !== 'object') {
    return 'not_implemented';
  }

  const completionReceivedAt = payload.completionReceivedAt ?? payload.completionReceiptAt ?? null;
  if (parseTime(completionReceivedAt) !== null) {
    return 'completed';
  }

  const hasDispatch = [payload.runId, payload.childSessionKey, payload.dispatchAt, payload.expectedBy].every(
    (value) => typeof value === 'string' && value.length > 0,
  );

  if (!hasDispatch) {
    return 'not_implemented';
  }

  const childRunStatus = typeof payload.childRunStatus === 'string'
    ? payload.childRunStatus.trim().toLowerCase()
    : null;

  if (childRunStatus === 'done') {
    return 'done_but_not_forwarded';
  }

  const expectedBy = parseTime(payload.expectedBy);
  const currentTime = parseTime(payload.currentTime);

  if (expectedBy === null || currentTime === null) {
    return 'not_implemented';
  }

  if (currentTime > expectedBy) {
    return 'suspect_delivery_failure';
  }

  return 'active';
}

function decideRecoveryAction(payload, status) {
  if (!payload || typeof payload !== 'object') {
    return null;
  }

  if (status !== 'done_but_not_forwarded') {
    return null;
  }

  const attemptCountRaw = payload.recoveryAttemptCount;
  const recoveryAttemptCount = Number.isFinite(attemptCountRaw)
    ? attemptCountRaw
    : Number.parseInt(String(attemptCountRaw ?? '0'), 10);

  if (!Number.isNaN(recoveryAttemptCount) && recoveryAttemptCount >= 2) {
    return 'blocked';
  }

  if (!Number.isNaN(recoveryAttemptCount) && recoveryAttemptCount >= 1) {
    return 'respawn';
  }

  return 'fetch_history';
}

function buildReportingPayload(payload, status, recoveryDecision) {
  const detail = {
    runId: typeof payload?.runId === 'string' ? payload.runId : null,
    childSessionKey: typeof payload?.childSessionKey === 'string' ? payload.childSessionKey : null,
    status,
    recoveryDecision,
  };

  if (status === 'suspect_delivery_failure') {
    return {
      ownerVisible: true,
      category: 'suspect_delivery_failure',
      decision: 'report',
      summary: 'Subagent delivery is suspected to have failed after crossing SLA.',
      detail,
    };
  }

  if (status === 'done_but_not_forwarded' && recoveryDecision === 'fetch_history') {
    return {
      ownerVisible: true,
      category: 'done_but_not_forwarded',
      decision: 'fetch_history',
      summary: 'Child run is done but no forwarded completion receipt is confirmed yet.',
      detail,
    };
  }

  if (status === 'done_but_not_forwarded' && recoveryDecision === 'respawn') {
    return {
      ownerVisible: true,
      category: 'done_but_not_forwarded',
      decision: 'respawn',
      summary: 'Child run is done but recovery already failed once; respawn is the next conservative step.',
      detail,
    };
  }

  if (status === 'done_but_not_forwarded' && recoveryDecision === 'blocked') {
    return {
      ownerVisible: true,
      category: 'done_but_not_forwarded',
      decision: 'blocked',
      summary: 'Child run is still not forwarded after repeated recovery attempts; owner attention is required.',
      detail,
    };
  }

  if (status === 'completed') {
    return {
      ownerVisible: false,
      category: 'completed',
      decision: 'none',
      summary: 'Completion receipt is present; no owner-visible report is needed.',
      detail,
    };
  }

  if (status === 'active') {
    return {
      ownerVisible: false,
      category: 'active',
      decision: 'none',
      summary: 'Dispatch is still within SLA; no owner-visible report is needed.',
      detail,
    };
  }

  return {
    ownerVisible: false,
    category: status,
    decision: 'none',
    summary: 'No owner-visible report is needed.',
    detail,
  };
}

function main() {
  const args = parseArgs(process.argv.slice(2));

  if (args.help) {
    printHelp();
    process.exit(0);
  }

  const input = tryReadInput(args.input);
  const inputPayload = input.exists ? tryParseJson(input.content) : null;
  const dispatchWrite = writeDispatchReceiptState(inputPayload);
  const completionWrite = writeCompletionReceiptState(inputPayload);
  const status = recomputeStatus(inputPayload);
  const recoveryDecision = decideRecoveryAction(inputPayload, status);
  const reporting = buildReportingPayload(inputPayload, status, recoveryDecision);

  if ('content' in input) {
    delete input.content;
  }

  const records = [];
  if (dispatchWrite) {
    records.push(dispatchWrite.record);
  }
  if (completionWrite) {
    records.push(completionWrite.record);
  }

  const response = {
    ok: true,
    tool: 'subagent_delivery_watchdog',
    version: 'skeleton-v5',
    mode: 'receipt-write',
    args: {
      compact: args.compact,
      input: args.input,
    },
    input,
    result: {
      status,
      message: status === 'not_implemented'
        ? 'Dispatch and completion receipt writes are implemented; status recompute only handles basic active/suspect/completed states plus conservative recovery/reporting decisions.'
        : 'Basic watchdog status recompute completed.',
      recoveryDecision,
      reporting,
      records,
      dispatchReceiptWrite: dispatchWrite,
      completionReceiptWrite: completionWrite,
    },
  };

  const spacing = args.compact ? 0 : 2;
  process.stdout.write(`${JSON.stringify(response, null, spacing)}\n`);
}

main();