@p4code/cli 0.6.3 → 0.6.4

package/dist/bin.mjs

@@ -266,7 +266,7 @@ const make$122 = () => {
 const layer$123 = Layer.sync(NetService, make$122);
 //#endregion
 //#region package.json
-var version$1 = "0.6.3";
+var version$1 = "0.6.4";
 //#endregion
 //#region src/config.ts
 /**
@@ -12648,6 +12648,44 @@ const TicketResolveResult = Schema$1.Struct({
 	*/
 	description: Schema$1.optional(TrimmedNonEmptyString)
 });
+/** One link filed alongside a comment: the proof, and what to call it. */
+const TicketCommentAttachment = Schema$1.Struct({
+	url: TrimmedNonEmptyString.pipe(Schema$1.annotateEncoded({ description: "Publicly reachable URL of the proof to file against the ticket. Local file paths cannot be attached." })),
+	title: Schema$1.optional(TrimmedNonEmptyString.pipe(Schema$1.annotateEncoded({ description: "Label for the link. Defaults to the URL itself." })))
+});
+/**
+* One comment on a ticket, with the links that belong to it.
+*
+* Commenting rather than editing: closeout writes what happened, and the
+* description belongs to whoever filed the ticket. The attachments ride along
+* because proof without the sentence explaining it is an orphan link.
+*/
+const TicketCommentInput = Schema$1.Struct({
+	reference: TrimmedNonEmptyString.pipe(Schema$1.annotateEncoded({ description: "The ticket as it was written: an identifier like MOBILE-12241, or a tracker URL." })),
+	body: TrimmedNonEmptyString.pipe(Schema$1.annotateEncoded({ description: "The comment, in Markdown, exactly as it should appear on the ticket." })),
+	attachments: Schema$1.optional(Schema$1.Array(TicketCommentAttachment))
+});
+/** A link the tracker would not file, and the sentence explaining why. */
+const TicketCommentAttachmentFailure = Schema$1.Struct({
+	url: TrimmedNonEmptyString,
+	detail: Schema$1.String
+});
+const TicketCommentResult = Schema$1.Struct({
+	externalRef: TaskExternalRef,
+	/** Absent when the tracker filed the comment and reported no link to it. */
+	commentUrl: Schema$1.optional(TrimmedNonEmptyString),
+	/** The attachments that landed, in the order they were asked for. */
+	attachedUrls: Schema$1.Array(TrimmedNonEmptyString),
+	/**
+	* The attachments that did not land.
+	*
+	* Reported rather than thrown, because the comment is already on the ticket
+	* by the time a link can fail: a caller told only "it failed" retries the
+	* whole call and files the comment twice. With this it can retry the links
+	* alone, or say in the thread which proof is missing.
+	*/
+	failedAttachments: Schema$1.Array(TicketCommentAttachmentFailure)
+});
 /**
 * Why a reference could not be turned into a ticket.
 *
@@ -30894,6 +30932,34 @@ Layer.succeed(ClaudeMcpFiles, {
 const PROBE_CACHE_TTL_MS = 300 * 1e3;
 /** An authorize URL nobody returned from within this window is abandoned. */
 const PENDING_FLOW_TTL_MS = 600 * 1e3;
+/**
+* The two answers that mean the credential, not the request, was refused.
+*
+* The same pair `McpToolClient` reports as "the server rejected p4code's
+* credentials": 401 for a token the server will not accept, 403 for one it
+* accepts and will not act on. Both leave the session with a server it cannot
+* use, so both take the one refresh and, failing that, the sign-in.
+*/
+const credentialsRefused = (status) => status === 401 || status === 403;
+/**
+* Whether a token endpoint's answer means the grant itself is gone.
+*
+* RFC 6749 gives a retired or rejected refresh token one spelling: 400 with
+* `error: "invalid_grant"`. The other 400s - `invalid_request`,
+* `unsupported_grant_type`, `invalid_scope` - are complaints about the request
+* this code sent, and erasing the user's credential over a malformed request
+* of ours would charge them a sign-in for a bug. 401 and 403 stay terminal:
+* the client credential itself was refused, and no retry of this shape fixes
+* that. Everything else - 429, a 5xx, whatever a proxy invents - is the server
+* having a bad minute.
+*/
+const terminalRefreshAnswer = (status, json) => {
+	if (status === 401 || status === 403) return true;
+	if (status !== 400) return false;
+	return (typeof json === "object" && json !== null ? json["error"] : void 0) === "invalid_grant";
+};
+/** Why one refresh attempt failed, and whether the stored grant survives it. */
+var RefreshFailure = class extends Data.TaggedError("RefreshFailure") {};
 /** A token this close to expiry is refreshed rather than handed to a session. */
 const TOKEN_EXPIRY_MARGIN_MS = 60 * 1e3;
 /** Outbound discovery, registration and token requests all use this cap. */
@@ -31005,6 +31071,7 @@ const make$109 = Effect.gen(function* () {
 	const crypto = yield* Crypto.Crypto;
 	const pendingFlows = yield* Ref.make(/* @__PURE__ */ new Map());
 	const probeCache = yield* Ref.make(/* @__PURE__ */ new Map());
+	const tokenVerdicts = yield* Ref.make(/* @__PURE__ */ new Map());
 	const redirectUri = `http://127.0.0.1:${config.port}${OAUTH_CALLBACK_PATH}`;
 	const nowMillis = Effect.map(DateTime.now, DateTime.toEpochMillis);
 	const readRecord = Effect.fn("McpOAuth.readRecord")(function* (server) {
@@ -31036,26 +31103,28 @@ const make$109 = Effect.gen(function* () {
 	* does — while answering the initialize POST with the 401 challenge this
 	* probe exists to see.
 	*/
+	const initializeRequest = (registration, accessToken) => HttpClientRequest.bodyJsonUnsafe(HttpClientRequest.setHeaders(HttpClientRequest.post(registration.url), {
+		...registration.headers,
+		...accessToken === void 0 ? {} : { authorization: `Bearer ${accessToken}` },
+		accept: "application/json, text/event-stream"
+	}), {
+		jsonrpc: "2.0",
+		id: 0,
+		method: "initialize",
+		params: {
+			protocolVersion: MCP_PROBE_PROTOCOL_VERSION,
+			capabilities: {},
+			clientInfo: {
+				name: "p4code",
+				version: "0.0.0"
+			}
+		}
+	});
 	const probe = Effect.fn("McpOAuth.probe")(function* (registration) {
 		const now = yield* nowMillis;
 		const cached = (yield* Ref.get(probeCache)).get(registration.url);
 		if (cached !== void 0 && now - cached.at < PROBE_CACHE_TTL_MS) return cached;
-		const verdict = yield* http.execute(HttpClientRequest.bodyJsonUnsafe(HttpClientRequest.setHeaders(HttpClientRequest.post(registration.url), {
-			...registration.headers,
-			accept: "application/json, text/event-stream"
-		}), {
-			jsonrpc: "2.0",
-			id: 0,
-			method: "initialize",
-			params: {
-				protocolVersion: MCP_PROBE_PROTOCOL_VERSION,
-				capabilities: {},
-				clientInfo: {
-					name: "p4code",
-					version: "0.0.0"
-				}
-			}
-		})).pipe(Effect.timeout(OAUTH_REQUEST_TIMEOUT_MS), Effect.map((response) => {
+		const verdict = yield* http.execute(initializeRequest(registration)).pipe(Effect.timeout(OAUTH_REQUEST_TIMEOUT_MS), Effect.map((response) => {
 			const challengeHeader = response.headers["www-authenticate"];
 			const challenge = response.status === 401 && challengeHeader !== void 0 ? parseWwwAuthenticate(challengeHeader) : void 0;
 			return {
@@ -31082,12 +31151,53 @@ const make$109 = Effect.gen(function* () {
 		next.delete(url);
 		return next;
 	});
+	/**
+	* Ask the server whether the token this machine holds still works.
+	*
+	* `probe` cannot answer this. It asks without credentials, so its 401 is the
+	* one every protected server sends and says nothing about the token sitting
+	* in the record. A token revoked at the other end, or issued for a workspace
+	* the user has since left, stays well inside its stored expiry and is
+	* refused on every call - the state this catches.
+	*
+	* Unreachable counts as usable, exactly as `probe` treats it: a network
+	* fault is not a revocation, and signing someone out of a server that is
+	* merely down helps nobody. Only a real answer is remembered.
+	*/
+	const validateToken = Effect.fn("McpOAuth.validateToken")(function* (registration, accessToken) {
+		const now = yield* nowMillis;
+		const cached = (yield* Ref.get(tokenVerdicts)).get(registration.name);
+		if (cached !== void 0 && cached.accessToken === accessToken) {
+			if (!cached.accepted) return false;
+			if (now - cached.at < PROBE_CACHE_TTL_MS) return true;
+		}
+		const answered = yield* http.execute(initializeRequest(registration, accessToken)).pipe(Effect.timeout(OAUTH_REQUEST_TIMEOUT_MS), Effect.map((response) => Option.some(!credentialsRefused(response.status))), Effect.orElseSucceed(() => Option.none()));
+		if (Option.isNone(answered)) return true;
+		yield* Ref.update(tokenVerdicts, (cache) => {
+			const next = new Map(cache);
+			next.set(registration.name, {
+				accessToken,
+				at: now,
+				accepted: answered.value
+			});
+			return next;
+		});
+		return answered.value;
+	});
+	/** Whether the server has refused the exact token the record still holds. */
+	const rejectedAlready = (server, accessToken) => Effect.map(Ref.get(tokenVerdicts), (cache) => {
+		const verdict = cache.get(server);
+		return verdict !== void 0 && verdict.accessToken === accessToken && !verdict.accepted;
+	});
 	const statusFor = (registration) => Effect.gen(function* () {
 		const record = yield* readRecord(registration.name);
-		if (Option.isSome(record) && record.value.tokens !== void 0) return Option.some({
-			required: true,
-			connected: true
-		});
+		if (Option.isSome(record) && record.value.tokens !== void 0) {
+			const rejected = yield* rejectedAlready(registration.name, record.value.tokens.accessToken);
+			return Option.some({
+				required: true,
+				connected: !rejected
+			});
+		}
 		if ((yield* probe(registration)).requiresAuth || Option.isSome(record)) return Option.some({
 			required: true,
 			connected: false
@@ -31262,6 +31372,24 @@ const make$109 = Effect.gen(function* () {
 		ok: false,
 		detail: "The sign-in failed. See the server log."
 	}))));
+	/**
+	* Drop the tokens the server will not accept, keeping the client
+	* registration so the sign-in that follows skips re-registration.
+	*
+	* Compare-and-delete rather than a blind write, because two sessions can
+	* resolve the same server at once. The loser of that race spends a refresh
+	* token the winner has already rotated, is told `invalid_grant`, and would
+	* otherwise erase the credential the winner just stored - turning a refresh
+	* that worked into a sign-in prompt. A record whose access token has moved on
+	* belongs to somebody else's successful refresh and is left alone.
+	*/
+	const forgetTokens = Effect.fn("McpOAuth.forgetTokens")(function* (server, refusedAccessToken) {
+		const current = yield* readRecord(server);
+		if (Option.isNone(current)) return;
+		if (current.value.tokens?.accessToken !== refusedAccessToken) return;
+		const { tokens: _refused, ...rest } = current.value;
+		yield* writeRecord(server, rest);
+	});
 	const disconnect = (name) => Effect.gen(function* () {
 		const record = yield* readRecord(name);
 		if (Option.isNone(record)) return;
@@ -31279,9 +31407,15 @@ const make$109 = Effect.gen(function* () {
 			...record.clientSecret === void 0 ? {} : { client_secret: record.clientSecret },
 			...record.resource === void 0 ? {} : { resource: record.resource }
 		}));
-		if (status !== 200) return yield* Effect.fail(`status ${status}`);
+		if (status !== 200) return yield* Effect.fail(new RefreshFailure({
+			terminal: terminalRefreshAnswer(status, json),
+			detail: `status ${status}`
+		}));
 		const decoded = decodeTokenResponse(json);
-		if (decoded._tag !== "Success") return yield* Effect.fail("unexpected shape");
+		if (decoded._tag !== "Success") return yield* Effect.fail(new RefreshFailure({
+			terminal: false,
+			detail: "unexpected shape"
+		}));
 		const response = decoded.value;
 		const now = yield* nowMillis;
 		const tokens = {
@@ -31300,9 +31434,16 @@ const make$109 = Effect.gen(function* () {
 		if (Option.isNone(record) || record.value.tokens === void 0) return Option.none();
 		const tokens = record.value.tokens;
 		const now = yield* nowMillis;
-		if (!(tokens.expiresAt !== void 0 && now >= tokens.expiresAt - TOKEN_EXPIRY_MARGIN_MS)) return Option.some(tokens.accessToken);
-		if (tokens.refreshToken === void 0) return Option.none();
-		return yield* refreshTokens(registration.name, record.value, tokens.refreshToken).pipe(Effect.map(Option.some), Effect.catchCause((cause) => Effect.logWarning("mcp oauth refresh failed", {
+		if (!(tokens.expiresAt !== void 0 && now >= tokens.expiresAt - TOKEN_EXPIRY_MARGIN_MS) && (yield* validateToken(registration, tokens.accessToken))) return Option.some(tokens.accessToken);
+		if (tokens.refreshToken === void 0) {
+			yield* forgetTokens(registration.name, tokens.accessToken);
+			return Option.none();
+		}
+		return yield* refreshTokens(registration.name, record.value, tokens.refreshToken).pipe(Effect.map(Option.some), Effect.catchTag("RefreshFailure", (failure) => Effect.logWarning("mcp oauth refresh failed", {
+			server: registration.name,
+			detail: failure.detail,
+			terminal: failure.terminal
+		}).pipe(Effect.andThen(failure.terminal ? forgetTokens(registration.name, tokens.accessToken) : Effect.void), Effect.as(Option.none()))), Effect.catchCause((cause) => Effect.logWarning("mcp oauth refresh could not be attempted", {
 			cause,
 			server: registration.name
 		}).pipe(Effect.as(Option.none()))));
@@ -60994,8 +61135,15 @@ const FUSION_SAFETY_KERNEL = [
 * `task_propose` is deliberately absent: it tells its caller to stop and wait
 * for the user, and a supervisor that waits is one the builder sits idle
 * behind. Asking the user is what `ask_user_question` is for.
+*
+* `thread_spawn` is here because starting a thread is a coordination act: when
+* the authorized work needs a separate checkout, a different provider or its
+* own pair, the half that owns the plan is the half that decides. It stays in
+* the builder's denial list, so the pair still has exactly one thread that can
+* open new work.
 */
 const FUSION_SUPERVISOR_P4_TOOLS = /* @__PURE__ */ new Set([
+	"thread_spawn",
 	"thread_watch_review",
 	"thread_watch_events",
 	"thread_evidence_report",
@@ -61013,7 +61161,8 @@ const FUSION_SUPERVISOR_P4_TOOLS = /* @__PURE__ */ new Set([
 	"task_list",
 	"task_create",
 	"task_update",
-	"ticket_resolve"
+	"ticket_resolve",
+	"ticket_comment"
 ]);
 /**
 * What the builder half must not reach.
@@ -61023,8 +61172,9 @@ const FUSION_SUPERVISOR_P4_TOOLS = /* @__PURE__ */ new Set([
 * those should reach it without an edit here. What it must never have is the
 * pair's own machinery - spawning threads, creating pairs, advising, answering
 * its own gate - the phase plan, which the supervisor owns outright, plus
-* task-board mutation. Both roles may read paired history and task-relevant
-* external evidence; only Supervisor writes review reports and the phase plan.
+* task-board mutation and the tracker comment that closes a task. Both roles
+* may read paired history and task-relevant external evidence; only Supervisor
+* writes review reports and the phase plan.
 *
 * Both roles retain `thread_pair_detach` as their way out. Its handler limits
 * detaching to a pair containing the caller whose other thread this session
@@ -61046,6 +61196,7 @@ const FUSION_BUILDER_DENIED_P4_TOOLS = /* @__PURE__ */ new Set([
 	"task_create",
 	"task_update",
 	"task_propose",
+	"ticket_comment",
 	"memory_append"
 ]);
 /**
@@ -63641,6 +63792,7 @@ const P4CODE_MCP_TOOL_NAMES = [
 	"thread_spawn",
 	"thread_watch_events",
 	"thread_watch_review",
+	"ticket_comment",
 	"ticket_resolve"
 ];
 /** The catalogue as the adapters read it. */
@@ -123186,6 +123338,9 @@ const callMcpTool = Effect.fn("McpToolClient.callMcpTool")(function* (input) {
 * name that drifts between them fails at runtime with a shrug from the server.
 */
 const LINEAR_GET_ISSUE_TOOL = "get_issue";
+/** The write half: one comment, and the links filed beside it. */
+const LINEAR_SAVE_COMMENT_TOOL = "save_comment";
+const LINEAR_CREATE_ATTACHMENT_TOOL = "create_attachment";
 /** Why a Linear call could not be made, in terms a person can act on. */
 var LinearUnavailable = class extends Schema$1.TaggedErrorClass()("LinearUnavailable", {
 	reason: Schema$1.Literals([
@@ -123403,10 +123558,11 @@ const graphqlRequest = Effect.fn("tracker/graphqlRequest")(function* (input) {
 /**
 * Linear over its own GraphQL API, wearing the MCP tool vocabulary.
 *
-* This speaks the same three "tools" the Linear MCP server offers -
-* `list_issues`, `get_issue`, `save_issue` - and answers in the same row
-* shapes, so `LinearTasks` and the resolver cannot tell which transport
-* served them. That is the point: the MCP server remains the fallback, and a
+* This speaks the same "tools" the Linear MCP server offers - `list_issues`,
+* `get_issue`, `save_issue`, `list_comments`, `save_comment` and
+* `create_attachment` - and answers in the same row shapes, so `LinearTasks`,
+* the resolver and the closeout path cannot tell which transport served
+* them. That is the point: the MCP server remains the fallback, and a
 * consumer that could tell the two apart would need two code paths.
 *
 * The one real difference is hidden here: the MCP tools accept names where
@@ -123476,6 +123632,29 @@ const toIssueRow = (node) => {
 		parentId: parent?.["id"]
 	};
 };
+/** Everything a closeout comment's caller renders back: who, when, and where. */
+const COMMENT_SELECTION = `
+  id
+  body
+  url
+  createdAt
+  user { id name displayName }
+`;
+/** An attachment as Linear files it: a link with a label, against one issue. */
+const ATTACHMENT_SELECTION = `
+  id
+  url
+  title
+  subtitle
+`;
+/** One comment node, flattened the way `toIssueRow` flattens an issue. */
+const toCommentRow = (node) => ({
+	id: node["id"],
+	body: node["body"],
+	url: node["url"],
+	createdAt: node["createdAt"],
+	user: node["user"]
+});
 /** A case-insensitive equality filter over the ways a person is named. */
 const personFilter = (person) => ({ or: [
 	{ displayName: { eqIgnoreCase: person } },
@@ -123648,6 +123827,107 @@ const makeLinearApiTransport = Effect.gen(function* () {
 		});
 		return toIssueRow(issue);
 	});
+	/**
+	* The issue's own id, from whatever a caller had - an identifier, a URL's
+	* tail, or the id itself.
+	*
+	* The comment and attachment mutations take the UUID only, while every
+	* caller here starts from what a person typed. One lookup closes that gap
+	* and gives the "no such issue" sentence a name to report.
+	*/
+	const resolveIssueNodeId = (apiKey, reference) => Effect.gen(function* () {
+		const response = yield* request(apiKey, `query($id: String!) { issue(id: $id) { id } }`, { id: reference });
+		const issue = yield* readEntity(response, "issue");
+		const id = asString(issue?.["id"]);
+		if (id === void 0) return yield* new LinearUnavailable({
+			reason: "failed",
+			detail: `Linear has no issue "${reference}".`
+		});
+		return id;
+	});
+	const listComments = (apiKey, args) => Effect.gen(function* () {
+		const reference = asString(args["issueId"]) ?? asString(args["id"]);
+		if (reference === void 0) return yield* new LinearUnavailable({
+			reason: "failed",
+			detail: "list_comments needs an issueId."
+		});
+		const response = yield* request(apiKey, `query($id: String!, $first: Int!) {
+          issue(id: $id) {
+            comments(first: $first) {
+              nodes { ${COMMENT_SELECTION} }
+            }
+          }
+        }`, {
+			id: reference,
+			first: typeof args["limit"] === "number" ? args["limit"] : 50
+		});
+		const issue = yield* readEntity(response, "issue");
+		if (issue === void 0) return yield* new LinearUnavailable({
+			reason: "failed",
+			detail: `Linear has no issue "${reference}".`
+		});
+		return { comments: asArray(asRecord$5(issue["comments"])?.["nodes"]).map(asRecord$5).filter((node) => node !== void 0).map(toCommentRow) };
+	});
+	const saveComment = (apiKey, args) => Effect.gen(function* () {
+		const reference = asString(args["issueId"]) ?? asString(args["id"]);
+		const body = typeof args["body"] === "string" ? args["body"] : void 0;
+		if (reference === void 0 || body === void 0) return yield* new LinearUnavailable({
+			reason: "failed",
+			detail: "save_comment needs an issueId and a body."
+		});
+		const issueNodeId = yield* resolveIssueNodeId(apiKey, reference);
+		const parentId = asString(args["parentId"]);
+		const response = yield* request(apiKey, `mutation($input: CommentCreateInput!) {
+          commentCreate(input: $input) { comment { ${COMMENT_SELECTION} } }
+        }`, { input: {
+			issueId: issueNodeId,
+			body,
+			...parentId === void 0 ? {} : { parentId }
+		} });
+		const payload = yield* readEntity(response, "commentCreate");
+		const comment = asRecord$5(payload?.["comment"]);
+		if (comment === void 0) return yield* new LinearUnavailable({
+			reason: "failed",
+			detail: response.errors.length > 0 ? response.errors.join("; ") : "Linear accepted the comment and returned nothing."
+		});
+		return toCommentRow(comment);
+	});
+	/**
+	* A link filed against an issue, which is every attachment this transport
+	* can make.
+	*
+	* Linear's own file upload is a signed-URL handshake followed by a PUT of
+	* the bytes, and nothing here has bytes to send: the proof a closeout links
+	* is already hosted somewhere. A caller holding a local file gets the same
+	* answer it would get from the MCP server's `create_attachment`, which also
+	* takes a URL.
+	*/
+	const createAttachment = (apiKey, args) => Effect.gen(function* () {
+		const reference = asString(args["issueId"]) ?? asString(args["id"]);
+		const url = asString(args["url"]);
+		if (reference === void 0 || url === void 0) return yield* new LinearUnavailable({
+			reason: "failed",
+			detail: "create_attachment needs an issueId and a url."
+		});
+		const issueNodeId = yield* resolveIssueNodeId(apiKey, reference);
+		const title = asString(args["title"]);
+		const subtitle = asString(args["subtitle"]);
+		const response = yield* request(apiKey, `mutation($input: AttachmentCreateInput!) {
+          attachmentCreate(input: $input) { attachment { ${ATTACHMENT_SELECTION} } }
+        }`, { input: {
+			issueId: issueNodeId,
+			url,
+			title: title ?? url,
+			...subtitle === void 0 ? {} : { subtitle }
+		} });
+		const payload = yield* readEntity(response, "attachmentCreate");
+		const attachment = asRecord$5(payload?.["attachment"]);
+		if (attachment === void 0) return yield* new LinearUnavailable({
+			reason: "failed",
+			detail: response.errors.length > 0 ? response.errors.join("; ") : "Linear accepted the attachment and returned nothing."
+		});
+		return attachment;
+	});
 	const isConfigured = secrets.read("linear").pipe(Effect.map((credential) => Option.isSome(credential)));
 	const call = (toolName, args) => Effect.gen(function* () {
 		const credential = yield* secrets.read("linear");
@@ -123660,6 +123940,9 @@ const makeLinearApiTransport = Effect.gen(function* () {
 			case "list_issues": return yield* listIssues(apiKey, args);
 			case "get_issue": return yield* getIssue(apiKey, args);
 			case "save_issue": return yield* saveIssue(apiKey, args);
+			case "list_comments": return yield* listComments(apiKey, args);
+			case "save_comment": return yield* saveComment(apiKey, args);
+			case "create_attachment": return yield* createAttachment(apiKey, args);
 			default: return yield* new LinearUnavailable({
 				reason: "failed",
 				detail: `The Linear API transport has no translation for "${toolName}".`
@@ -134245,22 +134528,27 @@ PreviewToolkit.toLayer(handlers$5);
 //#endregion
 //#region src/mcp/TicketResolver.ts
 var TicketResolver = class extends Context.Service()("@p4code/cli/mcp/TicketResolver") {};
+/**
+* The client's reasons map one-to-one except `failed`, which for a caller
+* here means "try again", not "fix your configuration".
+*/
+const toResolveError = (cause) => new TicketResolveError({
+	reason: cause.reason === "failed" ? "unavailable" : cause.reason,
+	detail: cause.detail
+});
 const stringField = (record, key) => {
 	const value = record[key];
 	return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
 };
 const make$12 = Effect.gen(function* () {
 	const linear = yield* LinearClient;
-	return { resolve: Effect.fn("TicketResolver.resolve")(function* (reference) {
+	const resolve = Effect.fn("TicketResolver.resolve")(function* (reference) {
 		const identifier = parseTicketReference(reference);
 		if (identifier === null) return yield* new TicketResolveError({
 			reason: "not_found",
 			detail: `"${reference}" does not look like a ticket reference.`
 		});
-		const issue = readOne(yield* linear.call(LINEAR_GET_ISSUE_TOOL, { id: identifier }).pipe(Effect.mapError((cause) => new TicketResolveError({
-			reason: cause.reason === "failed" ? "unavailable" : cause.reason,
-			detail: cause.detail
-		}))));
+		const issue = readOne(yield* linear.call(LINEAR_GET_ISSUE_TOOL, { id: identifier }).pipe(Effect.mapError(toResolveError)));
 		const url = issue === void 0 ? void 0 : stringField(issue, "url");
 		const title = issue === void 0 ? void 0 : stringField(issue, "title");
 		if (issue === void 0 || url === void 0 || title === void 0) return yield* new TicketResolveError({
@@ -134278,7 +134566,43 @@ const make$12 = Effect.gen(function* () {
 			title,
 			...description === void 0 ? {} : { description }
 		};
-	}) };
+	});
+	return {
+		resolve,
+		comment: Effect.fn("TicketResolver.comment")(function* (input) {
+			const ticket = yield* resolve(input.reference);
+			const identifier = ticket.externalRef.identifier;
+			const comment = readOne(yield* linear.call(LINEAR_SAVE_COMMENT_TOOL, {
+				issueId: identifier,
+				body: input.body
+			}).pipe(Effect.mapError(toResolveError)));
+			const commentUrl = comment === void 0 ? void 0 : stringField(comment, "url");
+			const attachedUrls = [];
+			const failedAttachments = [];
+			for (const attachment of input.attachments ?? []) {
+				const failure = yield* linear.call(LINEAR_CREATE_ATTACHMENT_TOOL, {
+					issueId: identifier,
+					url: attachment.url,
+					...attachment.title === void 0 ? {} : { title: attachment.title }
+				}).pipe(Effect.as(void 0), Effect.catch((cause) => Effect.logWarning("ticket attachment failed", {
+					ticket: identifier,
+					url: attachment.url,
+					detail: cause.detail
+				}).pipe(Effect.as(cause.detail))));
+				if (failure === void 0) attachedUrls.push(attachment.url);
+				else failedAttachments.push({
+					url: attachment.url,
+					detail: failure
+				});
+			}
+			return {
+				externalRef: ticket.externalRef,
+				...commentUrl === void 0 ? {} : { commentUrl },
+				attachedUrls,
+				failedAttachments
+			};
+		})
+	};
 });
 const layer$5 = Layer.effect(TicketResolver, make$12);
 //#endregion
@@ -134399,7 +134723,29 @@ const TicketResolveTool = Tool.make("ticket_resolve", {
 	failure: Schema$1.Union([TaskToolUnavailableError, TicketResolveError]),
 	dependencies: [McpInvocationContext, TicketResolver]
 }).annotate(Tool.Title, "Resolve a ticket").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, true);
-const TaskToolkit = Toolkit.make(TaskListTool, TaskGetTool, TaskCurrentTool, TaskCreateTool, TaskUpdateTool, TaskProposeTool, TicketResolveTool);
+/**
+* Writing one comment back to the ticket, through p4code's own transport.
+*
+* Separate from `ticket_resolve` because it writes, and on the task toolkit
+* for the same reason that one is: it is the tracker side of the work a board
+* row describes, under the one capability a session is granted.
+*
+* It exists because a provider's own tracker registration is not a transport
+* p4code controls - it can be absent, or hold a credential the tracker has
+* stopped accepting - while closeout is the moment that must not fail
+* silently. `LinearClient` picks the stored API key when there is one and the
+* registered MCP server otherwise, so this reaches the ticket whenever any
+* route to it exists. Both halves of a Fusion pair may call it; which half
+* should is the prompt's business, not the toolkit's.
+*/
+const TicketCommentTool = Tool.make("ticket_comment", {
+	description: "Comment on a tracker ticket by id or URL (e.g. MOBILE-12241, or a linear.app link), optionally filing links as attachments alongside it. Use it for an authorized closeout note or a requested ticket comment - never for progress chatter. Reaches the tracker through p4code's own credential, so it works when the session has no tracker server of its own. The comment is written as given: Markdown, and the caller's words. Attachments take publicly reachable URLs; a local file path cannot be filed. A link the tracker refuses comes back in failedAttachments with the reason - retry that link alone rather than the whole call, which would file the comment twice.",
+	parameters: TicketCommentInput,
+	success: TicketCommentResult,
+	failure: Schema$1.Union([TaskToolUnavailableError, TicketResolveError]),
+	dependencies: [McpInvocationContext, TicketResolver]
+}).annotate(Tool.Title, "Comment on a ticket").annotate(Tool.Readonly, false).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, false);
+const TaskToolkit = Toolkit.make(TaskListTool, TaskGetTool, TaskCurrentTool, TaskCreateTool, TaskUpdateTool, TaskProposeTool, TicketResolveTool, TicketCommentTool);
 //#endregion
 //#region src/mcp/toolkits/tasks/handlers.ts
 const nowIso$1 = Effect.map(DateTime.now, DateTime.formatIso);
@@ -134502,6 +134848,10 @@ const TaskToolkitHandlersLive = TaskToolkit.toLayer({
 		yield* requireTaskCapability();
 		return yield* (yield* TicketResolver).resolve(input.reference);
 	}),
+	ticket_comment: (input) => Effect.gen(function* () {
+		yield* requireTaskCapability();
+		return yield* (yield* TicketResolver).comment(input);
+	}),
 	task_propose: () => Effect.gen(function* () {
 		yield* requireTaskCapability();
 		return { awaitingConfirmation: true };