@planu/cli 4.14.1 → 5.0.0

package/dist/types/session-safeguard.d.ts

@@ -7,40 +7,9 @@ export type AutopushResult = {
     reason: 'disabled' | 'nothing-to-push' | 'diverged' | 'no-upstream';
     message: string;
 };
-export interface UnpushedCommitInfo {
-    count: number;
-    branch: string;
-    /** Hours since the oldest unpushed commit was authored. */
-    oldestAgeHours: number;
-}
 export interface SessionContextFreshnessResult {
     stale: boolean;
     /** Age in days of session-context.md relative to newest spec.md (negative means session-context is newer). */
     ageDays: number;
 }
-export type LearningCategory = 'bug' | 'pattern' | 'decision' | 'estimate';
-export type LearningSource = 'autopilot' | 'user';
-export interface LearningEntry {
-    timestamp: string;
-    category: LearningCategory;
-    content: string;
-    source: LearningSource;
-}
-export interface LearningsBuffer {
-    version: 1;
-    entries: LearningEntry[];
-}
-export interface CheckpointRunnerOptions {
-    projectPath: string;
-    dryRun?: boolean;
-    autopush?: boolean;
-    autopushBranches?: string[];
-}
-export interface CheckpointResult {
-    sessionContextRefreshed: boolean;
-    learningsFlushed: number;
-    unpushedCommits: UnpushedCommitInfo | null;
-    pushed?: AutopushResult;
-    humanSummary: string;
-}
 //# sourceMappingURL=session-safeguard.d.ts.map

package/dist/types/spec/canonical-repair.d.ts

@@ -0,0 +1,81 @@
+import type { SpecStatus } from '../common/index.js';
+import type { Spec } from './core.js';
+export interface LifecycleOverride {
+    readonly canonicalUuid: string;
+    readonly retainedStatus: SpecStatus;
+    readonly reason: string;
+}
+export interface CanonicalRepairManifest {
+    readonly projectId: string;
+    readonly sourceDigest: string;
+    readonly sourceProjectAliases: readonly string[];
+    readonly canonicalSourceProjectAlias: string;
+    readonly foreignOwnerSingletonIds: readonly string[];
+    readonly lifecycleOverrides?: Readonly<Record<string, LifecycleOverride>>;
+}
+export interface CanonicalRepairPlan {
+    readonly changed: boolean;
+    readonly projectId: string;
+    readonly sourceDigest: string;
+    readonly manifestDigest: string;
+    readonly planDigest: string;
+    readonly resultDigest: string;
+    readonly duplicateGroups: number;
+    readonly foreignOwnerSingletons: number;
+    readonly fieldChanges: readonly Record<string, unknown>[];
+    readonly artifactId: string;
+    readonly resultBytes: Buffer;
+    readonly finalizationDegraded?: boolean;
+}
+export interface CanonicalRepairReview {
+    readonly reviewer: string;
+    readonly verdict: string;
+    readonly sourceDigest: string;
+    readonly manifestDigest: string;
+    readonly planDigest: string;
+    readonly resultDigest: string;
+}
+export interface RepairCanonicalStoreInput {
+    readonly projectId: string;
+    readonly manifestPath: string;
+    readonly dryRun?: boolean;
+    readonly reviewPath?: string;
+    readonly expectedSourceDigest?: string;
+    readonly expectedManifestDigest?: string;
+    readonly expectedPlanDigest?: string;
+    readonly expectedResultDigest?: string;
+    readonly authorizationReason?: string;
+    /** Test-only I/O seam; normal callers always use durable filesystem operations. */
+    readonly io?: CanonicalRepairIo;
+}
+export interface CanonicalRepairIo {
+    readonly readFile?: (path: string) => Promise<Buffer>;
+    readonly writeAtomic?: (path: string, bytes: Buffer | string) => Promise<void>;
+    readonly mkdir?: (path: string) => Promise<void>;
+    readonly withLock?: <T>(projectId: string, fn: () => Promise<T>) => Promise<T>;
+}
+export interface CanonicalRepairReceipt {
+    readonly schemaVersion: 1;
+    readonly state: 'prepared' | 'committed';
+    readonly projectId: string;
+    readonly reviewer: string;
+    readonly verdict: string;
+    readonly authorizationReason: string;
+    readonly sourceDigest: string;
+    readonly manifestDigest: string;
+    readonly planDigest: string;
+    readonly resultDigest: string;
+    readonly backupArtifactId: string;
+    readonly backupDigest: string;
+    readonly removedRows: readonly Spec[];
+    readonly singletonOwnershipChanges: readonly Record<string, unknown>[];
+    readonly retainedUuids: readonly Record<string, unknown>[];
+    readonly aliasesAdded: readonly Record<string, unknown>[];
+    readonly fieldChanges: readonly Record<string, unknown>[];
+}
+/** Internal parsed representation of the legacy or enveloped canonical store. */
+export interface CanonicalRepairRawStore {
+    readonly envelope: boolean;
+    readonly rows: Spec[];
+}
+//# sourceMappingURL=canonical-repair.d.ts.map

package/dist/types/spec/canonical-repair.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=canonical-repair.js.map

package/dist/types/spec/core.d.ts

@@ -15,8 +15,16 @@ export interface StatusHistoryEntry {
     readonly transitionId?: string;
     /** Optional work scheduled after the durable transition boundary. */
     readonly pendingBackgroundActions?: readonly string[];
+    /** Opaque binding to the repository root authorized to execute pending work. */
+    readonly transitionRootBinding?: string;
     /** Durable execution state for optional post-commit work. */
     readonly postCommitTasks?: readonly PostCommitTaskReceipt[];
+    /** SPEC-1232 request bound in the same canonical status mutation. */
+    readonly reconciliationRequestId?: string;
+    /** SPEC-1232 deterministic request/evidence binding digest. */
+    readonly reconciliationBindingDigest?: string;
+    /** Lifecycle trigger persisted with the canonical transition receipt. */
+    readonly trigger?: string;
 }
 export type PostCommitTaskStatus = 'pending' | 'running' | 'done' | 'failed';
 export interface PostCommitTaskReceipt {
@@ -41,6 +49,12 @@ export interface Spec {
     id: string;
     /** SPEC-601: Globally unique identifier for cross-project portability. */
     uuid?: string;
+    /**
+     * Historical canonical UUIDs retained after an administrative identity repair.
+     * An alias is an identity, not display metadata: it must be unique across the
+     * complete canonical store and may never duplicate a primary UUID.
+     */
+    uuidAliases?: string[];
     title: string;
     slug: string;
     feature?: string;

package/dist/types/spec/index.d.ts

@@ -1,4 +1,5 @@
 export * from './core.js';
+export * from './canonical-repair.js';
 export * from './clarification.js';
 export * from './inputs.js';
 export * from './agent.js';

package/dist/types/spec/index.js

@@ -1,6 +1,7 @@
 // Planu — Spec types barrel
 // Re-exports all spec types from domain sub-files.
 export * from './core.js';
+export * from './canonical-repair.js';
 export * from './clarification.js';
 export * from './inputs.js';
 export * from './agent.js';

package/dist/types/spec/inputs.d.ts

@@ -2,6 +2,9 @@ import type { SpecStatus, SpecType, SpecScope, SpecTarget, ToolResult } from '..
 import type { Actuals } from '../estimation.js';
 import type { ProjectKnowledge } from '../project.js';
 import type { Spec, ChecklistCategory, SpecDiagram, SpecSplitSuggestion, ReconcileChange } from './core.js';
+export interface ReconciliationInvocationContext {
+    surface: 'local-mcp' | 'http' | 'dashboard' | 'direct' | 'unknown';
+}
 export interface CreateSpecInput {
     title: string;
     description: string;
@@ -89,6 +92,12 @@ export interface UpdateStatusInput {
      * Must be ≥30 characters explaining why the spec is being reopened.
      */
     reason?: string;
+    /** Stable idempotency key for a trusted implementing → review reconciliation. */
+    reconciliationRequestId?: string;
+    /** Latest canonical implementing transition receipt expected by reconciliation. */
+    expectedImplementingTransitionId?: string;
+    /** SHA-256 digest of the independent changes-requested validation report. */
+    implementationReviewDigest?: string;
     /**
      * SPEC-769: Force-approve a spec that scored below 70 on the readiness gate.
      * When true, the transition proceeds and qualityWarnings[] is written to spec.md frontmatter.
@@ -200,6 +209,26 @@ export interface SpecMigrationDeps {
     listSpecs: (projectId: string) => Promise<Spec[]>;
     updateSpec: (projectId: string, specId: string, updates: Partial<Spec>) => Promise<Spec>;
 }
+export type FilesystemImportFailureCode = 'READ_FAILED' | 'INVALID_CONTRACT' | 'CREATE_FAILED' | 'INCOMPATIBLE_IDENTITY';
+export interface FilesystemImportFailure {
+    specId: string;
+    path: string;
+    code: FilesystemImportFailureCode;
+}
+export interface FilesystemImportResult {
+    importedCount: number;
+    importedSpecIds: string[];
+    failures: FilesystemImportFailure[];
+    errors: string[];
+}
+export interface FilesystemImportDeps {
+    listSpecs: (projectId: string) => Promise<Spec[]>;
+    createSpec: (projectId: string, spec: Spec) => Promise<Spec>;
+    getSpecFresh?: (projectId: string, specId: string) => Promise<Spec | null>;
+}
+export interface PortableIndexReconciliationResult extends FilesystemImportResult {
+    repositoryFilesChanged: string[];
+}
 export type ChallengeSpecFocus = 'failures' | 'concurrency' | 'scale' | 'security' | 'data-consistency';
 export type { ScopeFilter, ScopeFilterConfig } from './core.js';
 export interface SplitAnalysisInput {

package/dist/types/spec-format.d.ts

@@ -152,4 +152,28 @@ export interface ImplementationContractIssue {
     code: 'contract_missing' | 'contract_subsection_missing' | 'contract_subsection_empty' | 'contract_filler' | 'contract_needs_decision' | 'contract_unmapped_criterion' | 'contract_manual_verification_vague';
     message: string;
 }
+export type UnifiedSpecCandidateIssueCode = 'MISSING_REQUIRED_SECTION' | 'DUPLICATE_REQUIRED_SECTION' | 'MISORDERED_REQUIRED_SECTION' | 'EMBEDDED_REQUIRED_SECTION' | 'UNRESOLVED_CONTRACT_PLACEHOLDER' | 'MISSING_EXECUTABLE_CRITERIA' | 'UNGROUNDED_FILE_OWNERSHIP';
+export interface UnifiedSpecCandidateIssue {
+    code: UnifiedSpecCandidateIssueCode;
+    message: string;
+    section?: string;
+    path?: string;
+}
+export interface UnifiedSpecCandidateValidation {
+    valid: boolean;
+    issues: UnifiedSpecCandidateIssue[];
+}
+export interface CanonicalUnifiedSpecInput {
+    leanSpecBody: string;
+    sourceDescription: string;
+    technicalBody: string;
+    implementationContract: string;
+    criteria: LeanCriterion[];
+    files: {
+        create: LeanFileEntry[];
+        modify: LeanFileEntry[];
+        test: LeanFileEntry[];
+    };
+    outOfScope: string[];
+}
 //# sourceMappingURL=spec-format.d.ts.map

package/dist/types/telemetry.d.ts

@@ -4,7 +4,7 @@ export interface GeoData {
     city: string;
     timezone: string;
 }
-export type TelemetryEventName = 'init_project' | 'create_spec' | 'tool_used' | 'tool_error' | 'tool_blocked' | 'trial_started'
+export type TelemetryEventName = 'init_project' | 'create_spec' | 'tool_used' | 'tool_error' | 'tool_blocked'
 /** SPEC-705: Emitted when agent parallelism is downgraded due to host RAM constraints. */
  | 'ram_guardrail_downgrade'
 /** SPEC-727: Emitted when a panel is aborted because two specialists share the same (modelId, promptHash). */
@@ -31,7 +31,10 @@ export interface ConfigureTelemetryInput {
 }
 export interface TelemetryResult {
     action: string;
+    /** Current versioned consent, independent from runtime delivery configuration. */
     enabled: boolean;
+    /** A valid endpoint and a non-empty operator token are both available. */
+    configured: boolean;
     consentVersion?: number;
     message: string;
 }

package/dist/types/transport.d.ts

@@ -1,7 +1,5 @@
 export type TransportType = 'stdio' | 'http';
 export interface HttpSessionContext {
-    /** License key provided via HTTP header for this session */
-    licenseKey?: string;
     /** MCP session ID */
     sessionId: string;
     /** Aborts when the active HTTP response loses its client connection. */

package/dist/types/usage.d.ts

@@ -1,30 +1,15 @@
-import type { PricingTier } from './common/primitives.js';
 export interface UsageEvent {
     /** Tool name that was called */
     readonly toolName: string;
-    /** Tier at the time of the call */
-    readonly tier: PricingTier;
     /** ISO 8601 timestamp */
     readonly timestamp: string;
-    /** Whether the call succeeded (not blocked by license gate) */
+    /** Whether the call succeeded */
     readonly success: boolean;
 }
 export interface UsageLog {
     /** Array of usage events */
     readonly events: readonly UsageEvent[];
 }
-export interface DailyUsage {
-    /** Date string YYYY-MM-DD */
-    readonly date: string;
-    /** Number of tool calls today */
-    readonly callCount: number;
-    /** ISO 8601 timestamp of the last tool call */
-    readonly lastCallAt: string;
-}
-export interface TrialState {
-    /** ISO 8601 timestamp of the first Planu execution ever */
-    readonly firstRunAt: string;
-}
 export interface ToolHealthEntry {
     readonly name: string;
     readonly totalCalls: number;
@@ -38,8 +23,6 @@ export interface UsageStats {
     readonly totalCalls: number;
     /** Calls grouped by tool name */
     readonly callsByTool: Record<string, number>;
-    /** Calls grouped by tier */
-    readonly callsByTier: Record<string, number>;
     /** Top N most-used tools */
     readonly topTools: readonly {
         readonly name: string;
@@ -49,29 +32,11 @@ export interface UsageStats {
     readonly activeSpecs: number;
     /** Number of active projects */
     readonly activeProjects: number;
-    /** Current tier */
-    readonly currentTier: PricingTier;
-    /** Days since first run */
-    readonly daysSinceFirstRun: number;
-    /** Whether in trial period */
-    readonly isTrialActive: boolean;
-    /** Remaining daily calls (Starter only, -1 for unlimited) */
-    readonly remainingDailyCalls: number;
     /** Per-tool health breakdown — sorted by error rate descending (most broken first) */
     readonly toolHealthBreakdown: readonly ToolHealthEntry[];
     /** Tool names with 0 calls in the reporting period (candidates for removal) */
     readonly deadTools: readonly string[];
 }
-export interface RateLimitResult {
-    /** Whether the call is allowed */
-    readonly allowed: boolean;
-    /** If not allowed, the reason */
-    readonly reason: 'daily_limit' | 'cooldown' | null;
-    /** Human-readable message */
-    readonly message: string;
-    /** Remaining daily calls (-1 = unlimited) */
-    readonly remainingCalls: number;
-}
 export interface UsageStatsInput {
     readonly period?: '7d' | '30d' | 'all';
 }

package/dist/types/usage.js

@@ -1,4 +1,4 @@
 // types/usage.ts — Usage tracking and analytics types for Planu SDD MCP Server.
-// Supports local telemetry, trial enforcement, rate limiting, and usage reporting.
+// Supports neutral local telemetry and usage reporting.
 export {};
 //# sourceMappingURL=usage.js.map

package/dist/types/validate-worker.d.ts

@@ -37,6 +37,12 @@ export interface ValidateWorkerProgress {
     readonly phase: string;
     readonly command: string;
     readonly durationMs: number;
+    /** Number of validation gates that have reached a terminal state. */
+    readonly completedGates: number;
+    /** Stable gate count for the current validation run. */
+    readonly totalGates: number;
+    /** ISO timestamp of the most recent semantic progress transition. */
+    readonly lastProgressAt: string;
     readonly filesScanned?: number;
     readonly status: 'running' | 'passed' | 'failed' | 'cancelled';
     readonly remediation?: string;

package/dist/types/validation-receipt.d.ts

@@ -93,7 +93,7 @@ export interface ValidationReceiptPersistence {
     readCurrent(projectId: string, specId: string): Promise<ValidationReceipt | undefined>;
     readCurrentBindings(projectId: string, specId: string): Promise<ValidationReceiptBindings | undefined>;
     projectCurrentBindings(bindings: ValidationReceiptBindings): Promise<void>;
-    invalidateCurrentBindings(projectId: string, specId: string): Promise<void>;
+    invalidateCurrentBindings(projectId: string, specId: string, receiptId?: string): Promise<void>;
     readLog(logDigest: string): Promise<Buffer | undefined>;
     logPath(logDigest: string): string;
 }

package/dist/types/validation.d.ts

@@ -18,13 +18,13 @@ export interface ValidationError {
 }
 /**
  * A non-blocking issue. Same shape as ValidationError; severity is implicit
- * from array placement in ValidationResult.
+ * from array placement in SpecValidationResult.
  */
 export type ValidationWarning = ValidationError;
 /**
  * Unified result returned by validateSpecFormat().
  */
-export interface ValidationResult {
+export interface SpecValidationResult {
     valid: boolean;
     errors: ValidationError[];
     warnings: ValidationWarning[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.14.1",
+  "version": "5.0.0",
   "description": "Planu — MCP Server for Spec Driven Development with native Rust acceleration for hot paths. Cross-platform (Linux/macOS/Windows, x64/arm64, glibc/musl).",
   "type": "module",
   "main": "dist/index.js",
@@ -12,6 +12,7 @@
     "dist/",
     "!dist/**/*.map",
     "!dist/engine/*.node",
+    "scripts/lib/pending-release-file.mjs",
     "src/i18n/messages/",
     "planu-native.json",
     "planu-plugin.json",
@@ -34,14 +35,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "4.14.1",
-    "@planu/core-darwin-x64": "4.14.1",
-    "@planu/core-linux-arm64-gnu": "4.14.1",
-    "@planu/core-linux-arm64-musl": "4.14.1",
-    "@planu/core-linux-x64-gnu": "4.14.1",
-    "@planu/core-linux-x64-musl": "4.14.1",
-    "@planu/core-win32-arm64-msvc": "4.14.1",
-    "@planu/core-win32-x64-msvc": "4.14.1"
+    "@planu/core-darwin-arm64": "5.0.0",
+    "@planu/core-darwin-x64": "5.0.0",
+    "@planu/core-linux-arm64-gnu": "5.0.0",
+    "@planu/core-linux-arm64-musl": "5.0.0",
+    "@planu/core-linux-x64-gnu": "5.0.0",
+    "@planu/core-linux-x64-musl": "5.0.0",
+    "@planu/core-win32-arm64-msvc": "5.0.0",
+    "@planu/core-win32-x64-msvc": "5.0.0"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -53,6 +54,9 @@
     "build:rust:check-tools": "bash scripts/build-rust-local.sh --check-tools",
     "check:native-version-parity": "node scripts/check-native-version-parity.mjs",
     "check:release-authorities": "node scripts/check-release-authorities.mjs",
+    "check:commercial-surfaces": "node scripts/check-commercial-surfaces.mjs",
+    "check:tool-registration": "bash scripts/check-tool-registration.sh",
+    "generate:host-tool-registry": "node scripts/generate-host-tool-registry.mjs",
     "release:local": "bash scripts/release-local.sh",
     "release:local:all": "bash scripts/release-local.sh --all",
     "release:publish": "bash scripts/release-local.sh --all --publish",
@@ -81,8 +85,8 @@
     "native:project-graph:e2e": "PLANU_NATIVE_E2E=1 vitest run tests/integration/native-project-graph-e2e.test.ts",
     "native:project-graph:benchmark": "node scripts/benchmark-native-performance.mjs --operation project_graph_query --samples 30 --warmups 5 --project-path . --spec-id SPEC-1119 --json",
     "benchmark:execution-kernel": "pnpm build && node scripts/benchmark-execution-kernel.mjs",
-    "check": "pnpm typecheck && pnpm lint && pnpm format:check && pnpm check:release-authorities && pnpm check:public-privacy && pnpm check:website-proof && pnpm check:donation-assets && pnpm check:website-public-assets",
-    "check:strict": "pnpm check && pnpm check:environment-schema && pnpm audit:hardcodes && pnpm audit:deadcode && pnpm audit:circular && pnpm audit:types && pnpm audit:security && pnpm audit:licenses && pnpm audit:i18n",
+    "check": "pnpm typecheck && pnpm lint && pnpm format:check && pnpm check:release-authorities && pnpm check:commercial-surfaces && pnpm check:tool-registration && pnpm check:public-privacy && pnpm check:website-proof && pnpm check:donation-assets && pnpm check:website-public-assets",
+    "check:strict": "pnpm check && pnpm generate:host-tool-registry -- --check && pnpm check:native-version-parity && pnpm check:environment-schema && pnpm audit:hardcodes && pnpm audit:deadcode && pnpm audit:circular && pnpm audit:types && pnpm audit:security && pnpm audit:licenses && pnpm audit:i18n",
     "check:reliability": "node scripts/check-reliability-policies.mjs",
     "check:environment-schema": "node scripts/check-environment-schema.mjs",
     "test:contracts": "vitest run tests/contracts tests/integration/package-consumer-hono.test.ts",
@@ -113,7 +117,7 @@
     "prepublishOnly": "bash scripts/prepublish-guard.sh",
     "prepack": "pnpm build:ts && pnpm package:size",
     "test:debug": "vitest run --inspect-brk --single-thread",
-    "validate": "pnpm typecheck && pnpm verify:typescript-migration && pnpm lint && pnpm format:check && pnpm test",
+    "validate": "pnpm build && pnpm typecheck && pnpm verify:typescript-migration && pnpm lint && pnpm format:check && pnpm test",
     "docker:build": "docker build -t planu .",
     "docker:run": "docker compose up",
     "publish:blog": "node scripts/publish-blog.mjs",

package/planu-native.json

@@ -1,7 +1,7 @@
 {
   "name": "dev.planu.native",
   "displayName": "Planu Native Lightweight Surface",
-  "version": "4.14.1",
+  "version": "5.0.0",
   "packageName": "@planu/cli",
   "modes": {
     "lightweight": {

package/planu-plugin.json

@@ -2,66 +2,49 @@
   "name": "dev.planu.cli",
   "displayName": "Planu — Spec Driven Development",
   "description": "Manage software specs, estimations, and autonomous SDD workflows. Language-agnostic MCP server for Claude Code.",
-  "version": "4.14.1",
+  "version": "5.0.0",
   "icon": "assets/plugin/icon.svg",
-  "command": [
-    "npx",
-    "@planu/cli@latest"
-  ],
+  "command": ["npx", "@planu/cli@latest"],
   "packageName": "@planu/cli",
   "capabilities": {
     "tools": [
       "planu_status",
+      "session_checkpoint",
       "facilitate",
       "init_project",
       "clarify_requirements",
       "create_spec",
+      "list_specs",
       "challenge_spec",
       "check_readiness",
       "update_status",
+      "update_status_batch",
       "package_handoff",
       "validate",
+      "get_job",
+      "watch_job",
+      "cancel_job",
+      "restart_job",
       "reconcile_spec",
       "create_rule",
       "create_skill",
-      "skill_search"
+      "skill_search",
+      "configure_code_graph",
+      "code_graph_status",
+      "submit_feedback",
+      "triage_feedback",
+      "resolve_feedback",
+      "sync_feedback",
+      "feedback_status"
     ],
-    "resources": [
-      "planu://specs/list",
-      "planu://specs/{id}",
-      "planu://project/status",
-      "planu://roadmap"
-    ],
-    "prompts": [
-      "create-spec-from-idea",
-      "review-spec-readiness",
-      "generate-implementation-plan"
-    ],
-    "subagents": [
-      "sdd-orchestrator",
-      "spec-challenger",
-      "test-generator"
-    ]
-  },
-  "compatibility": {
-    "minimumHostVersion": "1.0.0",
-    "requiredFeatures": [
-      "mcp-tools",
-      "file-editing"
-    ]
+    "resources": ["planu://specs/list", "planu://specs/{id}", "planu://project/status", "planu://roadmap"],
+    "prompts": ["create-spec-from-idea", "review-spec-readiness", "generate-implementation-plan"],
+    "subagents": ["sdd-orchestrator", "spec-challenger", "test-generator"]
   },
+  "compatibility": { "minimumHostVersion": "1.0.0", "requiredFeatures": ["mcp-tools", "file-editing"] },
   "repository": "https://github.com/planu-dev/planu",
   "author": "Planu",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://planu.dev",
-  "keywords": [
-    "sdd",
-    "spec-driven-development",
-    "mcp",
-    "specs",
-    "planning",
-    "ai",
-    "bdd",
-    "tdd"
-  ]
+  "keywords": ["sdd", "spec-driven-development", "mcp", "specs", "planning", "ai", "bdd", "tdd"]
 }

package/scripts/lib/pending-release-file.mjs

@@ -0,0 +1,93 @@
+import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+
+const DEFAULT_TIMEOUT_MS = 5_000;
+const POLL_INTERVAL_MS = 10;
+const ABANDONED_LOCK_MS = 30_000;
+
+function delay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code !== 'ESRCH';
+  }
+}
+
+async function removeAbandonedLock(lockPath) {
+  try {
+    const owner = JSON.parse(await readFile(`${lockPath}/owner.json`, 'utf8'));
+    if (Number.isInteger(owner.pid) && owner.pid > 0 && !isProcessAlive(owner.pid)) {
+      await rm(lockPath, { recursive: true, force: true });
+      return true;
+    }
+  } catch {
+    try {
+      const lockStat = await stat(lockPath);
+      if (Date.now() - lockStat.mtimeMs > ABANDONED_LOCK_MS) {
+        await rm(lockPath, { recursive: true, force: true });
+        return true;
+      }
+    } catch {
+      return true;
+    }
+  }
+  return false;
+}
+
+async function acquireLock(pendingPath, { timeoutMs, signal }) {
+  const lockPath = `${pendingPath}.lock`;
+  const deadline = Date.now() + timeoutMs;
+  while (true) {
+    if (signal?.aborted) throw new Error('pending release lock acquisition aborted');
+    try {
+      await mkdir(lockPath);
+      await writeFile(
+        `${lockPath}/owner.json`,
+        `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`,
+        { flag: 'wx', mode: 0o600 },
+      );
+      return lockPath;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') {
+        await rm(lockPath, { recursive: true, force: true });
+        throw error;
+      }
+      if (await removeAbandonedLock(lockPath)) continue;
+      if (Date.now() >= deadline) {
+        throw new Error(`timed out waiting for pending release lock: ${lockPath}`);
+      }
+      await delay(POLL_INTERVAL_MS);
+    }
+  }
+}
+
+export async function withPendingReleaseLock(pendingPath, options, task) {
+  const lockPath = await acquireLock(pendingPath, {
+    timeoutMs: options?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    signal: options?.signal,
+  });
+  try {
+    return await task();
+  } finally {
+    await rm(lockPath, { recursive: true, force: true });
+  }
+}
+
+export async function writePendingReleaseLedger(pendingPath, entries) {
+  const temporaryPath = `${pendingPath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await writeFile(temporaryPath, `${JSON.stringify(entries, null, 2)}\n`, {
+      encoding: 'utf8',
+      flag: 'wx',
+      mode: 0o644,
+    });
+    await rename(temporaryPath, pendingPath);
+  } catch (error) {
+    await rm(temporaryPath, { force: true });
+    throw error;
+  }
+}