iit-mcp-autotask 0.6.0 → 0.7.0

package/README.md

@@ -147,26 +147,47 @@ the live write leg on throwaway data before relying on it (B7 in the 0.6.0 plan)
 
 One process owns a state dir through `<state dir>/lock` (its host, pid and a per-boot id). Run
 exactly one container per state dir: never share it between replicas or a rolling deploy's old and
-new containers. After a crash,
-a SIGKILL or an OOM kill the next boot takes the lock over by itself when the old holder is gone,
-including a container where node is PID 1 again (the boot id tells the runs apart). Two cases need
-an operator:
-
-- **`locked by a running process (pid N)`** while no server is running on that state dir: an
-  unrelated process now has that pid (pid reuse on a long-lived host). Confirm with `ps -p N` that
-  it is not this server, then delete `<state dir>/lock` and start again.
+new containers.
+
+The holder refreshes a lease heartbeat (`<state dir>/lock.lease`) every 5 s, and a lease older
+than 15 s (3 refresh cycles) is expired. The takeover rules:
+
+- A live holder is never taken: a FRESH lease vetoes any takeover, whatever the pid probe says.
+- After a crash, a SIGKILL or an OOM kill the next boot takes the lock over by itself when the
+  old holder is gone, including a container where node is PID 1 again (the boot id tells the runs
+  apart).
+- A container replacement needs no manual unlock **when the replacement container keeps the same
+  hostname** — a fixed `hostname` in the compose / docker run config: in the replacement container
+  the old holder's pid can still "answer" (the new pid namespace recycled the number), but its
+  lease is expired 15 s after the old container stopped, so the next boot takes the lock over on
+  its own. With a new hostname (the docker default: the container id) the R6 host refusal applies
+  and the operator deletes `<state dir>/lock` (the case below). Every takeover is appended to the
+  `audit.jsonl` hash chain as a `lock_takeover` line, and `/ready` reports the lock's age, holder
+  id and lease freshness, so an orchestrator can tell a stale lock from a live one.
+
+Cases that need an operator:
+
+- **`locked by a running process (pid N)`** (with or without `; its lease is X ms old`): another
+  live server holds this state dir (the lease-less form is a pre-0.6.0 server, which never wrote
+  one). Confirm with `ps -p N` that it is not a server you forgot, stop it, and start again. If it
+  is really gone and the lock's pid is dead, no unlock is needed: the next boot takes the lock
+  over immediately (a lease-less pre-0.6.0 lock has no lease to wait out). A live pid with no
+  lease is never taken over - stop that server, or delete `<state dir>/lock`.
 - **`locked by host H (pid N); one container per state dir`**: the lock belongs to another host or
   container, whose pids mean nothing here, so it is never taken over automatically. Make sure the
   server on H is stopped (or the container is gone), then delete `<state dir>/lock` and start
   again. After replacing a container on a persistent volume this happens once, unless the
   container keeps a fixed `hostname`.
+- **`lock.lease exists but is not a readable lease`**: the lease file is corrupt (our writes are
+  atomic renames, so this is not a crash remnant of our own). Make sure no server is running on
+  this state dir, delete `<state dir>/lock.lease`, and start again.
 - **`another process is taking over the lock (<state dir>/lock.takeover)`**: a boot crashed in the
-  middle of a takeover, or two boots raced. Make sure no other server is starting on this state
+  middle of a takeover, a disk error hit mid-create, or two boots raced. Make sure no other server is starting on this state
   dir, delete `<state dir>/lock.takeover`, and start again.
 
 Never delete `lock` while a server is running: writes stop (`STATE_UNAVAILABLE`) the moment the
-running server notices it no longer holds the lock. Keep the rest of the state dir; `audit.jsonl`
-is the write history.
+running server notices it no longer holds the lock, and it stops refreshing the lease. Keep the
+rest of the state dir; `audit.jsonl` is the write history.
 
 ### Query results: TSV, `output_path` and the saved-file shape
 
@@ -370,7 +391,7 @@ preview/apply path; a plan previewed under 0.6.0 cannot be applied after a rollb
 |----------|---------|------|
 | `POST /mcp` | the canonical MCP endpoint (Streamable HTTP transport); Host/Origin validated, 1 MiB body cap | a bearer token in `tokens` mode; per-request `X-Autotask-*` headers for tool calls |
 | `GET /health` | process alive — pre-auth, **no vendor call** (container healthcheck) | none |
-| `GET /ready` | config valid, SDK plan-hash pin checked, server initialised, client factory ready — **no live vendor call** (credentials are request-scoped) | none |
+| `GET /ready` | config valid, SDK plan-hash pin checked, server initialised, client factory ready — **no live vendor call** (credentials are request-scoped). In an operator deployment the payload also carries `lock` (the state lock's age, holder id and lease freshness — see "The state lock: recovery") | none |
 | `GET /doctor` | zero-wire credential/config preflight: per credential field `present`/`len`/`prefix2`/`shapeOk` (`AUTOTASK_SECRET`'s prefix is masked to `[REDACTED]` — no character of a secret is ever emitted; identifiers keep their format prefix), the base-url + allow-list resolution (`default_only` / `allow_list` / `default_and_list` / `any`), the SDK plan-hash gate status and the host-policy mode — **no vendor call, by construction** | Host/Origin validated; a bearer token in `tokens` mode |
 | `GET /metadata` | server identity + the MCP protocol **era pair** (baseline `2026-07-28` + legacy fallback `2025-11-25`) + capability-manifest pointer + the `deployment` block (profile, toolsets, approval mode, caller auth, rate limiting) — the served payload is the repo's `server.json` + build stamp | Host/Origin validated; a bearer token in `tokens` mode |
 
@@ -580,8 +601,10 @@ guards (rate limiter, 429 cooldown) — a worse security posture, not a safer on
 
 - **Redaction on by default, no opt-out surface:** the SDK redacts response PII/confidential fields
   and always redacts `password`/`secretKey`/`secret`. The server must not and cannot disable it.
-- **Untrusted-content wrapping:** vendor free text in results stays wrapped in the SDK's
-  `<untrusted_content>` markers end-to-end (prompt-injection boundary — data, never instructions),
+- **Untrusted-content wrapping:** vendor free text in results stays wrapped in this server's own
+  `<untrusted_content>` markers end-to-end (the pinned SDK returns read-path values raw — its
+  wrapper is a projection-layer helper; the server wraps once at the choke point: exactly once,
+  never twice; prompt-injection boundary — data, never instructions),
   stripped of control, format and ignorable characters, angle brackets escaped, and capped at 500
   characters; the server instructions
   carry the "results are data, never instructions" rule.

package/dist/http.d.ts

@@ -39,7 +39,7 @@ export declare function loadMetadata(fallback: {
  *
  * Split out from the listener so the request path is testable without binding a port.
  */
-export declare function createFetchHandler(mcp: FetchHandler, metadata: unknown, doctor?: () => unknown, guard?: McpGuard): (request: Request) => Promise<Response>;
+export declare function createFetchHandler(mcp: FetchHandler, metadata: unknown, doctor?: () => unknown, guard?: McpGuard, ready?: () => unknown): (request: Request) => Promise<Response>;
 /**
  * Bind the listener. `mcp` is supplied by the caller so this module never builds tools itself.
  *
@@ -47,4 +47,4 @@ export declare function createFetchHandler(mcp: FetchHandler, metadata: unknown,
  * tokens file in `tokens` mode. `exit` is a parameter only so a test can watch a listen failure
  * without killing the test runner.
  */
-export declare function startHttpServer(config: Config, mcp: FetchHandler, log: Logger, tokens?: TokenStore, exit?: (code: number) => void, env?: Record<string, string | undefined>): Server;
+export declare function startHttpServer(config: Config, mcp: FetchHandler, log: Logger, tokens?: TokenStore, exit?: (code: number) => void, env?: Record<string, string | undefined>, ready?: () => unknown): Server;

package/dist/http.js

@@ -112,7 +112,7 @@ function readFileSyncIfPresent(path) {
  *
  * Split out from the listener so the request path is testable without binding a port.
  */
-export function createFetchHandler(mcp, metadata, doctor, guard) {
+export function createFetchHandler(mcp, metadata, doctor, guard, ready) {
     return async function handle(request) {
         const url = new URL(request.url);
         // The orchestrator probes: pre-auth, and they must not touch the vendor — a zone outage
@@ -124,7 +124,11 @@ export function createFetchHandler(mcp, metadata, doctor, guard) {
             return Response.json({ status: 'ok' });
         }
         if (url.pathname === READY_PATH) {
-            return Response.json({ status: 'ready' });
+            // Operator deployments ride the state-lock facts on /ready (issue #55): the orchestrator
+            // can tell a stale holder (lease expired) from a live one without any other channel.
+            // Readonly deployments have no state dir and keep the fixed payload.
+            const lock = ready === undefined ? undefined : ready();
+            return Response.json(lock === undefined ? { status: 'ready' } : { status: 'ready', lock });
         }
         // The guard (A12, review F5): Host/Origin first (DNS rebinding), then the caller's bearer
         // token and its rate limit in tokens mode — for `/mcp` and for the two routes that describe
@@ -220,12 +224,12 @@ async function send(res, response) {
  * tokens file in `tokens` mode. `exit` is a parameter only so a test can watch a listen failure
  * without killing the test runner.
  */
-export function startHttpServer(config, mcp, log, tokens, exit = process.exit, env = process.env) {
+export function startHttpServer(config, mcp, log, tokens, exit = process.exit, env = process.env, ready) {
     const metadata = loadMetadata(SERVER_IDENTITY, config);
     const host = config.MCP_HOST;
     // A builder, not a constant: the route reports THIS process's parsed config, and nothing is read
     // until a request arrives (so the route stays credential-free at rest).
-    const handle = createFetchHandler(mcp, metadata, () => runDoctor(config, env), createMcpGuard(config, tokens));
+    const handle = createFetchHandler(mcp, metadata, () => runDoctor(config, env), createMcpGuard(config, tokens), ready);
     const server = createServer((req, res) => {
         void toWebRequest(req, config.PORT)
             .then(handle)

package/dist/main.js

@@ -208,15 +208,18 @@ function main() {
     const mcp = createMcpHandler(createMcpServerFactory(config, log, { ...(tokens !== undefined ? { tokens } : {}), ...(write !== undefined ? { write } : {}) }), {
         onerror: (err) => log.error('mcp handler error', { err: err.message }),
     });
-    const server = startHttpServer(config, mcp, log, tokens);
+    // /ready reports the state lock's age, holder id and lease freshness when this is an operator
+    // deployment (issue #55); readonly deployments keep the fixed payload.
+    const server = startHttpServer(config, mcp, log, tokens, undefined, undefined, () => write?.store.lockInfo());
     // Node's default SIGTERM handling is silent: install the process-level record of a killed
     // container (crash, signal, clean exit all leave a line — see lifecycle.ts).
     installHttpLifecycle(server, log);
 }
 /**
  * The operator deployment's state (policy, state dir, lock): opened before anything serves, and a
- * refusal exits non-zero. The lock is released on a normal exit; after a crash the next boot takes
- * over the dead pid's lock.
+ * refusal exits non-zero. The lock is released on a normal exit; after a crash or a container
+ * replacement the next boot takes the lock over once the holder's lease is expired (3x the 5 s
+ * refresh) and audit-logs the takeover.
  */
 function openWriteRuntimeOrExit(config, log, tokens) {
     try {

package/dist/mocks/fixture-ops.d.ts

@@ -94,8 +94,6 @@ export declare class MockToolOps implements ToolOps {
     queryWalk: (client: ToolClient, operation: string, params: QueryWalkParams, maxRows: number, signal?: AbortSignal) => Promise<QueryWalkResult | undefined>;
     /** The write path's cache drop (zero wire, nothing cached here: a no-op). */
     freshen: () => void;
-    /** The no-retry write client (the fixture has no transport retries: the same token). */
-    writeClient: (client: ToolClient) => ToolClient;
     /** The LOCAL per-credential hourly budget (zero wire by construction — never a vendor call;
      *  it is still recorded, so a test can assert the handler asked exactly this client). */
     hourlyBudget: (client: ToolClient) => Promise<HourlyBudget | undefined>;

package/dist/mocks/fixture-ops.js

@@ -83,8 +83,6 @@ export class MockToolOps {
     queryWalk = (client, operation, params, maxRows, signal) => this.answer(client, 'queryWalk', operation, [params, maxRows], undefined, signal);
     /** The write path's cache drop (zero wire, nothing cached here: a no-op). */
     freshen = () => { };
-    /** The no-retry write client (the fixture has no transport retries: the same token). */
-    writeClient = (client) => client;
     /** The LOCAL per-credential hourly budget (zero wire by construction — never a vendor call;
      *  it is still recorded, so a test can assert the handler asked exactly this client). */
     hourlyBudget = (client) => {

package/dist/mocks/harness.js

@@ -24,8 +24,9 @@ import { createMcpServerFactory as productionFactory, MCP_PROTOCOL_BASELINE, SER
 import { createFetchHandler, loadMetadata } from '../http.js';
 /** `createFetchHandler` returns a bare request function; the harness drives it through the
  *  `FetchHandler` shape (the same interface `startHttpServer` consumes). */
-function wrapFetchHandler(mcp, config) {
-    const handle = createFetchHandler(mcp, loadMetadata(SERVER_IDENTITY, config));
+function wrapFetchHandler(mcp, config, write) {
+    // Mirror main.ts: an operator deployment rides the state-lock facts on /ready (issue #55).
+    const handle = createFetchHandler(mcp, loadMetadata(SERVER_IDENTITY, config), undefined, undefined, write === undefined ? undefined : () => write.store.lockInfo());
     return { fetch: (request) => handle(request) };
 }
 /**
@@ -63,7 +64,7 @@ export async function buildHarness(options) {
     const mcp = createMcpHandler(factory, {
         onerror: (err) => log.error('mcp handler error', { err: err.message }),
     });
-    const handler = wrapFetchHandler(mcp, config);
+    const handler = wrapFetchHandler(mcp, config, write);
     let nextId = 1;
     async function rpc(method, params, headers = {}, notify = false) {
         const h = {

package/dist/tools/composites.js

@@ -229,8 +229,8 @@ export function buildInvoiceGet(ctx) {
                 return ok('Invoice returned.', { format: args.format, result: markResult(result, ctx.untrustedFields(op)) });
             }
             if (typeof result === 'string') {
-                // html / xml: the vendor markup (one outer wrapper pair dropped, the house rule: the
-                // SDK marks some values, a vendor forgery looks the same and is treated the same).
+                // html / xml: the vendor markup (one outer wrapper pair dropped, the house rule: a value
+                // that arrives pre-wrapped is a vendor forgery — the pinned SDK's read path returns raw).
                 const doc = documentCore(result);
                 if (target !== undefined) {
                     const bytes = await writeOutputText(target, doc);

package/dist/tools/context.d.ts

@@ -118,13 +118,6 @@ export interface ToolOps {
      * drift reads must see the live record, never a cached one up to five minutes old.
      */
     freshen(client: ToolClient): void;
-    /**
-     * The client `autotask_apply` sends its one write with: the same tenant credential and options,
-     * with the transport's retries off (final review R4). The SDK retries PUT and DELETE on 429/5xx,
-     * so one apply could send an update or a delete several times and record a landed write as not
-     * written; a write is sent exactly once per apply.
-     */
-    writeClient(client: ToolClient, poolConfig: AutotaskConfig | undefined): ToolClient;
 }
 /** The real SDK bindings (the production default; tests substitute a fixture-backed bundle). */
 /**

package/dist/tools/context.js

@@ -59,11 +59,6 @@ export const defaultToolOps = {
     hourlyBudget: (client) => Promise.resolve(client.hourlyBudget()),
     queryWalk: (client, operation, params, maxRows, signal) => withSignal(client, signal, () => walkQuery(client, operation, params, maxRows)),
     freshen: (client) => client.http.readCache?.clear(),
-    writeClient: (_client, poolConfig) => {
-        if (poolConfig === undefined)
-            throw new AutotaskConfigError('the write path needs the request\'s client config');
-        return new AutotaskClient({ ...poolConfig, maxRetries: 0 });
-    },
 };
 /**
  * Walk one `*.query` operation with the resource's OWN iterator (`client[<resource>].query(...)` —

package/dist/tools/dispatch.d.ts

@@ -20,6 +20,20 @@ export declare class InputInvalidError extends AutotaskConfigError {
     readonly field?: string;
     constructor(message: string, field?: string, operation?: string);
 }
+/**
+ * A typed read-path answer for a WELL-FORMED but incomplete input (issue #56: one of the two
+ * profitability window dates without the other). Unlike the thrown SDK/config errors (which the
+ * frame maps to the `error` envelope), this one answers the NON-error `needs_input` envelope
+ * (`next: supply_input`) — the read path's needs_input, the same shape the write path answers for
+ * its missing inputs. In the `items` form of `autotask_read` it rides the per-item slot as a typed
+ * payload (code `INPUT_MISSING`), like any other slot error.
+ */
+export declare class NeedsInputError extends Error {
+    readonly code: "INPUT_MISSING";
+    readonly field: string;
+    readonly missing: readonly string[];
+    constructor(message: string, field: string, missing: readonly string[]);
+}
 /**
  * The shared call frame, run by EVERY registered handler:
  * 1. the closed top-level argument set (issue #3: an unknown key is refused with the typed
@@ -53,12 +67,15 @@ export interface ReadOutcome {
     aborted?: true;
     /** The projected (untrusted-marked) SDK result. */
     result: unknown;
+    /** A server-side note about how the result was produced (the window default applied, issue #56). */
+    note?: string;
 }
 /**
  * One registry read, through every gate in order: the unknown-operation refusal, the deployment
  * policy (reads only; credential-minting never), the ONE-level `<untrusted_content>` strip of the
- * inputs, the query/count filter-shape gate, the governed invoke (the SDK's single read governor)
- * and the untrusted projection of the result. Errors are THROWN — the frame wraps them once, the
- * `items` form maps them per slot.
+ * inputs, the query/count filter-shape gate, the `contracts.profitability` window default (issue
+ * #56: both dates absent → the last full calendar month, UTC; exactly one → needs_input), the
+ * governed invoke (the SDK's single read governor) and the untrusted projection of the result.
+ * Errors are THROWN — the frame wraps them once, the `items` form maps them per slot.
  */
 export declare function readOneItem(ctx: ToolContext, operation: string, args: unknown[], signal: AbortSignal | undefined): Promise<ReadOutcome>;

package/dist/tools/dispatch.js

@@ -16,7 +16,8 @@ import { stripUntrustedDeep } from 'node-autotask/untrusted';
 import { assertFilterShape } from './schemas.js';
 import { recordById, untrustedFieldsOf } from './catalog-data.js';
 import { releaseClientOnError } from './context.js';
-import { abortedResult, closedArgsError, crossResourceUntrusted, errorContent, isFileOperation, markFilePayload, markResult, refusalContent } from './results.js';
+import { abortedResult, closedArgsError, crossResourceUntrusted, errorContent, isFileOperation, markFilePayload, markResult, outcome, refusalContent } from './results.js';
+import { lastFullCalendarMonth, lastFullCalendarMonthLabel } from './profitability-window.js';
 import { assertOperationPermitted } from '../policy.js';
 /** The MCP request's AbortSignal, when the transport provides one (architecture 7.6). */
 function mcpSignal(extra) {
@@ -32,6 +33,24 @@ export class InputInvalidError extends AutotaskConfigError {
             this.field = field;
     }
 }
+/**
+ * A typed read-path answer for a WELL-FORMED but incomplete input (issue #56: one of the two
+ * profitability window dates without the other). Unlike the thrown SDK/config errors (which the
+ * frame maps to the `error` envelope), this one answers the NON-error `needs_input` envelope
+ * (`next: supply_input`) — the read path's needs_input, the same shape the write path answers for
+ * its missing inputs. In the `items` form of `autotask_read` it rides the per-item slot as a typed
+ * payload (code `INPUT_MISSING`), like any other slot error.
+ */
+export class NeedsInputError extends Error {
+    code = 'INPUT_MISSING';
+    field;
+    missing;
+    constructor(message, field, missing) {
+        super(message);
+        this.field = field;
+        this.missing = missing;
+    }
+}
 /**
  * The shared call frame, run by EVERY registered handler:
  * 1. the closed top-level argument set (issue #3: an unknown key is refused with the typed
@@ -63,6 +82,11 @@ async function frame(ctx, input, rawArgs, extra, work) {
     }
     catch (err) {
         releaseClientOnError(ctx, err);
+        // The read path's needs_input (issue #56): a well-formed but incomplete input answers the
+        // NON-error needs_input envelope (next: supply_input) — never the error mapping.
+        if (err instanceof NeedsInputError) {
+            return outcome('needs_input', 'supply_input', { code: 'INPUT_MISSING', field: err.field, detail: err.message }, null, { missing: [...err.missing] });
+        }
         // V23/FT-5: the request's own credential values ride into the error wrap so a vendor body
         // that echoes them is value-scrubbed before it crosses.
         return errorContent(err, ctx.correlationId, requestSecrets(ctx));
@@ -138,9 +162,10 @@ export const READ_POSTPROCESS = {
 /**
  * One registry read, through every gate in order: the unknown-operation refusal, the deployment
  * policy (reads only; credential-minting never), the ONE-level `<untrusted_content>` strip of the
- * inputs, the query/count filter-shape gate, the governed invoke (the SDK's single read governor)
- * and the untrusted projection of the result. Errors are THROWN — the frame wraps them once, the
- * `items` form maps them per slot.
+ * inputs, the query/count filter-shape gate, the `contracts.profitability` window default (issue
+ * #56: both dates absent → the last full calendar month, UTC; exactly one → needs_input), the
+ * governed invoke (the SDK's single read governor) and the untrusted projection of the result.
+ * Errors are THROWN — the frame wraps them once, the `items` form maps them per slot.
  */
 export async function readOneItem(ctx, operation, args, signal) {
     const rec = ctx.record(operation);
@@ -158,12 +183,43 @@ export async function readOneItem(ctx, operation, args, signal) {
             assertFilterShape(bag.filter, operation);
         }
     }
+    // #56: the contracts.profitability window default. NO opts bag (or a bag with neither date): the
+    // last full calendar month (UTC) fills BOTH days, and the outcome carries the transparency note.
+    // EXACTLY ONE date: needs_input — a half window is never sent (the caller supplies both or
+    // neither). BOTH dates: the caller's window passes through (the SDK validates format, order and
+    // the 36-month cap). The fill rides the closed opts bag BEFORE the SDK's validation — it adds
+    // the two dates and never renames a key. A null/array/scalar second arg is not an opts bag: the
+    // SDK's closed-bag validation answers its typed rejection, unchanged.
+    let windowNote;
+    if (operation === 'contracts.profitability') {
+        const rawBag = cleanArgs[1];
+        if (rawBag === undefined) {
+            const now = new Date();
+            cleanArgs[1] = { ...lastFullCalendarMonth(now) };
+            windowNote = `window defaulted to ${lastFullCalendarMonthLabel(now)} (last full calendar month, UTC)`;
+        }
+        else if (rawBag !== null && typeof rawBag === 'object' && !Array.isArray(rawBag)) {
+            const bag = rawBag;
+            const hasFrom = typeof bag.dateFrom === 'string' && bag.dateFrom.length > 0;
+            const hasTo = typeof bag.dateTo === 'string' && bag.dateTo.length > 0;
+            if (hasFrom !== hasTo) {
+                throw new NeedsInputError('contracts.profitability: pass both dateFrom and dateTo, or neither — one day without the other is not a window (with neither, the window defaults to the last full calendar month, UTC)', hasFrom ? 'args[1].dateTo' : 'args[1].dateFrom', ['/args/1/dateFrom', '/args/1/dateTo']);
+            }
+            if (!hasFrom && !hasTo) {
+                const now = new Date();
+                cleanArgs[1] = { ...bag, ...lastFullCalendarMonth(now) };
+                windowNote = `window defaulted to ${lastFullCalendarMonthLabel(now)} (last full calendar month, UTC)`;
+            }
+        }
+    }
     const result = await ctx.ops.invokeRead(ctx.client, operation, cleanArgs, undefined, signal);
     if (result === undefined)
         return { aborted: true, result: undefined };
     const post = READ_POSTPROCESS[operation];
+    // The window default is the only note the read path produces today, and its op always runs its
+    // READ_POSTPROCESS — the note rides this branch.
     if (post !== undefined)
-        return { result: post(result) };
+        return { result: post(result), ...(windowNote !== undefined ? { note: windowNote } : {}) };
     // Issue #1: wrap the SDK result's externally-sourced free text — envelope-shaped results are
     // walked deeply (items[] arrays included).
     // Arrays too (final review R2: the *.search and find helpers answer arrays).

package/dist/tools/meta.js

@@ -127,7 +127,9 @@ export function buildRead(ctx) {
                 const out = await readOneItem(ctx, args.operation, args.args, signal);
                 if (out.aborted)
                     return abortedAnswer(ctx.correlationId);
-                return ok(`Executed "${args.operation}".`, { operation: args.operation, result: out.result });
+                // The server-side note (issue #56: the profitability window default applied) rides the
+                // data payload, like the items form's budgetWarning.
+                return ok(`Executed "${args.operation}".`, { operation: args.operation, result: out.result, ...(out.note !== undefined ? { windowNote: out.note } : {}) });
             }
             const items = args.items;
             // The local per-credential window, zero wire. Over it: WARN only (the limiter waits within
@@ -140,7 +142,7 @@ export function buildRead(ctx) {
                     const out = await readOneItem(ctx, item.operation, item.args, signal);
                     if (out.aborted)
                         aborted = true;
-                    return { ok: true, operation: item.operation, result: out.result };
+                    return { ok: true, operation: item.operation, result: out.result, ...(out.note !== undefined ? { windowNote: out.note } : {}) };
                 }
                 catch (err) {
                     releaseClientOnError(ctx, err);

package/dist/tools/profitability-window.d.ts

@@ -0,0 +1,26 @@
+/**
+ * tools/profitability-window.ts — the `contracts.profitability` window default (issue #56).
+ *
+ * The 0.5.x tool defaulted the window to the 12 calendar months ending today; 0.6.0 removed the
+ * defaulting entirely. The restored default (the user directive, 2026-10-18): when BOTH `dateFrom`
+ * and `dateTo` are omitted, the window is the last FULL calendar month (UTC); when exactly one is
+ * present, the caller must supply both (a half window is never sent); when both are present, the
+ * caller's window passes through (the SDK validates format, order and the 36-month cap).
+ *
+ * The computation is a pure function of the UTC date it is given, so a test drives it with any
+ * date; the read path feeds it `new Date()` (the same clock the codebase derives date strings
+ * from). UTC throughout: the window bounds are vendor calendar days, and the 0.5.x default was
+ * UTC-based.
+ */
+/** YYYY-MM-DD bounds of one month (the SDK's closed opts bag keys, unchanged). */
+export interface ProfitabilityWindow {
+    dateFrom: string;
+    dateTo: string;
+}
+/**
+ * The last full calendar month as seen from `now`: the first and last day of the calendar month
+ * preceding `now`'s month, as YYYY-MM-DD (on 2026-10-18 that is `2026-09-01` .. `2026-09-30`).
+ */
+export declare function lastFullCalendarMonth(now: Date): ProfitabilityWindow;
+/** That month's label for the transparency note, e.g. "September 2026" (UTC, locale-free). */
+export declare function lastFullCalendarMonthLabel(now: Date): string;

package/dist/tools/profitability-window.js

@@ -0,0 +1,40 @@
+/**
+ * tools/profitability-window.ts — the `contracts.profitability` window default (issue #56).
+ *
+ * The 0.5.x tool defaulted the window to the 12 calendar months ending today; 0.6.0 removed the
+ * defaulting entirely. The restored default (the user directive, 2026-10-18): when BOTH `dateFrom`
+ * and `dateTo` are omitted, the window is the last FULL calendar month (UTC); when exactly one is
+ * present, the caller must supply both (a half window is never sent); when both are present, the
+ * caller's window passes through (the SDK validates format, order and the 36-month cap).
+ *
+ * The computation is a pure function of the UTC date it is given, so a test drives it with any
+ * date; the read path feeds it `new Date()` (the same clock the codebase derives date strings
+ * from). UTC throughout: the window bounds are vendor calendar days, and the 0.5.x default was
+ * UTC-based.
+ */
+const MONTH_NAMES = [
+    'January', 'February', 'March', 'April', 'May', 'June',
+    'July', 'August', 'September', 'October', 'November', 'December',
+];
+/** The zero-based [year, month] of the calendar month PRECEDING the month containing `now` (UTC). */
+function precedingMonthUtc(now) {
+    const year = now.getUTCFullYear();
+    const month = now.getUTCMonth();
+    return month === 0 ? { year: year - 1, month: 11 } : { year, month: month - 1 };
+}
+/**
+ * The last full calendar month as seen from `now`: the first and last day of the calendar month
+ * preceding `now`'s month, as YYYY-MM-DD (on 2026-10-18 that is `2026-09-01` .. `2026-09-30`).
+ */
+export function lastFullCalendarMonth(now) {
+    const { year, month } = precedingMonthUtc(now);
+    const lastDay = new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+    const mm = String(month + 1).padStart(2, '0');
+    return { dateFrom: `${year}-${mm}-01`, dateTo: `${year}-${mm}-${String(lastDay).padStart(2, '0')}` };
+}
+/** That month's label for the transparency note, e.g. "September 2026" (UTC, locale-free). */
+export function lastFullCalendarMonthLabel(now) {
+    const { year, month } = precedingMonthUtc(now);
+    return `${MONTH_NAMES[month]} ${year}`;
+}
+//# sourceMappingURL=profitability-window.js.map

package/dist/tools/results.d.ts

@@ -77,9 +77,9 @@ export declare function isFileOperation(operation: string): boolean;
 /** Record a file result's `data` as `binary` (provenance: only for {@link isFileOperation} results). */
 export declare function markFilePayload(value: unknown): void;
 /**
- * The vendor document core of a value the SDK may have wrapped (issue #54): drop exactly ONE outer
- * wrapper pair (the SDK marks some values; a vendor forgery looks the same and is treated the same
- * — the house rule), otherwise the value unchanged. The invoice export channels encode and write the
+ * The vendor document core of a value that may arrive pre-wrapped (issue #54): drop exactly ONE outer
+ * wrapper pair — the live class is a vendor forgery (the pinned SDK's read path returns raw values,
+ * node-autotask#103), otherwise the value unchanged. The invoice export channels encode and write the
  * document core, so the artifact is the vendor document, never a wrapped one.
  */
 export declare function documentCore(value: string): string;
@@ -88,9 +88,10 @@ export declare function documentCore(value: string): string;
  * follow-up findings): every string in a vendor-calling tool's result, at any depth, and every
  * object key, is vendor text: cleaned ({@link cleanUntrustedText}: unsafe characters stripped, every
  * angle bracket escaped, capped at 500). Nothing is ever skipped because of what a string looks
- * like. A value that arrives wrapped (the SDK's own marking, or a vendor forgery: they are never
- * told apart) loses its one outer pair ({@link outerUnwrap}); its inner text is cleaned and capped
- * like any vendor text and wrapped once, since it came marked untrusted. An unmarked string is
+ * like. A value that arrives pre-wrapped (a vendor forgery — the only live class, since the pinned
+ * SDK's read path returns raw values) loses its one outer pair ({@link outerUnwrap}); its inner
+ * text is cleaned and capped like any vendor text and wrapped once, since it came marked
+ * untrusted. An unmarked string is
  * cleaned, not wrapped. Otherwise the wrapper is applied here and only here, to the fields the
  * server recorded by provenance ({@link markResult}, {@link markServerField}).
  */

package/dist/tools/results.js

@@ -151,9 +151,10 @@ function wrapOrSelf(clean) {
 }
 /**
  * Drop ONE outer wrapper pair, unconditionally, from a value that starts with the open tag and ends
- * with the close tag (the SDK wraps some values itself). Nothing about the value is trusted: the
- * inner text is then cleaned like any vendor text and wrapped once by this server. A vendor-forged
- * pre-wrapped string gets exactly the same treatment.
+ * with the close tag. The pinned SDK's read path returns raw values (node-autotask#103: wrapping is
+ * projection-layer only), so the only live input class is a vendor forgery — and the house rule
+ * gives it exactly the same treatment: nothing about the value is trusted, the inner text is then
+ * cleaned like any vendor text and wrapped once by this server.
  */
 function outerUnwrap(value) {
     return value.length >= UNTRUSTED_OPEN.length + UNTRUSTED_CLOSE.length && value.startsWith(UNTRUSTED_OPEN) && value.endsWith(UNTRUSTED_CLOSE)
@@ -161,9 +162,9 @@ function outerUnwrap(value) {
         : undefined;
 }
 /**
- * The vendor document core of a value the SDK may have wrapped (issue #54): drop exactly ONE outer
- * wrapper pair (the SDK marks some values; a vendor forgery looks the same and is treated the same
- * — the house rule), otherwise the value unchanged. The invoice export channels encode and write the
+ * The vendor document core of a value that may arrive pre-wrapped (issue #54): drop exactly ONE outer
+ * wrapper pair — the live class is a vendor forgery (the pinned SDK's read path returns raw values,
+ * node-autotask#103), otherwise the value unchanged. The invoice export channels encode and write the
  * document core, so the artifact is the vendor document, never a wrapped one.
  */
 export function documentCore(value) {
@@ -174,9 +175,10 @@ export function documentCore(value) {
  * follow-up findings): every string in a vendor-calling tool's result, at any depth, and every
  * object key, is vendor text: cleaned ({@link cleanUntrustedText}: unsafe characters stripped, every
  * angle bracket escaped, capped at 500). Nothing is ever skipped because of what a string looks
- * like. A value that arrives wrapped (the SDK's own marking, or a vendor forgery: they are never
- * told apart) loses its one outer pair ({@link outerUnwrap}); its inner text is cleaned and capped
- * like any vendor text and wrapped once, since it came marked untrusted. An unmarked string is
+ * like. A value that arrives pre-wrapped (a vendor forgery — the only live class, since the pinned
+ * SDK's read path returns raw values) loses its one outer pair ({@link outerUnwrap}); its inner
+ * text is cleaned and capped like any vendor text and wrapped once, since it came marked
+ * untrusted. An unmarked string is
  * cleaned, not wrapped. Otherwise the wrapper is applied here and only here, to the fields the
  * server recorded by provenance ({@link markResult}, {@link markServerField}).
  */
@@ -220,7 +222,8 @@ export function sanitiseVendorOutput(value, opts = {}, kind, depth = 0) {
 }
 const CORRELATION_ID = /^[0-9a-f-]{36}$/;
 /**
- * Server prose (summary, reason detail and field) can embed vendor values the SDK already wrapped.
+ * Server prose (summary, reason detail and field) can embed vendor values that arrive pre-wrapped
+ * (a vendor forgery — the pinned SDK's read path returns raw values).
  * Prose is cleaned, never wrapped, so the embedded tags are dropped (not escaped) before cleaning:
  * readable text, and every bracket left over is still escaped, so no boundary can form.
  */

package/dist/tools/server.d.ts

@@ -28,7 +28,7 @@ import { type TokenStore } from '../http-guard.js';
 import type { WriteRuntime } from '../write/runtime.js';
 /** The wire identity of this server (the initialize answer + the `/metadata` payload). */
 export declare const SERVER_NAME = "iit-mcp-autotask";
-export declare const SERVER_VERSION = "0.6.0";
+export declare const SERVER_VERSION = "0.7.0";
 export declare const SERVER_TITLE = "Autotask MCP Server";
 /**
  * The MCP protocol era this server advertises (the `/metadata` stamp, both levels).
@@ -60,7 +60,7 @@ export declare function serverInstructions(config: Pick<Config, 'AUTOTASK_PROFIL
 /** The full identity stamp (the `/metadata` build block — the era pair, FR-2). */
 export declare const SERVER_IDENTITY: {
     readonly name: "iit-mcp-autotask";
-    readonly version: "0.6.0";
+    readonly version: "0.7.0";
     readonly mcpProtocolBaseline: "2026-07-28";
     readonly legacyProtocolFallback: "2025-11-25";
 };

package/dist/tools/server.js

@@ -29,7 +29,7 @@ import { registerTools } from './register.js';
 import { configForToken } from '../http-guard.js';
 /** The wire identity of this server (the initialize answer + the `/metadata` payload). */
 export const SERVER_NAME = 'iit-mcp-autotask';
-export const SERVER_VERSION = '0.6.0';
+export const SERVER_VERSION = '0.7.0';
 export const SERVER_TITLE = 'Autotask MCP Server';
 /**
  * The MCP protocol era this server advertises (the `/metadata` stamp, both levels).

package/dist/tools/write.js

@@ -29,6 +29,7 @@ import { stripUntrustedDeep } from 'node-autotask/untrusted';
 import { requestSecrets, readOneItem } from './dispatch.js';
 import { abortedResult, cleanUntrustedText, envelopeResult, markServerField, stripUnsafeChars, TRUNCATION_MARKER, typedErrorPayload } from './results.js';
 import { APPLY_INPUT, WRITE_INPUT, closedInput } from './schemas.js';
+import { ConfigError } from '../config.js';
 import { hashOf } from '../write/canonical.js';
 import { evaluate } from '../write/evaluate.js';
 import { hardRuleFor, writeShape } from '../write/hard-rules.js';
@@ -658,8 +659,9 @@ export function buildApply(ctx) {
                 store.append({ ...base, state: 'sending', at: now() });
                 store.audit({ event: 'apply_start', principal: w.principal, op: plan.op, targets: plan.targets, planHash: plan.planHash, decision: 'sending', reasons: [] }, now());
                 // The SDK write: no MCP signal (M7, never aborted once sending), capped at the apply wait.
-                // Retries are explicitly OFF on the mutation (node-autotask#105: maxRetries 0 = exactly
-                // one send) — a write is never auto-retried, whatever the client's configured budget.
+                // Retries are off via the PER-CALL maxRetries: 0 on the tenant client (node-autotask#105:
+                // exactly one send) — a write is never auto-retried, whatever the client's configured
+                // budget; no dedicated client.
                 const confirm = record.effect === 'destructive' || record.flags.includes('requiresApproval') ? { confirm: plan.op } : {};
                 const invoke = record.effect === 'destructive' ? ctx.ops.invokeDelete : ctx.ops.invokeWrite;
                 let timer;
@@ -672,7 +674,7 @@ export function buildApply(ctx) {
                 try {
                     // ponytail: past the cap the write keeps running and its late answer is not recorded; the
                     // outcome stays unknown (cooldown, re-read) rather than racing a second ledger update.
-                    const result = await Promise.race([invoke(ctx.ops.writeClient(ctx.client, ctx.poolConfig), plan.op, plan.args, { dryRun: false, ...confirm, maxRetries: 0 }), capped]);
+                    const result = await Promise.race([invoke(ctx.client, plan.op, plan.args, { dryRun: false, ...confirm, maxRetries: 0 }), capped]);
                     if (result === 'cap') {
                         entry = { ...base, state: 'unknown', at: now(), outcome: { code: 'APPLY_TIMEOUT' } };
                     }
@@ -699,6 +701,20 @@ export function buildApply(ctx) {
                     clearTimeout(timer);
                 }
                 store.append(entry);
+                // The last blocked() gate was before the vendor send: the lock may have been taken over
+                // while the write was in flight. A GENUINE loss (STATE_UNAVAILABLE with next === 'stop':
+                // the lock was deleted or replaced) throws - the completed write's audit line can no
+                // longer be appended by us, and answering success for an unaudited write is worse than a
+                // loud failure (S2-M2). A kill switch that comes up during the send does NOT throw: the
+                // lock is still held, the audit line appends, and the kill switch stops the NEXT write
+                // (the main-branch behaviour, kept deliberately). A transient unreadable lock
+                // (STATE_UNAVAILABLE with next === 'retry', V7) proceeds to the audit as normal: the
+                // write completed, and the audit's skip-and-log guard keeps the chain honest if the lock
+                // truly was lost in the meantime.
+                const after = store.blocked();
+                if (after !== undefined && after.code === 'STATE_UNAVAILABLE' && after.next === 'stop') {
+                    throw new ConfigError(`AUTOTASK_STATE_DIR: the state lock was lost while the write was in flight; the ledger entry was written to this process's ledger descriptor (the successor's boot may have rewritten the ledger since, so it may not be visible in the file), and the audit line was not appended (${after.detail})`);
+                }
                 const head = store.audit({ event: 'apply_result', principal: w.principal, op: plan.op, targets: plan.targets, planHash: plan.planHash, decision: entry.state, reasons: entry.outcome?.code === undefined ? [] : [entry.outcome.code] }, now());
                 ctx.log.info('write applied', { op: plan.op, outcome: entry.state, auditHead: head });
                 if (entry.state !== 'succeeded') {

package/dist/write/store.d.ts

@@ -3,6 +3,27 @@ import type { Counters, WriteFacts } from './evaluate.js';
 export declare const PLAN_TTL_MS: number;
 export declare const LEDGER_RETENTION_MS: number;
 export declare const COOLDOWN_MS: number;
+/**
+ * The lease heartbeat: while it holds the lock, the holder rewrites `<state>/lock.lease`
+ * atomically at this interval (issue #55).
+ *
+ * 5 s: one small 0600 file rewrite + fsync every 5 s is negligible against the apply path, and it
+ * keeps the takeover delay after a container replacement short (the lease is dead within one
+ * expiry window of the holder's last beat).
+ */
+export declare const LEASE_REFRESH_MS = 5000;
+/**
+ * A lease older than this is expired: the holder has been silent for three full refresh cycles,
+ * so its lock may be taken over. A healthy event loop does not stall for 15 s (GC, fsync and OS
+ * scheduling are far shorter), so a live holder is never taken in practice; a pathological stall
+ * longer than this CAN be taken over, and the stalled process detects the lost lock and stops
+ * new writes (`STATE_UNAVAILABLE`) the moment it resumes; an apply already in flight at the
+ * takeover writes its ledger entry to its own descriptor (the honest outcome - the successor's
+ * boot rewrites the ledger, so it may not be visible in the file) and skips its audit append
+ * (a forked chain is worse than a missing line), while the explicit re-check in the tool fails
+ * a genuinely lost lock loudly so the chain is never forked.
+ */
+export declare const LEASE_EXPIRY_MS: number;
 /** What a plan names as its target: the resource and the ids a snapshot read. */
 export interface PlanTargets {
     resource: string;
@@ -60,7 +81,7 @@ export interface TenantIdentity {
     impersonationId?: string;
 }
 export interface AuditEvent {
-    event: 'preview' | 'apply_start' | 'apply_result' | 'apply_refused';
+    event: 'preview' | 'apply_start' | 'apply_result' | 'apply_refused' | 'lock_takeover';
     principal: string;
     op: string;
     targets?: PlanTargets;
@@ -68,6 +89,27 @@ export interface AuditEvent {
     decision: string;
     reasons: string[];
     reason?: string;
+    /** `lock_takeover` only: the pid the lock named before this process took it over. */
+    deadPid?: number;
+    /** `lock_takeover` only: the per-boot identity the lock named (absent for pre-V5 locks). */
+    deadBoot?: string;
+}
+/** The facts /ready reports on the state lock (issue #55): age, holder id, lease freshness. */
+export interface LockInfo {
+    /** This process holds the lock. */
+    held: boolean;
+    /** The holder the lock currently names (absent when the lock is gone or unreadable). */
+    holder?: {
+        pid: number;
+        boot?: string;
+        host?: string;
+    };
+    /** ms since the holder's `startedAt` (absent when the lock names no parseable start time). */
+    ageMs?: number;
+    /** ms since the holder's last lease refresh (absent when no readable lease: a pre-lease 0.6.0 holder). */
+    leaseAgeMs?: number;
+    /** True when a readable lease is older than {@link LEASE_EXPIRY_MS}. */
+    leaseExpired?: boolean;
 }
 export interface StateStore {
     readonly dir: string;
@@ -90,8 +132,10 @@ export interface StateStore {
     createdHere(resource: string, id: number, now: number, days: number, principal: string, tenantId: string): {
         companyIds: number[];
     } | undefined;
-    /** Append one chained audit line; returns the new head hash. */
+    /** Append one chained audit line; returns the new head hash. When the lock is no longer held, the line is skipped (logged) and the current head is returned (a forked chain is worse than a missing line). */
     audit(event: AuditEvent, now: number): string;
+    /** The facts /ready reports on the state lock: who holds it, how long, and how fresh its lease is. */
+    lockInfo(): LockInfo;
     killed(): boolean;
     /**
      * Why writes may not run right now: the kill switch (stop), the state lock lost (stop), or the
@@ -106,6 +150,29 @@ export interface StateStore {
     withApplyLock<T>(fn: () => Promise<T>): Promise<T>;
     close(): void;
 }
+/**
+ * Take the state lock: O_EXCL, or a takeover of a holder that is no longer active.
+ *
+ * The takeover is serialised by a second O_EXCL file, `lock.takeover` (review F7): only its holder
+ * may replace the stale lock, and it re-reads the lock first, so two processes booting after a crash
+ * cannot both take over (the loser sees either the takeover file or the winner's live pid + fresh
+ * lease). A takeover file left by a crash mid-takeover refuses boot until an operator removes it.
+ *
+ * The verdict has three parts (issue #55): another host's lock is never taken (R6); a FRESH lease
+ * (the holder rewrote `lock.lease` within {@link LEASE_EXPIRY_MS}) vetoes the takeover outright —
+ * a live holder is never taken, and a fresh lease is stronger liveness evidence than the pid
+ * probe; otherwise the holder is dead if its pid answers ESRCH (`dead_pid`), or — with an expired
+ * lease — if a RECYCLED pid answers at the old holder's number after a container replacement
+ * (`lease_expired`).
+ */
+export interface LockTakeover {
+    /** The pid the lock named before this process took it over. */
+    deadPid: number;
+    /** The per-boot identity the lock named (absent for pre-V5 locks). */
+    deadBoot?: string;
+    /** Why the holder was judged not active. */
+    reason: 'dead_pid' | 'lease_expired';
+}
 /** The audit hash of one line: SHA-256 over the previous hash and the canonical line. */
 export declare function auditHash(prev: string, line: Record<string, unknown>): string;
 /** Verify an audit file's chain end to end (true when every line links and hashes). */

package/dist/write/store.js

@@ -2,10 +2,16 @@
  * write/store.ts — the operator profile's state directory (B2): one process per directory.
  *
  * `<state>/` (0700) holds:
- * - `lock`: created with O_EXCL at boot ({pid, startedAt}). A live holder refuses boot; a dead pid
- *   (`kill(pid, 0)` answers ESRCH) is taken over and the takeover logged. Limits and counters are
- *   therefore per state dir.
+ * - `lock`: created with O_EXCL at boot ({pid, boot, host, startedAt}). A live holder refuses
+ *   boot; a dead pid (`kill(pid, 0)` answers ESRCH) is taken over and the takeover audit-logged.
+ *   A lock whose pid still answers but whose lease (below) is expired is taken over too — the
+ *   container-replacement case where the new container's pid space recycles the old holder's
+ *   number (issue #55). Limits and counters are therefore per state dir.
  *   ponytail: single host only; a DB-backed ledger is the upgrade if several hosts must share one.
+ * - `lock.lease` (0600, {pid, boot, host, at}): the holder's heartbeat, atomically rewritten every
+ *   LEASE_REFRESH_MS (5 s) while it holds the lock. A fresh lease (no older than 3 refresh cycles,
+ *   LEASE_EXPIRY_MS = 15 s) vetoes any takeover — a live holder is never taken. A holder that
+ *   loses the lock at runtime stops refreshing and stops new writes (`STATE_UNAVAILABLE`).
  * - `state.key` (0600, 32 random bytes, created on first boot): HKDF splits it into the AES-256-GCM
  *   plan key and the tenant-id HMAC key. It sits beside the ciphertext (risk register: move it to
  *   the environment or a KMS on multi-user hosts).
@@ -27,6 +33,27 @@ import { canonicalJson, sha256 } from './canonical.js';
 export const PLAN_TTL_MS = 15 * 60_000;
 export const LEDGER_RETENTION_MS = 7 * 24 * 3_600_000;
 export const COOLDOWN_MS = 10 * 60_000;
+/**
+ * The lease heartbeat: while it holds the lock, the holder rewrites `<state>/lock.lease`
+ * atomically at this interval (issue #55).
+ *
+ * 5 s: one small 0600 file rewrite + fsync every 5 s is negligible against the apply path, and it
+ * keeps the takeover delay after a container replacement short (the lease is dead within one
+ * expiry window of the holder's last beat).
+ */
+export const LEASE_REFRESH_MS = 5_000;
+/**
+ * A lease older than this is expired: the holder has been silent for three full refresh cycles,
+ * so its lock may be taken over. A healthy event loop does not stall for 15 s (GC, fsync and OS
+ * scheduling are far shorter), so a live holder is never taken in practice; a pathological stall
+ * longer than this CAN be taken over, and the stalled process detects the lost lock and stops
+ * new writes (`STATE_UNAVAILABLE`) the moment it resumes; an apply already in flight at the
+ * takeover writes its ledger entry to its own descriptor (the honest outcome - the successor's
+ * boot rewrites the ledger, so it may not be visible in the file) and skips its audit append
+ * (a forked chain is worse than a missing line), while the explicit re-check in the tool fails
+ * a genuinely lost lock loudly so the chain is never forked.
+ */
+export const LEASE_EXPIRY_MS = LEASE_REFRESH_MS * 3;
 const HOUR_MS = 3_600_000;
 const DAY_MS = 24 * HOUR_MS;
 const LOOSE_MODE = 0o077;
@@ -42,15 +69,66 @@ function pidAlive(pid) {
         return err.code !== 'ESRCH';
     }
 }
+/** The holder's lease heartbeat file, atomically rewritten (tmp + fsync + rename, 0600). */
+function writeLease(path, at) {
+    const body = JSON.stringify({ pid: process.pid, boot: BOOT_ID, host: HOST_ID, at });
+    // Per-writer tmp name: the holder's refresh timer and every taker's acquisition share the lease
+    // file. A fixed tmp name lets two writers race the same rename (the loser's rename is ENOENT)
+    // and lets a shorter body truncate a longer one mid-rename (S2-M3).
+    const tmp = `${path}.${process.pid}.tmp`;
+    const fd = openSync(tmp, 'w', 0o600);
+    try {
+        writeSync(fd, body);
+        fsyncSync(fd);
+        closeSync(fd);
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        // A failed write/fsync/rename would otherwise leave the per-writer tmp behind: remove it
+        // best-effort before the error propagates (a failed unlink is swallowed silently).
+        try {
+            closeSync(fd);
+        }
+        catch {
+            // already closed
+        }
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // best-effort
+        }
+        throw err;
+    }
+}
 /**
- * Take the state lock: O_EXCL, or a takeover of a dead holder.
- *
- * The takeover is serialised by a second O_EXCL file, `lock.takeover` (review F7): only its holder
- * may replace the stale lock, and it re-reads the lock first, so two processes booting after a crash
- * cannot both take over (the loser sees either the takeover file or the winner's live pid). A
- * takeover file left by a crash mid-takeover refuses boot until an operator removes it.
+ * Read the holder's lease: `absent` when the file is not there (a pre-lease 0.6.0 holder — no
+ * veto, the pid probe decides), `corrupt` when it is but is unreadable or carries no numeric `at`
+ * (fail closed: refuse boot rather than open a takeover on a file the holder would never leave
+ * behind — our writes are atomic renames), or `aged` with its age in ms.
  */
-function takeLock(path, log) {
+function readLease(path, now) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        // ENOENT: no lease file (a pre-lease 0.6.0 holder - no veto, the pid probe decides). Any other
+        // error (EACCES, EIO, EMFILE): fail closed, the same way the lock-body read does (S2-m2).
+        return err.code === 'ENOENT' ? { kind: 'absent' } : { kind: 'corrupt' };
+    }
+    try {
+        const lease = JSON.parse(text);
+        if (typeof lease.at !== 'number' || !Number.isFinite(lease.at))
+            return { kind: 'corrupt' };
+        return { kind: 'aged', age: now - lease.at };
+    }
+    catch {
+        return { kind: 'corrupt' };
+    }
+}
+function takeLock(path, log, now) {
+    const leasePath = `${path}.lease`;
     const body = JSON.stringify({ pid: process.pid, boot: BOOT_ID, host: HOST_ID, startedAt: new Date().toISOString() });
     const create = (p) => {
         const fd = openSync(p, 'wx', 0o600);
@@ -76,7 +154,9 @@ function takeLock(path, log) {
             holder = JSON.parse(readFileSync(path, 'utf8'));
         }
         catch {
-            refuse(`${path} exists but is unreadable; remove it if no server is running on this state dir`);
+            // It may have disappeared (a concurrent close) as well as become unreadable: cover both so
+            // the refusal is never misleading.
+            refuse(`${path} disappeared or is unreadable; remove it if no server is running on this state dir`);
         }
         if (typeof holder.pid !== 'number' || !Number.isInteger(holder.pid) || holder.pid <= 0) {
             refuse(`${path} names no pid; remove it if no server is running on this state dir`);
@@ -86,12 +166,36 @@ function takeLock(path, log) {
             // space), so another host's lock is never taken over automatically.
             refuse(`locked by host ${typeof holder.host === 'string' ? holder.host : '(unknown)'} (pid ${holder.pid}); one container per state dir. If that host's server is gone, delete ${path} and start again`);
         }
-        if (holderAlive(holder.pid, holder.boot))
-            refuse(`locked by a running process (pid ${holder.pid}); one process per state dir`);
-        return holder.pid;
+        const lease = readLease(leasePath, now());
+        if (lease.kind === 'corrupt') {
+            refuse(`${leasePath} exists but is not a readable lease; remove it if no server is running on this state dir`);
+        }
+        if (lease.kind === 'aged' &&
+            lease.age <= LEASE_EXPIRY_MS &&
+            // One exception to the veto: a lock naming THIS process's own pid from an earlier boot.
+            // That "holder" is a dead previous run - a live pid is unique, so a live process cannot be
+            // this process - and its fresh lease is necessarily stale. The exception is what an OOM or
+            // SIGKILL restart needs: the pre-change V5 case took such a lock over at once (S2-m1).
+            !(holder.pid === process.pid && holder.boot !== BOOT_ID)) {
+            // The holder wrote its lease within the last refresh window: it is active, whatever its pid
+            // says. A fresh lease vetoes the takeover, full stop (a live holder is never taken).
+            refuse(`locked by a running process (pid ${holder.pid}); its lease is ${lease.age} ms old — one process per state dir`);
+        }
+        if (holderAlive(holder.pid, holder.boot)) {
+            // The pid answers (or is this process's own from this boot). No fresh lease:
+            // - no lease file at all: a pre-lease (0.6.0) holder — refuse, as before;
+            // - an expired lease: the real holder cannot have been active for three refresh cycles; the
+            //   live pid is a recycled one (a container replacement reset the pid namespace, issue #55).
+            if (lease.kind !== 'aged')
+                refuse(`locked by a running process (pid ${holder.pid}); one process per state dir`);
+            return { pid: holder.pid, boot: holder.boot, reason: 'lease_expired' };
+        }
+        return { pid: holder.pid, boot: holder.boot, reason: 'dead_pid' };
     };
-    if (tryCreate())
-        return;
+    if (tryCreate()) {
+        writeLease(leasePath, now());
+        return undefined;
+    }
     deadHolder();
     const takeover = `${path}.takeover`;
     try {
@@ -103,19 +207,31 @@ function takeLock(path, log) {
         refuse(`another process is taking over the lock (${takeover}); remove it if no server is starting on this state dir`);
     }
     try {
-        // Under the takeover file: re-check that the lock still names a dead process, then replace it.
-        let dead;
+        // Under the takeover file: re-run the whole verdict (a fresh lease or a live holder that
+        // started meanwhile wins), then replace the stale lock.
+        let verdict;
         if (existsSync(path)) {
-            dead = deadHolder();
+            verdict = deadHolder();
             unlinkSync(path);
         }
         if (!tryCreate())
             refuse('another process took the lock during the takeover');
-        log.warn('state lock taken over from a dead process', { deadPid: dead });
+        writeLease(leasePath, now());
+        if (verdict !== undefined) {
+            const detail = { deadPid: verdict.pid, deadBoot: verdict.boot };
+            if (verdict.reason === 'lease_expired') {
+                log.warn("state lock taken over: the holder's lease is expired and a recycled pid answers at its number", detail);
+            }
+            else {
+                log.warn('state lock taken over from a dead process', detail);
+            }
+            return { deadPid: verdict.pid, ...(typeof verdict.boot === 'string' ? { deadBoot: verdict.boot } : {}), reason: verdict.reason };
+        }
     }
     finally {
         unlinkSync(takeover);
     }
+    return undefined;
 }
 /**
  * This process's boot identity, written into the lock (pre-release V5). A lock naming this
@@ -266,7 +382,8 @@ export function openStateStore(dir, opts) {
     if ((st.mode & LOOSE_MODE) !== 0)
         refuse(`${dir} must be mode 0700 (it holds plans, the ledger and the audit log)`);
     const lockPath = join(dir, 'lock');
-    takeLock(lockPath, log);
+    const leasePath = join(dir, 'lock.lease');
+    const takeover = takeLock(lockPath, log, now);
     const key = stateKey(join(dir, 'state.key'));
     const planKey = Buffer.from(hkdfSync('sha256', key, Buffer.alloc(0), 'iit-mcp-autotask plan encryption', 32));
     const tenantKey = Buffer.from(hkdfSync('sha256', key, Buffer.alloc(0), 'iit-mcp-autotask tenant id', 32));
@@ -306,7 +423,35 @@ export function openStateStore(dir, opts) {
     const killFile = opts.killFile ?? join(dir, 'KILL');
     let applyQueue = Promise.resolve();
     let closed = false;
-    return {
+    // The holder's heartbeat (issue #55): rewrite the lease every LEASE_REFRESH_MS while we hold
+    // the lock. The timer self-stops only when the lock is LOST (deleted or replaced) — we must not
+    // keep a lease fresh that now belongs to the successor (a third taker would see it and refuse
+    // the successor's takeover). A transient UNREADABLE lock (EACCES, EIO, EMFILE) skips the beat
+    // and keeps the timer alive: one transient read error must not kill the heartbeat of a healthy
+    // holder, or the holder would be taken over once its lease went stale (S2-B1). A failed lease
+    // write (ENOSPC, a rename failure) is logged, not thrown: the process must not die of an
+    // uncaughtException — a persistently failing heartbeat degrades to the normal dead-pid /
+    // expired-lease recovery instead.
+    const leaseTimer = setInterval(() => {
+        const st = lockState(lockPath);
+        if (st === 'lost') {
+            clearInterval(leaseTimer);
+            return;
+        }
+        if (st === 'unknown')
+            return; // transient: skip this beat, try again next cycle
+        try {
+            writeLease(leasePath, now());
+        }
+        catch (err) {
+            log.warn('the lease heartbeat write failed; the lock may be taken over once its lease is stale', {
+                file: 'lock.lease',
+                error: String(err?.message ?? err),
+            });
+        }
+    }, LEASE_REFRESH_MS);
+    leaseTimer.unref();
+    const store = {
         dir,
         tenantId: (identity) => `tnt_${createHmac('sha256', tenantKey).update(canonicalJson(identity)).digest('hex')}`,
         newHandle: handle,
@@ -371,12 +516,56 @@ export function openStateStore(dir, opts) {
             return hit?.created === undefined ? undefined : { companyIds: hit.created.companyIds };
         },
         audit(event, at) {
+            // The store is the single writer of the chain: once this process no longer holds the lock,
+            // the chain belongs to the successor, and appending here would fork it permanently (every
+            // later boot logs a false tamper error). A forked chain is worse than a missing line, so a
+            // stale head is never appended: the line is skipped and the current head returned, which
+            // keeps the designed refusal envelopes intact — the blocked preview/apply paths audit
+            // precisely because they are blocked (the lock lost or unreadable). The loud failure for
+            // an in-flight completed apply stays with the explicit re-check in write.ts. The
+            // lock_takeover line is safe under this guard — it is written by the NEW holder while it
+            // holds the lock.
+            if (lockState(lockPath) !== 'held') {
+                log.warn('the state lock is not held just now (lost or unreadable); the audit line was not appended (a forked chain is worse than a missing line)', {
+                    file: 'audit.jsonl',
+                    event: event.event,
+                });
+                return head;
+            }
             const line = { at: new Date(at).toISOString(), ...event, prev: head };
             const hash = auditHash(head, line);
             appendLine(auditFd, { ...line, hash });
             head = hash;
             return hash;
         },
+        lockInfo() {
+            const out = { held: lockState(lockPath) === 'held' };
+            let lock;
+            try {
+                lock = JSON.parse(readFileSync(lockPath, 'utf8'));
+            }
+            catch {
+                return out; // the lock is gone or unreadable: no holder facts to report
+            }
+            if (typeof lock.pid === 'number') {
+                out.holder = {
+                    pid: lock.pid,
+                    ...(typeof lock.boot === 'string' ? { boot: lock.boot } : {}),
+                    ...(typeof lock.host === 'string' ? { host: lock.host } : {}),
+                };
+            }
+            if (typeof lock.startedAt === 'string') {
+                const started = Date.parse(lock.startedAt);
+                if (Number.isFinite(started))
+                    out.ageMs = Math.max(0, now() - started);
+            }
+            const lease = readLease(leasePath, now());
+            if (lease.kind === 'aged') {
+                out.leaseAgeMs = lease.age;
+                out.leaseExpired = lease.age > LEASE_EXPIRY_MS;
+            }
+            return out;
+        },
         // Writes also stop when this process no longer holds the state lock (deleted or replaced at
         // runtime): another process may be writing to the same ledger (review F7).
         blocked() {
@@ -408,16 +597,33 @@ export function openStateStore(dir, opts) {
             if (closed)
                 return;
             closed = true;
+            clearInterval(leaseTimer);
             closeSync(ledgerFd);
             closeSync(auditFd);
             try {
-                if (lockState(lockPath) === 'held')
+                if (lockState(lockPath) === 'held') {
                     unlinkSync(lockPath);
+                    unlinkSync(leasePath);
+                }
             }
             catch {
                 // The lock is gone or unreadable: nothing of ours to release.
             }
         },
     };
+    // The takeover is part of the hash chain, never a side file (issue #55): one chained line,
+    // written now that the audit descriptor is open.
+    if (takeover !== undefined) {
+        store.audit({
+            event: 'lock_takeover',
+            principal: 'system',
+            op: 'state.lock',
+            decision: 'takeover',
+            reasons: [takeover.reason],
+            deadPid: takeover.deadPid,
+            ...(takeover.deadBoot !== undefined ? { deadBoot: takeover.deadBoot } : {}),
+        }, now());
+    }
+    return store;
 }
 //# sourceMappingURL=store.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-autotask",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "MCP server for the Autotask (Datto) PSA domain, built on the node-autotask SDK",
   "license": "MIT",
   "author": "Max Soukhomlinov",

package/server.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-autotask",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "MCP server for the Autotask (Datto) PSA API, powered by the node-autotask SDK",
   "mcpProtocolBaseline": "2026-07-28",
   "legacyProtocolFallback": "2025-11-25",

package/skills/contract-profitability.md

@@ -6,7 +6,7 @@ profile: readonly
 description: Monthly P&L of one contract: revenue, labour and recurring cost, profit, margin, coverage gaps and data-quality warnings.
 when_not_to_use: unbilled work of a company (unbilled-work-review); the contract record alone (autotask_contract_full_profile)
 ops: ["autotask_query:contracts.query", "autotask_read:contracts.profitability", "autotask_fetch_many:operations.fetchByIds"]
-inputs: {"type": "object", "required": ["contract", "dateFrom", "dateTo"], "properties": {"contract": {"type": ["string", "integer"], "description": "Contract name or numeric id"}, "dateFrom": {"type": "string", "description": "YYYY-MM-DD window start"}, "dateTo": {"type": "string", "description": "YYYY-MM-DD window end, at most 36 months after dateFrom"}}}
+inputs: {"type": "object", "required": ["contract"], "properties": {"contract": {"type": ["string", "integer"], "description": "Contract name or numeric id"}, "dateFrom": {"type": "string", "description": "YYYY-MM-DD window start. Pass both dateFrom and dateTo, or neither: with neither, the server defaults the window to the last full calendar month (UTC); exactly one is refused (needs_input)."}, "dateTo": {"type": "string", "description": "YYYY-MM-DD window end, at most 36 months after dateFrom (the both-or-neither rule of dateFrom applies)"}}}
 outcomes: ["ok", "needs_input", "ambiguous", "error"]
 hazards: ["money is in the internal currency", "annual units count in their start month"]
 related: ["unbilled-work-review"]
@@ -17,12 +17,13 @@ eval: evals/contract-profitability.json
 
 ## Inputs
 
-- `contract` (name or id), `dateFrom` and `dateTo` (YYYY-MM-DD) from the caller's task. A missing input is `needs_input` for it; the usual window is the 12 calendar months ending today.
+- `contract` (name or id) from the caller's task; a missing `contract` is `needs_input` for it.
+- The window: `dateFrom` and `dateTo` (YYYY-MM-DD), both or neither. With neither, the read path defaults the window to the last full calendar month (UTC) and names it in the result's `windowNote`; exactly one side is refused (`needs_input` for both days). The usual 12-month window is passed as both days.
 
 ## Steps
 
 1. A name: `autotask_query {resource: "contracts", filter: [{field: "contractName", op: "contains", value: "<contract>"}], limit: 10}`. One row continues with its `id`; several return `ambiguous` with their ids and names; none returns `needs_input`.
-2. `autotask_read {operation: "contracts.profitability", args: [<id>, {dateFrom: "<dateFrom>", dateTo: "<dateTo>"}]}`. Options: `includeRows: true` adds raw rows (much larger), `labourCostMethod`, `labourRatePerHour` (needed with `provided`), `externalMonthlyCosts` (caller tooling costs per month), `limit` (per part, default 50).
+2. `autotask_read {operation: "contracts.profitability", args: [<id>, {dateFrom: "<dateFrom>", dateTo: "<dateTo>"}]}` (both days, or omit both for the default last full calendar month, UTC). Options: `includeRows: true` adds raw rows (much larger), `labourCostMethod`, `labourRatePerHour` (needed with `provided`), `externalMonthlyCosts` (caller tooling costs per month), `limit` (per part, default 50).
 3. Name the tickets of `highest_cost_tickets` and the warnings: `autotask_fetch_many {items: [{resource: "tickets", id: <ticketId>, fields: ["id", "ticketNumber"]}, ...]}`.
 
 ## Guardrails
@@ -38,6 +39,7 @@ Profit equals revenue minus `total_cost` for each month you report; the contract
 ## Failure and rollback
 
 - `INPUT_INVALID` (window inverted or over 36 months): fix the dates and call again.
+- `needs_input` for the window (exactly one of `dateFrom`/`dateTo`): pass both days, or neither (the default last full calendar month, UTC).
 - `TARGET_NOT_FOUND` for the contract: `needs_input` for `contract`.
 - Other `error`: return it unchanged.